fix(v3.3.12): claude-use/claude-whoami resolve v3 subctl explicitly — survive v4 PATH collision

[webdevtodayjason]

Problem

The shell helpers (claude-use, claude-whoami, claude-accounts) called bare subctl config show / subctl accounts. Once the v4 subctl-chat-tui entry point landed at ~/.local/bin/subctl and that dir sorted ahead of ~/bin on the operator's interactive PATH, bare subctl resolved to v4, which doesn't dispatch v3 verbs — config show just prints v4 help and exits 0. The awk parser downstream found nothing, so:

• claude-use (no args) listed no profiles
• claude-use <alias> → "Unknown account"
• claude-whoami always said "custom"

Operator report: "I can't switch, I can't select, claude-use shows nothing."

Why it was masked

Claude Code's settings.json pins env.PATH with ~/bin first and no ~/.local/bin, so v3 won inside Claude Code — the break only reproduced in the interactive terminal (.zshrc prepends ~/.local/bin 3× ahead of ~/bin).

Fix

lib/migrate.sh bakes a _subctl_v3 resolver into the generated shell-aliases.sh and routes all four bare-subctl call sites (config show ×3, accounts ×1) through it, bypassing PATH. Mirrors the existing claude-teams shim, which already resolves its v3 sibling directly because v4 owns the bare subctl name.

The intentional bare-claude account guard is unchanged.

Verification

• Regenerated live ~/.config/subctl/shell-aliases.sh; diff = resolver + 4 substitutions only.
• Repro test with PATH=~/.local/bin:... (bare subctl → v4): sourcing the regenerated file makes claude-use list all 5 accounts, claude-use jason switch, claude-whoami resolve to claude-jason. Pre-fix all three failed.
• bash -n + zsh -n clean on generated output and generator.

Note: already-running shells must source ~/.zshrc or open a new terminal.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes
  • Fixed account management commands that failed when multiple versions of required system tools were installed on the same system. The affected functionality now operates consistently regardless of tool version conflicts or installation order. Re-source your active shell to apply the fix.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a4018d79-4e43-458a-8b85-4ec565a92c7b

📥 Commits

Reviewing files that changed from the base of the PR and between 6aa6d6d and 3186131.

📒 Files selected for processing (3)

• CHANGELOG.md
• VERSION
• lib/migrate.sh

Disabled knowledge base sources:

• Linear integration is disabled

You can enable these sources in your CodeRabbit configuration.

---

📝 Walkthrough

Walkthrough

This pull request fixes a PATH collision where subctl-chat-tui v4 installs a competing v4 binary at ~/.local/bin/subctl, shadowing the v3 dispatcher. The fix introduces an explicit v3-subctl resolver in generated shell aliases and routes claude-whoami, claude-accounts, and claude-use through it, with fallbacks to ensure consistency. Version is bumped to 3.3.12.

Changes

v3 subctl resolver fix

Layer / File(s)	Summary
v3 subctl resolver implementation lib/migrate.sh	Adds generated _SUBCTL_V3 variable and _subctl_v3() function that resolves to v3 dispatcher from repo root with fallbacks to $HOME/bin/subctl and command subctl.
Route shell aliases through v3 resolver lib/migrate.sh	Updates claude-whoami(), claude-accounts(), and claude-use() functions to invoke _subctl_v3 config show or _subctl_v3 accounts instead of bare subctl commands for config/account operations.
Release version and changelog VERSION, CHANGELOG.md	Version bumped to 3.3.12; changelog entry documents the PATH-collision fix, resolver routing, and notes that running shells must re-source to pick up regenerated functions.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~18 minutes

Possibly related PRs

• webdevtodayjason/subctl#38: Addresses the same v3/v4 PATH-collision issue using a different approach (bin shim wrappers) rather than generated shell-alias resolvers.

Poem

🐰 Hop, hop, the versions dance,
v3 and v4 in PATH's chance,
But now _subctl_v3 finds the way,
Through fallback chains, hooray, hooray!
Aliases resolve with grace so fine,
No more collisions on the line! ✨

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/v3.3.12-claude-use-v4-path-collision

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}