From 8d3dfab52c8c5bee43b1ce0523b93863560a4511 Mon Sep 17 00:00:00 2001 From: Lucas Kim <41357160+kimnamu@users.noreply.github.com> Date: Fri, 13 Nov 2026 11:43:04 +0900 Subject: [PATCH] fix(claude-local): fail Opus 5.5 ACP runs early when the bundled Claude Code is too old (#13927) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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).
Root cause, raw runs, checklist - `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
--------- Co-authored-by: Claude --- .../adapters/claude-local/src/index.test.ts | 8 +- packages/adapters/claude-local/src/index.ts | 2 +- .../claude-local/src/server/acp.test.ts | 81 +++++++++++++++++++ .../adapters/claude-local/src/server/acp.ts | 56 ++++++++++++- .../src/server/cli-capabilities.ts | 24 +++++- 5 files changed, 164 insertions(+), 7 deletions(-) diff --git a/packages/adapters/claude-local/src/index.test.ts b/packages/adapters/claude-local/src/index.test.ts index 1decc97a672..8e3446c5555 100644 --- a/packages/adapters/claude-local/src/index.test.ts +++ b/packages/adapters/claude-local/src/index.test.ts @@ -3,7 +3,13 @@ import { claudeLocalReasoningEffortsForModel, DEFAULT_CLAUDE_LOCAL_MODEL, resolv import { minimumClaudeCliVersionForModel } from "./server/cli-capabilities.js"; describe("Claude model defaults", () => { - it.each(["claude-opus-5-5", "us.anthropic.claude-opus-5-5", "global.anthropic.claude-opus-5-5[1m]"])("requires a current CLI and offers all efforts for %s", (model) => { + it.each([ + "claude-opus-5-5", + "us.anthropic.claude-opus-5-5", + "global.anthropic.claude-opus-5-5[1m]", + "jp.anthropic.claude-opus-5-5", + "au.anthropic.claude-opus-5-5", + ])("requires a current CLI and offers all efforts for %s", (model) => { expect(minimumClaudeCliVersionForModel(model)).toBe("2.1.280"); expect(claudeLocalReasoningEffortsForModel(model)).toEqual(["low", "medium", "high", "xhigh", "max"]); }); diff --git a/packages/adapters/claude-local/src/index.ts b/packages/adapters/claude-local/src/index.ts index 814479afeaa..ddc4451b662 100644 --- a/packages/adapters/claude-local/src/index.ts +++ b/packages/adapters/claude-local/src/index.ts @@ -24,7 +24,7 @@ export function resolveClaudeModel( export const type = "claude_local"; export function claudeLocalReasoningEffortsForModel(model: string): readonly string[] { - const id = model.trim().replace(/\[1m\]$/, "").replace(/^(?:(?:us|eu|apac|global)\.)?anthropic\./, ""); + const id = model.trim().replace(/\[1m\]$/, "").replace(/^(?:(?:us|eu|apac|global|jp|au)\.)?anthropic\./, ""); if (/^claude-haiku-/.test(id)) return []; if (/^claude-(?:opus-5(?:-5)?|opus-4-[78]|sonnet-5(?:-5)?|fable-5(?:-1)?)$/.test(id)) { return ["low", "medium", "high", "xhigh", "max"]; diff --git a/packages/adapters/claude-local/src/server/acp.test.ts b/packages/adapters/claude-local/src/server/acp.test.ts index 6be80f537bc..b807a9cb196 100644 --- a/packages/adapters/claude-local/src/server/acp.test.ts +++ b/packages/adapters/claude-local/src/server/acp.test.ts @@ -19,6 +19,11 @@ vi.mock("@paperclipai/adapter-utils/execution-target", async (importActual) => { }; }); import { prepareAdapterExecutionTargetRuntime } from "@paperclipai/adapter-utils/execution-target"; +vi.mock("./cli-capabilities.js", async (importActual) => { + const actual = await importActual(); + return { ...actual, readBundledClaudeCodeVersion: vi.fn(actual.readBundledClaudeCodeVersion) }; +}); +import { readBundledClaudeCodeVersion } from "./cli-capabilities.js"; import { buildClaudeAcpConfig, createClaudeAcpExecutor, @@ -800,6 +805,82 @@ describe("claude_local ACP lane", () => { expect(meta[0]?.env?.ANTHROPIC_MODEL).toBe("claude-fable-5-1"); }); + it("reads the Claude Code version bundled with the ACP bridge", async () => { + await expect(readBundledClaudeCodeVersion()).resolves.toMatch(/^\d+\.\d+\.\d+$/); + }); + + it.each([ + ["hoisted", { "node_modules/@anthropic-ai/claude-agent-sdk": "2.1.257" }], + // npm nests the bridge's pinned SDK when another SDK version is hoisted. + ["nested under the bridge", { + "node_modules/@anthropic-ai/claude-agent-sdk": "2.1.280", + "node_modules/@agentclientprotocol/claude-agent-acp/node_modules/@anthropic-ai/claude-agent-sdk": "2.1.257", + }], + ])("reads the bridge's Claude Code version from an npm install with the SDK %s", async (_layout, sdkDirs) => { + const root = await makeTempRoot("paperclip-claude-acp-npm-layout-"); + const writePackage = async (dir: string, manifest: Record) => { + await fs.mkdir(path.join(root, dir), { recursive: true }); + await fs.writeFile(path.join(root, dir, "package.json"), JSON.stringify(manifest)); + }; + // Export maps as published: the bridge exports ./*, the SDK exports only ".". + await writePackage("node_modules/@agentclientprotocol/claude-agent-acp", { exports: { "./*": "./*" } }); + for (const [dir, claudeCodeVersion] of Object.entries(sdkDirs)) { + await writePackage(dir, { exports: { ".": { default: "./sdk.mjs" } }, claudeCodeVersion }); + await fs.writeFile(path.join(root, dir, "sdk.mjs"), ""); + } + + const adapterModule = path.join(root, "node_modules/@paperclipai/adapter-claude-local/dist/server/cli-capabilities.js"); + await expect(readBundledClaudeCodeVersion(adapterModule)).resolves.toBe("2.1.257"); + }); + + it.each([ + ["claude-opus-5-5", {}], + ["us.anthropic.claude-opus-5-5", { CLAUDE_CODE_USE_BEDROCK: "1" }], + ])("rejects %s before launch when the bundled Claude Code is too old", async (model, env) => { + vi.mocked(readBundledClaudeCodeVersion).mockResolvedValueOnce("2.1.257"); + const root = await makeTempRoot("paperclip-claude-acp-old-bundle-"); + const runtimes: FakeRuntime[] = []; + const execute = createClaudeAcpExecutor({ + createRuntime: (options: FakeRuntimeOptions) => { + const runtime = new FakeRuntime(options); + runtimes.push(runtime); + return runtime as never; + }, + }); + + const context = buildContext(root); + const result = await execute({ ...context, config: { ...context.config, model, env } }); + + expect(runtimes.flatMap((runtime) => runtime.startInputs)).toEqual([]); + expect(result.errorCode).toBe("claude_cli_version_incompatible"); + expect(result.errorMessage).toContain(`${model} requires Claude Code 2.1.280 or newer`); + expect(result.resultJson).toMatchObject({ + requiredClaudeCodeVersion: "2.1.280", + detectedClaudeCodeVersion: "2.1.257", + }); + }); + + it("leaves Opus 5.5 to an explicit CLAUDE_CODE_EXECUTABLE on the ACP lane", async () => { + vi.mocked(readBundledClaudeCodeVersion).mockClear(); + const root = await makeTempRoot("paperclip-claude-acp-executable-"); + const execute = createClaudeAcpExecutor({ + createRuntime: (options: FakeRuntimeOptions) => new FakeRuntime(options) as never, + }); + + const context = buildContext(root); + const result = await execute({ + ...context, + config: { + ...context.config, + model: "claude-opus-5-5", + env: { CLAUDE_CODE_EXECUTABLE: path.join(root, "claude") }, + }, + }); + + expect(result.exitCode).toBe(0); + expect(readBundledClaudeCodeVersion).not.toHaveBeenCalled(); + }); + it("creates the ACP session on the in-sandbox workspace cwd for runner-backed remote runs", async () => { const root = await makeTempRoot("paperclip-claude-acp-remote-cwd-"); const localCwd = path.join(root, "worktree"); diff --git a/packages/adapters/claude-local/src/server/acp.ts b/packages/adapters/claude-local/src/server/acp.ts index 8277d41168e..5b0ab2c7b58 100644 --- a/packages/adapters/claude-local/src/server/acp.ts +++ b/packages/adapters/claude-local/src/server/acp.ts @@ -58,6 +58,11 @@ import { buildLocalAdapterTestProbeEnv } from "./probe-env.js"; import { detectClaudeLoginRequired, extractClaudeRetryNotBefore, isClaudeProviderQuotaError, parseClaudeStreamJson } from "./parse.js"; import { buildClaudeProbePermissionArgs, claudeSandboxPermissionEnv } from "./permissions.js"; import { ADAPTER_AUTH_MISSING_CHECK_CODE } from "./auth-check.js"; +import { + claudeCliVersionAtLeast, + minimumClaudeCliVersionForModel, + readBundledClaudeCodeVersion, +} from "./cli-capabilities.js"; import { resolveClaudeModel, SANDBOX_INSTALL_COMMAND } from "../index.js"; const moduleDir = path.dirname(fileURLToPath(import.meta.url)); @@ -431,6 +436,49 @@ export function mapClaudeAcpAuthErrorCode( }; } +/** + * Mirror the CLI lane's minimum-version check (`execute.ts`) for the Claude + * Code bundled with the local ACP bridge. Without it an unsupported model + * fails only as a generic terminal service failure. A remote target, a custom + * agentCommand, or CLAUDE_CODE_EXECUTABLE brings its own Claude Code. + */ +async function bundledClaudeCodeVersionFailure( + ctx: AdapterExecutionContext, + config: Record, + target: ReturnType, +): Promise { + const model = asString(config.model, ""); + const minimumCliVersion = minimumClaudeCliVersionForModel(model); + if ( + !minimumCliVersion || + target?.kind === "remote" || + firstNonEmptyString(config.agentCommand) || + firstNonEmptyString(parseObject(config.env).CLAUDE_CODE_EXECUTABLE) + ) { + return null; + } + const bundledCliVersion = await readBundledClaudeCodeVersion(); + if (!bundledCliVersion || claudeCliVersionAtLeast(bundledCliVersion, minimumCliVersion)) return null; + const errorMessage = + `${model} requires Claude Code ${minimumCliVersion} or newer; the ACP lane runs the bundled Claude Code ${bundledCliVersion}. ` + + "Set CLAUDE_CODE_EXECUTABLE in the agent env to a newer Claude Code, or set engine=cli, before retrying."; + await ctx.onLog("stderr", `[paperclip] ${errorMessage}\n`); + return { + exitCode: 1, + signal: null, + timedOut: false, + errorMessage, + errorCode: "claude_cli_version_incompatible", + ...resolveClaudeAcpBillingIdentity(ctx), + model, + resultJson: { + stopReason: "claude_cli_version_incompatible", + requiredClaudeCodeVersion: minimumCliVersion, + detectedClaudeCodeVersion: bundledCliVersion, + }, + }; +} + export function createClaudeAcpExecutor(options: ClaudeAcpExecutorOptions = {}): ClaudeAcpExecutor { let executor: ClaudeAcpExecutor | null = null; return async (ctx) => { @@ -444,10 +492,10 @@ export function createClaudeAcpExecutor(options: ClaudeAcpExecutorOptions = {}): executionTarget: ctx.executionTarget, legacyRemoteExecution: ctx.executionTransport?.remoteExecution, }); - const result = await currentExecutor({ - ...ctx, - config: buildClaudeAcpConfig(ctx.config, target?.kind === "remote" ? {} : process.env), - }); + const config = buildClaudeAcpConfig(ctx.config, target?.kind === "remote" ? {} : process.env); + const versionFailure = await bundledClaudeCodeVersionFailure(ctx, config, target); + if (versionFailure) return versionFailure; + const result = await currentExecutor({ ...ctx, config }); return mapClaudeAcpAuthErrorCode(result); }; } diff --git a/packages/adapters/claude-local/src/server/cli-capabilities.ts b/packages/adapters/claude-local/src/server/cli-capabilities.ts index f20c46d7c91..db937a69282 100644 --- a/packages/adapters/claude-local/src/server/cli-capabilities.ts +++ b/packages/adapters/claude-local/src/server/cli-capabilities.ts @@ -1,5 +1,7 @@ import type { AdapterExecutionTarget } from "@paperclipai/adapter-utils/execution-target"; import { runAdapterExecutionTargetProcess } from "@paperclipai/adapter-utils/execution-target"; +import fs from "node:fs/promises"; +import { createRequire } from "node:module"; import path from "node:path"; const effortFlagSupportCache = new Map>(); @@ -36,7 +38,7 @@ function cacheKeyForTarget(command: string, target: AdapterExecutionTarget | nul } export function minimumClaudeCliVersionForModel(model: string): string | null { - const modelId = model.trim().replace(/\[1m\]$/, "").replace(/^(?:(?:us|eu|apac|global)\.)?anthropic\./, ""); + const modelId = model.trim().replace(/\[1m\]$/, "").replace(/^(?:(?:us|eu|apac|global|jp|au)\.)?anthropic\./, ""); if (modelId === "claude-opus-5-5") return "2.1.280"; if (modelId === "claude-sonnet-5-5") return "2.1.284"; return modelId === "claude-fable-5-1" @@ -48,6 +50,26 @@ export function parseClaudeCliVersion(output: string): string | null { return output.match(/\b(\d+)\.(\d+)\.(\d+)\b/)?.[0] ?? null; } +/** + * The Claude Code version bundled with the ACP bridge's SDK dependency, which + * the bridge launches unless CLAUDE_CODE_EXECUTABLE is set. Resolved through + * the bridge like `build-provider-pack.mjs`, so workspace overrides count. + * `from` is where resolution starts; tests point it into an npm-style tree. + */ +export async function readBundledClaudeCodeVersion(from: string | URL = import.meta.url): Promise { + try { + const acpRequire = createRequire( + createRequire(from).resolve("@agentclientprotocol/claude-agent-acp/package.json"), + ); + // The SDK does not export ./package.json; its entry sits at the package root. + const sdkDir = path.dirname(acpRequire.resolve("@anthropic-ai/claude-agent-sdk")); + const sdkPackage = JSON.parse(await fs.readFile(path.join(sdkDir, "package.json"), "utf8")); + return parseClaudeCliVersion(String(sdkPackage.claudeCodeVersion ?? "")); + } catch { + return null; + } +} + export function claudeCliVersionAtLeast(version: string, minimum: string): boolean { const parsedVersion = version.split(".").map(Number); const parsedMinimum = minimum.split(".").map(Number);