feat: override a CLI profile's binary per project and per run

[albi-bon]

Describe your idea

Let a project override the executable a CLI profile spawns, without duplicating the whole profile:

1. A binary field in [adapter] (and [adapter.dev|review|triage]) in policy.toml.
2. Per-run flags on run/sweep: --cli <profile> and --cli-binary <executable>.

Why is this needed?

Users who hold more than one subscription/profile for the same coding CLI invoke it under different names — e.g. a work account launched as cw and a personal one as claude, or two aliases used to split usage limits. Today bmad-loop always spawns CLIProfile.binary, which is fixed per profile.

The overlay in .bmad-loop/profiles/*.toml can express this, but only by copying the entire packaged profile to change one line. That copy then silently freezes everything else: bypass_args, [env] (CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN, CLAUDE_CODE_DISABLE_BACKGROUND_TASKS), seed_files, and env_fault_patterns stop tracking upstream. A user who forked claude.toml before #194 landed would never have received the transport-fault patterns. The cost of changing one field is permanent drift on eight others.

Choosing the account per run is also not expressible at all: policy.toml is project-scoped state, so switching accounts means editing a file rather than passing a flag — awkward when alternating profiles on the same repo.

How should it work?

The seam already exists and is simply unwired: both GenericAdapter.__init__ (adapters/generic.py:417) and OpencodeHttpAdapter.__init__ (adapters/opencode_http.py:389) already accept binary: str | None = None and do self.binary = binary or profile.binary. Nothing passes it — only probe-adapter --binary uses a parallel path.

Proposed:

Policy field — AdapterPolicy.binary: str = "" and StageAdapterPolicy.binary: str | None = None, surfaced through ResolvedAdapter. ""/None = use the profile's binary, so the default is unchanged. Inheritance follows the existing model/extra_args rule in AdapterPolicy.resolved: client-specific, inherited from the base only when same_client, so a stage that switches profile doesn't carry the other CLI's executable. runsetup.make_adapters passes cfg.binary or None into the ctor that already takes it.

Per-run flags — --cli / --cli-binary on run and sweep, applied as a dataclasses.replace on the policy before the snapshot is stamped into RunState, so resume, the --json adapters projection (documents.py:255) and per-task adapter stamping all inherit the override with no extra threading.

Also needed — cmd_validate's adapter.binary check (cli.py:294) currently probes p.binary per profile; it has to probe the effective binary, otherwise validate reports "claude found" for a run that will spawn cc.

Constraint worth documenting rather than detecting: an override assumes the same hook dialect, hooks.config_path and transcript layout as the profile it overrides. It is for an alias/wrapper of the same CLI, not a way to point claude at a different tool.

Nothing here touches the control loop, adds an LLM call, or changes a completion path.

PR

I'd like to contribute this, split into two PRs so each is one logical change:

1. the [adapter] binary policy field + plumbing + the cmd_validate fix
2. the --cli / --cli-binary per-run flags, based on (1)

Happy to adjust the shape (or drop half of it) before I open anything — flagging first per CONTRIBUTING.md.

Additional context

Related surfaces I expect to touch: policy.py (dataclasses, _parse_policy, _stage_adapter, adapter_policy_from_snapshot, _stage_from_snapshot, the embedded policy template), data/settings/core.toml (the sync test enforces field parity), runsetup.py, cli.py, plus docs/FEATURES.md and the changelog.

[coderabbitai]

🔗 Related PRs

#67 - feat(adapters): add Antigravity CLI (agy) adapter profile [merged]
#122 - fix(adapters): disable Claude Code background tasks in the shipped profile [merged]
#163 - feat(profiles): hookless CLI profiles (dialect="none") + opencode-http profile [merged]
#167 - feat(cli): opencode operator surfaces, live smoke, docs (Phase 5) [merged]
#226 - feat: add Hermes Agent adapter [open]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[albi-bon]

Draft PRs up for review of the shape:

• feat(adapter): override the CLI binary a session spawns #397 — [adapter] binary policy field + plumbing + the validate probe fix
• feat(cli): add --cli and --cli-binary to run and sweep #398 — --cli / --cli-binary per-run flags (stacked on feat(adapter): override the CLI binary a session spawns #397)

Both are draft while I wait for a maintainer read on whether this fits; happy to reshape or drop either half.

[albi-bon]

Third draft up: #399 — carries the binary through the adapter-identity path (#153) so an overridden executable is visible in the TUI header, the tasks table and status --json, not just in policy.toml.

Stack shape — #398 and #399 are siblings on #397, not a chain, so they can be taken or dropped independently:

#397  [adapter] binary policy field
 ├── #398  --cli / --cli-binary per-run flags
 └── #399  binary in adapter identity (TUI + --json)

Note for #399: the settings editor needed no code — it renders from core.toml, which #397 already populated.

[albi-bon]

Correcting my earlier note on the stack: I called the three PRs independently mergeable, which conflates two things.

The code is independent — #399 needs nothing from #398 and vice versa, so either can be dropped without touching the other. The merges are not: #397 has to go first (the other two are branched off it and would otherwise drag its commit along), and both leaves add a CHANGELOG entry at the same spot, so the second to merge conflicts there.

Merge order: #397 → then #398 and/or #399, with a rebase on each leaf after #397 lands. Base reads main on all three only because a cross-repo PR cannot target a fork branch.