Files
PaperClipAI/packages/adapters
Lucas KimandClaude 8d3dfab52c fix(claude-local): fail Opus 5.5 ACP runs early when the bundled Claude Code is too old (#13927)
Thanks @spaceshipmike for the clear report in #13889 and the
`CLAUDE_CODE_EXECUTABLE` workaround, and thanks @chen97 for the
follow-up.

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - `claude_local` defaults to the ACP lane, which runs the ACP bridge's
bundled Claude Code
> - npm installs get Claude Code 2.1.257, because the root pnpm override
does not reach them
> - Opus 5.5 needs 2.1.280, so each run fails with only "terminal
service failure"
> - This pull request adds the CLI lane version check to the ACP lane
> - The error then names both versions and the fix

## Linked Issues or Issue Description

Refs #13889. This PR adds the clear failure the issue asks for. The
bridge bump stays with maintainers (#13838 moved the workspace override
to 0.3.280). Bridge 0.81.0 is the first stable release on SDK 0.3.280.

## What Changed

- `acp.ts`: before launch, compare the bundled `claudeCodeVersion` with
`minimumClaudeCliVersionForModel()`. Return
`claude_cli_version_incompatible` with the CLI lane fields.
- `cli-capabilities.ts`: `readBundledClaudeCodeVersion()` resolves the
SDK through the bridge, like `build-provider-pack.mjs`.
- Match the `jp.` and `au.` Bedrock prefixes. Opus 5.5 has both
profiles.

## Verification

Default ACP lane on Bedrock, published `2026.924.0-canary.0`. After =
that install with this branch's build.

| Case | Before | After |
|---|---|---|
| `us.anthropic.claude-opus-5-5` | ❌ `acpx_turn_failed`, "ACP agent
reported a terminal service failure." (6.9 s) | ✅ clear
`claude_cli_version_incompatible` before launch (0 s) |
| `jp.anthropic.claude-opus-5-5` (ap-northeast-1) | ❌ same generic
failure | ✅ same clear error |
| `us.anthropic.claude-opus-5` (no minimum) | ✅ runs | ✅ runs, unchanged
|
| Opus 5.5 + `CLAUDE_CODE_EXECUTABLE` in agent env (2.1.281) | ✅ runs |
✅ runs, check skipped |
| `engine=cli` + Claude Code 2.1.281, `jp.` profile | ✅ runs | ✅ runs,
version probe passes |
| Source checkout (override, bundled 2.1.280), `us.` Opus 5.5 | ✅ runs |
✅ runs, unchanged |

```text
us.anthropic.claude-opus-5-5 requires Claude Code 2.1.280 or newer; the ACP lane runs the bundled Claude Code 2.1.257. Set CLAUDE_CODE_EXECUTABLE in the agent env to a newer Claude Code, or set engine=cli, before retrying.
```

```text
# source reverted, new tests kept
Tests  7 failed | 4 passed | 40 skipped (51)
# this branch (includes npm-style trees: SDK hoisted, and SDK nested under the bridge)
Tests  11 passed | 40 skipped (51)
# claude-local project (was 314 passed)
Tests  322 passed | 1 skipped (323)
# also: claude-local typecheck, check-forbidden-tokens, check-module-boundaries, UI effort tests (97), server adapter tests (34)
```

## Risks

Low risk. The check reads one `package.json`, only for models with a
minimum. It skips remote targets, custom `agentCommand`,
`CLAUDE_CODE_EXECUTABLE`, and an unreadable SDK.

## Model Used

Claude via Claude Code (tool use, code execution).

<details><summary>Root cause, raw runs, checklist</summary>

- `claude-agent-acp@0.73.0` pins SDK `0.3.257` (`claudeCodeVersion:
"2.1.257"`). The override at `pnpm-workspace.yaml:36` changes only the
workspace lockfile (see `installation-integrity.ts:96`).
- The CLI lane checks at `execute.ts:1263`. The ACP engine keeps
provider text out of results (`acpx-engine/execute.ts:4757`).
- A server-level `CLAUDE_CODE_EXECUTABLE` is not in the host env
allowlists (`acpx-engine/execute.ts:556`, `:588`). The agent env works.
This can explain what @chen97 saw.
- The `CLAUDE_CODE_EXECUTABLE` test also passes on master. It guards the
workaround.

```text
claude 2.1.257 --model us.anthropic.claude-opus-5-5 (us-east-1): api_error_status=400 API Error: 400 Claude Code 2.1.257 does not support this model; version 2.1.280 or newer is required.
claude 2.1.257 --model jp./au.anthropic.claude-opus-5-5 (ap-northeast-1 / ap-southeast-2): same 400
claude 2.1.281 --model jp.anthropic.claude-opus-5-5 (ap-northeast-1): Hello!
before, server env CLAUDE_CODE_EXECUTABLE | us.anthropic.claude-opus-5-5: errorCode=acpx_turn_failed
before, agent env CLAUDE_CODE_EXECUTABLE  | us.anthropic.claude-opus-5-5: exitCode=0 hello
```

- [x] I used Claude Code to search GitHub for duplicate or related PRs
(none references #13889)
- [x] Thinking path, `Refs #13889`, tests, and risks included; public
references only; descriptive branch name
- [x] I used Claude Code to run the tests locally, and they pass
- [ ] Model version listed, ROADMAP.md checked, docs updated
- [ ] CI green, Greptile 5/5, reviewer comments addressed

</details>

---------

Co-authored-by: Claude <noreply@anthropic.com>
2026-11-12 20:43:04 -06:00
..