Use host-installed Claude Code instead of the ACP adapter’s bundled executable #1080

Problem

Claude reviews through XMD can fail even when the host's installed Claude Code supports the requested model. The retained Claude ACP adapter selects the executable shipped with its Agent SDK instead of the host CLI.

Observed on PR #1078 at 9c17d04378b6f482c19857b7b65f86153d484a7d:

• The host claude --version reports 2.1.316.
• The materialized @agentclientprotocol/claude-agent-acp@0.70.0 pins Agent SDK 0.3.238, whose platform executable reports Claude Code 2.1.238.
• Fable refused that client with an API 400 requiring 2.1.251 or newer. The attempt fully joined without a substantive review or public post.
• The same cause had already affected the Require joined review evidence for workflow delivery readiness #1064 review.

The retained adapter supports CLAUDE_CODE_EXECUTABLE. XMD already uses that child-process override for its native-session integration, but the workflow Agent profile is ACP-only and does not take that construction route. Reuse the existing executable-selection and child-environment mechanisms rather than making the workflow inherit unrelated machine-session ownership capabilities.

Required outcome

Use the host-installed Claude Code for XMD's retained Claude ACP v1 integration, and stop installing or silently falling back to a second SDK-supplied Claude executable.

• Resolve the intended host claude through the host's execution environment and pass its executable selection to the adapter through the existing child-only seam. A missing or unlaunchable host CLI produces an actionable availability failure; it never selects the SDK binary instead.
• Cover workflow Agent prompts/reviews and the corresponding ordinary run, plan and REPL paths. Preserve deliberate custom-agent configuration and existing supported host executable selection.
• Fresh adapter materialization does not install the SDK's platform Claude executable packages. Preserve the SDK library and required adapter dependencies. Use the smallest compatible change; update the retained adapter/SDK only where needed for this outcome.
• Keep ACP v1 and the necessary patched snapshot contracts: explicit backend acceptance, exact completed-prompt checkpoint identity, and applicable native identity/history guarantees. Do not switch to the newest upstream adapter merely to get a newer bundled CLI.
• Keep permissions, exclusive ownership, cancellation, joined cleanup and replay behavior. Do not mutate global process.env, expose host-only executable configuration in durable session records, or replace an active conversation.
• Follow Make Codex and Claude sessions continue across CLI upgrades #891's accepted compatibility policy: observed CLI versions are evidence, not a new per-release certification or same-build admission gate. Preserve the exact retained conversation when continuing it. No retroactive rewriting of historical evidence or active-run hot reload.

Existing materialized caches and active calls are not deleted, rewritten or restarted as part of scheduling this work.

Discriminating evidence

1. A deterministic production-route test supplies a host Claude executable and a different/stale SDK executable, and proves the host executable is the one launched. Cover the actual workflow profile, not only the native-session helper.
2. Missing host Claude refuses clearly despite an available SDK binary, with no fallback or model prompt.
3. Fresh materialization omits platform Claude executable packages while the adapter can initialize using the host executable. Verify the affected dependency/provenance/generated-artifact boundaries.
4. Applicable continuity, acceptance, checkpoint, permission, cancellation and cleanup regressions still pass. Completed replay remains offline.
5. Preserve the first failure output and follow normal exact-head independent review and delivery checks. Reuse existing provider evidence where sufficient; this issue is not a grant for recurring paid qualification or retries of the failed reviews.

Ownership and queue

Integration owns this issue next after the currently active #1006 / PR #1078 work reaches its normal completion or an explicit human-approved handoff. It precedes the queued #1075 absolute-path permission work; the rest of Integration's queue retains its order. Do not interrupt the current owner, review, live evidence or CI, and do not change Main's #743 / PR #1079 work.

At the next required fresh workflow launch, retain the existing #1064 adoption direction and record the actual effective workflow/runtime/profile identities and original requirements before the first role. Do not claim full adoption from an acknowledgement or isolated test.

Related work

• Return each embedded ACP adapter to a qualifying upstream release #636 retires snapshots only after released adapters satisfy XMD's needs; it explicitly does not own adapter upgrades. This repair retains the required v1 snapshot.
• Support ACP v2 acceptance and completion in the runtime integration #1073 owns ACP v2 integration and remains deferred under the existing upstream-support condition.
• Make Codex and Claude sessions continue across CLI upgrades #891 owns CLI upgrade compatibility; this issue fixes which executable XMD actually launches.
• Closed 🐛 xmd plan resolves agents through ACPX's stock registry instead of the embedded adapters #672 fixed stock-registry selection. It did not require eliminating the executable dependency inside the selected embedded Claude adapter.
• Remove the vendored ACPX transient-environment patch after a released scoped seam passes continuity #566 owns retirement of the ACPX transient-environment patch, a separate concern.