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>
This commit is contained in:
Lucas KimandClaude authored and GitHub committed 2026-11-12 20:43:04 -06:00
1 parent 2e795628eb
commit 8d3dfab52c
5 files changed
+164 -7

No files matched your search

@@ -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"]);
});
+1 -1
View File
@@ -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"];
@@ -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<typeof import("./cli-capabilities.js")>();
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<string, unknown>) => {
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");
@@ -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<string, unknown>,
target: ReturnType<typeof readAdapterExecutionTarget>,
): Promise<AdapterExecutionResult | null> {
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);
};
}
@@ -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<string, Promise<boolean | null>>();
@@ -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<string | null> {
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);