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);