Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
fix(adapters): never encode tool names into a wire that cannot decode them
Jack Rudenko5b15868760cc
diff --git a/packages/cli/src/adapters/base-api-format.ts b/packages/cli/src/adapters/base-api-format.tsindex 80643738..f91125b7 100644--- a/packages/cli/src/adapters/base-api-format.ts+++ b/packages/cli/src/adapters/base-api-format.ts@@ -16,7 +16,12 @@ import type { APIFormat } from "./api-format.js";import { type ReasoningCapability, lookupModel, lookupModelReasoning } from "./model-catalog.js";import type { ModelDialect } from "./model-dialect.js";import { rejectedOptionalParams } from "./optional-param-rejection.js";-import { type ToolNameBindings, encodeToolName, newToolNameBindings } from "./tool-name-utils.js";+import {+ type ToolNameBindings,+ encodeToolName,+ newToolNameBindings,+ wireDecodesToolNames,+} from "./tool-name-utils.js";/*** The OPTIONAL parameters {@link BaseAPIFormat.applyOpenAISamplingParams} adds@@ -134,6 +139,36 @@ export abstract class BaseAPIFormat implements APIFormat, ModelDialect {*/protected readonly wireFormat?: StreamFormat;+ /**+ * The parser the RESPONSE will actually be fed to, as ComposedHandler+ * resolves it — `provider.overrideStreamFormat()` first, then the adapters.+ *+ * Distinct from {@link wireFormat}, which is the REQUEST shape. They are+ * usually the same and are not always: a custom endpoint may declare+ * `{transport:"openai", streamFormat:"anthropic-sse"}`, and then the payload+ * is OpenAI-shaped (so the encoder arms) while the parser is the Anthropic+ * passthrough (which has no decode map). Only {@link getToolNameLimit} reads+ * this; nothing else should branch on it.+ *+ * Set ONCE, from the ComposedHandler constructor. It is a property of the+ * composition, not of the request — `resolveStreamFormat()` does not look at+ * the request at all — so this carries none of the per-request race that made+ * {@link toolNameBindings} per-request.+ */+ private responseWireFormat?: StreamFormat;++ /**+ * Tell this adapter which parser will read the response it is helping build.+ *+ * Called once per handler, at construction. A delegating adapter that runs an+ * inner adapter's `prepareRequest` MUST override this and pass it on, or the+ * inner adapter encodes names into a wire that cannot decode them+ * (OpenRouterAPIFormat and LocalAdapter both do).+ */+ setResponseWireFormat(format: StreamFormat | undefined): void {+ this.responseWireFormat = format;+ }+/*** This request's tool-name bindings, in both directions.*@@ -261,28 +296,30 @@ export abstract class BaseAPIFormat implements APIFormat, ModelDialect {/*** Maximum tool name length this request's wire accepts, or null for no limit.*- * A RULE about the wire, not a roster of adapters. OpenAI validates a function- * name against `^[a-zA-Z0-9_-]{1,64}$` on both of its shapes, so every- * OpenAI-shaped wire gets 64 and everything else gets null. Before this, the- * method returned null on every adapter except Xiaomi, so nothing else+ * THE QUESTION IS "CAN THE RESPONSE BE DECODED", NOT "IS THE REQUEST+ * OpenAI-SHAPED". Those come apart, and when they do the encoder runs with no+ * decoder behind it and Claude Code receives a tool name it never advertised.+ * `wireDecodesToolNames` is the one list of parsers that are handed this+ * request's map; a wire absent from it gets null and nothing is encoded. The+ * cost of not encoding is a loud 400 on a >64-char name; the cost of encoding+ * without a decoder is a silently dropped tool call.+ *+ * OpenAI validates a function name against `^[a-zA-Z0-9_-]{1,64}$` on both of+ * its shapes, so 64 is that limit and not a guess about any one model. Before+ * item 7 this method returned null on every adapter except Xiaomi, so nothing* truncated at all — and a real 65-character MCP name- * (`mcp__plugin_browser-use_browser-use__retry_with_browser_use_agent`) fails+ * (`mcp__plugin_browser-use_browser-use__retry_with_browser_use_agent`) failed* the WHOLE request, not just that tool.- *- * The Anthropic-wire check comes FIRST and is load-bearing: a dialect is- * selected by model name and cannot know its wire, so `getStreamFormat()`- * still answers "openai-sse" for a dialect reached over Qwen Plan's- * Anthropic-compatible endpoint. Encoding there would rewrite names the- * anthropic-sse parser has no map to decode.*/getToolNameLimit(): number | null {- // The COMPOSED wire wins when it was supplied. A dialect self-selects by- // model name and its own `getStreamFormat()` answers "openai-sse" whatever- // it was composed into — so a dialect running under Ollama's JSONL wire, or- // Qwen Plan's Anthropic one, would otherwise encode names that wire's parser- // has no map to decode.- const wire = this.wireFormat ?? this.getStreamFormat();- return wire === "openai-sse" || wire === "openai-responses-sse" ? OPENAI_TOOL_NAME_LIMIT : null;+ // Precedence mirrors ComposedHandler.resolveStreamFormat(), which is what+ // actually picks the parser: the provider's RESPONSE override first, then+ // the composed request wire, then the dialect's own guess. A dialect+ // self-selects by model name and its `getStreamFormat()` answers+ // "openai-sse" whatever it was composed into, so it is the last word, never+ // the first.+ const wire = this.responseWireFormat ?? this.wireFormat ?? this.getStreamFormat();+ return wireDecodesToolNames(wire) ? OPENAI_TOOL_NAME_LIMIT : null;}/**diff --git a/packages/cli/src/adapters/local-adapter.ts b/packages/cli/src/adapters/local-adapter.tsindex adeb8f49..b7d51999 100644--- a/packages/cli/src/adapters/local-adapter.ts+++ b/packages/cli/src/adapters/local-adapter.ts@@ -13,6 +13,7 @@import { mapToolChoiceToOpenAI } from "../handlers/shared/format/openai-tools.js";import { log } from "../logger.js";+import type { StreamFormat } from "../providers/transport/types.js";import { type AdapterResult, BaseAPIFormat } from "./base-api-format.js";import { resolveModelDialect } from "./dialect-manager.js";@@ -154,6 +155,16 @@ export class LocalModelAdapter extends BaseAPIFormat {return request;}+ override setResponseWireFormat(format: StreamFormat | undefined): void {+ // The inner adapter runs its own prepareRequest template (above) and+ // encodes into its own bindings, so it needs the same answer to "can this+ // response be decoded". Load-bearing here: a local provider can serve this+ // adapter over `ollama-jsonl`, whose parser takes no decode map, while the+ // inner dialect's own `getStreamFormat()` still says "openai-sse".+ super.setResponseWireFormat(format);+ this.innerAdapter.setResponseWireFormat(format);+ }+override getToolNameMap(): Map<string, string> {const map = new Map(super.getToolNameMap());for (const [k, v] of this.innerAdapter.getToolNameMap()) {diff --git a/packages/cli/src/adapters/openrouter-api-format.ts b/packages/cli/src/adapters/openrouter-api-format.tsindex 79fa49e2..1f3ce808 100644--- a/packages/cli/src/adapters/openrouter-api-format.ts+++ b/packages/cli/src/adapters/openrouter-api-format.ts@@ -14,6 +14,7 @@ import {convertToolsToOpenAI,mapToolChoiceToOpenAI,} from "../handlers/shared/format/openai-tools.js";+import type { StreamFormat } from "../providers/transport/types.js";import { type AdapterResult, BaseAPIFormat } from "./base-api-format.js";import { resolveModelDialect } from "./dialect-manager.js";@@ -151,6 +152,15 @@ export class OpenRouterAPIFormat extends BaseAPIFormat {return this.innerAdapter.prepareRequest(request, originalRequest);}+ override setResponseWireFormat(format: StreamFormat | undefined): void {+ // The inner adapter runs its OWN prepareRequest template (above), so it+ // encodes into its own bindings and needs the same answer to "can this+ // response be decoded". Without this it would fall back to its dialect's+ // self-declared `getStreamFormat()`.+ super.setResponseWireFormat(format);+ this.innerAdapter.setResponseWireFormat(format);+ }+override getToolNameMap(): Map<string, string> {// Merge maps from both adaptersconst map = new Map(super.getToolNameMap());diff --git a/packages/cli/src/adapters/tool-name-utils.ts b/packages/cli/src/adapters/tool-name-utils.tsindex e73bd422..4940746d 100644--- a/packages/cli/src/adapters/tool-name-utils.ts+++ b/packages/cli/src/adapters/tool-name-utils.ts@@ -6,6 +6,7 @@*/import { log } from "../logger.js";+import type { StreamFormat } from "../providers/transport/types.js";/*** The character shape of a tool name, as a pattern fragment.@@ -154,3 +155,37 @@ export function encodeToolName(}return encoded;}++/**+ * The stream parsers that are handed this request's decode map, and can+ * therefore restore an encoded tool name before Claude Code sees it.+ *+ * A LIST OF PARSERS WITH A DECODER, not a list of OpenAI-shaped request wires —+ * those are two different questions and conflating them is the encoder/decoder+ * split this constant exists to close. `ComposedHandler.handleStream` threads+ * `toolNameMap` into exactly these two cases; `anthropic-sse`, `gemini-sse`,+ * `ollama-jsonl` and `connect-proto` receive no map and have no parameter to+ * receive one, so a name encoded on the way out reaches the client verbatim —+ * a tool name the client never advertised, dropped by its allowlist with no+ * error anywhere.+ *+ * That pairing is real and reachable today: a custom endpoint may declare+ * `{transport: "openai", streamFormat: "anthropic-sse"}` (an aggregator that+ * takes an OpenAI-shaped request and answers in Anthropic SSE), and+ * `streamFormat` accepts all five values, so `gemini-sse` and `ollama-jsonl`+ * pair with the OpenAI transport the same way.+ *+ * Add a wire here ONLY together with a decode path in its parser.+ */+export const TOOL_NAME_DECODING_WIRES = ["openai-sse", "openai-responses-sse"] as const;++/**+ * Whether the parser selected for the RESPONSE can decode an encoded tool name.+ *+ * `undefined` — nobody said — is treated as "cannot decode", which is the safe+ * direction: not encoding costs a 400 on a >64-char name (loud, recoverable),+ * while encoding without a decoder drops the call silently.+ */+export function wireDecodesToolNames(format: StreamFormat | undefined): boolean {+ return format !== undefined && (TOOL_NAME_DECODING_WIRES as readonly string[]).includes(format);+}diff --git a/packages/cli/src/handlers/composed-handler.ts b/packages/cli/src/handlers/composed-handler.tsindex 640a47c1..89f16a76 100644--- a/packages/cli/src/handlers/composed-handler.ts+++ b/packages/cli/src/handlers/composed-handler.ts@@ -22,7 +22,7 @@import type { Context } from "hono";import type { BaseAPIFormat, EffortLevel } from "../adapters/base-api-format.js";-import type { ProviderTransport } from "../providers/transport/types.js";+import type { ProviderTransport, StreamFormat } from "../providers/transport/types.js";import type { ModelHandler } from "./types.js";// Alias for readability within this filetype BaseModelAdapter = BaseAPIFormat;@@ -224,6 +224,28 @@ export class ComposedHandler implements ModelHandler {this.modelAdapter = resolvedModelAdapter;}+ // Tell every adapter which PARSER will read the response.+ //+ // This is the only place that knows: `resolveStreamFormat()` consults+ // `provider.overrideStreamFormat()` FIRST, and no adapter can see that. The+ // pairing it exists for is `{transport:"openai", streamFormat:"anthropic-sse"}`+ // — an OpenAI-shaped REQUEST answered in Anthropic SSE. The request shape+ // armed the 64-char tool-name encoder while the Anthropic passthrough parser+ // takes no decode map, so Claude Code received a tool name it never+ // advertised and its allowlist dropped the call with no error anywhere.+ // `getToolNameLimit()` now returns null for any wire whose parser cannot+ // decode. See `wireDecodesToolNames`.+ //+ // Set once, here, because it is a property of the COMPOSITION:+ // `resolveStreamFormat()` never looks at the request, so this carries none+ // of the per-request race that made the tool-name bindings per-request.+ // `resolvedDialect`, not `modelAdapter`: an unrecognized model leaves+ // `modelAdapter` unset and `getAdapter()` then returns the dialect, which is+ // the instance that would do the encoding.+ const responseWire = this.resolveStreamFormat() as StreamFormat;+ this.resolvedDialect.setResponseWireFormat(responseWire);+ this.explicitAdapter?.setResponseWireFormat(responseWire);+// Initialize middleware (only register model-specific middleware when applicable).// Use bareModelName for the middleware gate — .includes() works identically for// "[email protected]" and "gemini-2.5-flash", and bare form is the invariant.diff --git a/packages/cli/src/handlers/tool-name-encode-decode-pairing.test.ts b/packages/cli/src/handlers/tool-name-encode-decode-pairing.test.tsnew file mode 100644index 00000000..c9da3acf--- /dev/null+++ b/packages/cli/src/handlers/tool-name-encode-decode-pairing.test.ts@@ -0,0 +1,158 @@+/**+ * The tool-name codec must never encode into a wire that cannot decode.+ *+ * Item 7 (`aff8f7f`) turned the 64-char encoder on for every OpenAI-shaped+ * REQUEST and threaded the decode map to the parser — but the two decisions were+ * taken in different places. The encoder asked the adapter+ * (`BaseAPIFormat.getToolNameLimit`, request shape); the parser was chosen by+ * `ComposedHandler.resolveStreamFormat()`, which consults+ * `provider.overrideStreamFormat()` FIRST and no adapter can see. A custom+ * endpoint declaring `{transport:"openai", streamFormat:"anthropic-sse"}` — an+ * aggregator that takes an OpenAI-shaped request and answers in Anthropic SSE —+ * therefore encoded the names and handed the response to a parser with no decode+ * input at all. Claude Code received a tool name it never advertised and its+ * allowlist dropped the call, with no error anywhere.+ *+ * `streamFormat` accepts five values on a custom endpoint, so `gemini-sse` and+ * `ollama-jsonl` pair with the OpenAI transport in exactly the same way. That is+ * why the gate is "does the selected PARSER hold a decoder", not "is this one+ * response wire Anthropic".+ *+ * ## Provenance of the inputs+ *+ * REQUEST-side, plus a composition. `test-fixtures/sse-responses/` holds+ * response streams, not inbound bodies or provider configs, so no capture can+ * reach `prepareRequest` or a ComposedHandler constructor. The providers and+ * payloads below are constructed inline and assert only this tree's own+ * contract. No `.sse` fixture was invented.+ */++import { expect, test } from "bun:test";+import { OpenAIAPIFormat } from "../adapters/openai-api-format.js";+import { TOOL_NAME_DECODING_WIRES, wireDecodesToolNames } from "../adapters/tool-name-utils.js";+import { OpenAIProviderTransport } from "../providers/transport/openai.js";+import type { StreamFormat } from "../providers/transport/types.js";+import { ComposedHandler } from "./composed-handler.js";+import type { RemoteProvider } from "./shared/remote-provider-types.js";++/** A real one, from the magus browser-use MCP server. 65 characters. */+const REAL_LONG_NAME = "mcp__plugin_browser-use_browser-use__retry_with_browser_use_agent";++function customEndpointProvider(streamFormat?: RemoteProvider["streamFormatOverride"]) {+ return {+ name: "corp-proxy",+ baseUrl: "https://relay.example.invalid",+ apiPath: "/v1/chat/completions",+ apiKeyEnvVar: "CORP_PROXY_API_KEY",+ prefixes: ["corp/"],+ authScheme: "bearer",+ streamFormatOverride: streamFormat,+ } satisfies RemoteProvider;+}++/**+ * Compose exactly what `custom-endpoints-loader.ts` composes for+ * `{transport:"openai", streamFormat:<x>}`, and hand back the adapter so the+ * encode decision can be read off it.+ */+function composeOpenAiTransportEndpoint(+ streamFormat?: RemoteProvider["streamFormatOverride"]+): OpenAIAPIFormat {+ const provider = customEndpointProvider(streamFormat);+ const transport = new OpenAIProviderTransport(provider, "relay-model", "sk-test");+ const adapter = new OpenAIAPIFormat("relay-model");+ new ComposedHandler(transport, "corp@relay-model", "relay-model", 8080, { adapter });+ return adapter;+}++function payloadNamingTheLongTool() {+ return {+ model: "relay-model",+ tools: [{ type: "function", function: { name: REAL_LONG_NAME } }],+ messages: [{ role: "user", content: "go" }],+ tool_choice: { type: "function", function: { name: REAL_LONG_NAME } },+ };+}++// ─── The list of decoding parsers ───────────────────────────────────────────++test("exactly the two parsers that are handed a decode map decode tool names", () => {+ // `ComposedHandler.handleStream` threads `toolNameMap` into these two cases+ // and no others. Adding a wire here without a decode path in its parser+ // re-opens this defect.+ expect([...TOOL_NAME_DECODING_WIRES]).toEqual(["openai-sse", "openai-responses-sse"]);++ expect(wireDecodesToolNames("openai-sse")).toBe(true);+ expect(wireDecodesToolNames("openai-responses-sse")).toBe(true);++ for (const wire of [+ "anthropic-sse",+ "gemini-sse",+ "ollama-jsonl",+ "connect-proto",+ ] as StreamFormat[]) {+ expect(wireDecodesToolNames(wire)).toBe(false);+ }+ // "Nobody said" is treated as "cannot decode": not encoding costs a loud 400+ // on an over-long name; encoding with no decoder drops the call in silence.+ expect(wireDecodesToolNames(undefined)).toBe(false);+});++// ─── The composition decides, not the request shape ─────────────────────────++test("an openai transport answering anthropic-sse does NOT encode", () => {+ const adapter = composeOpenAiTransportEndpoint("anthropic-sse");++ expect(adapter.getToolNameLimit()).toBeNull();++ const payload = payloadNamingTheLongTool();+ adapter.reset();+ adapter.prepareRequest(payload, { messages: [] });++ expect(payload.tools[0].function.name).toBe(REAL_LONG_NAME);+ expect(payload.tool_choice.function.name).toBe(REAL_LONG_NAME);+ // Nothing bound: an empty map is the honest statement that nothing needs+ // decoding, and it is what the anthropic-sse branch cannot accept anyway.+ expect(adapter.getToolNameMap().size).toBe(0);+});++test("the other two undecodable overrides are refused the same way", () => {+ for (const wire of ["gemini-sse", "ollama-jsonl"] as const) {+ expect(composeOpenAiTransportEndpoint(wire).getToolNameLimit()).toBeNull();+ }+});++test("an openai transport answering openai-sse still encodes", () => {+ // The non-regression half: the fix must not switch the codec off for the+ // ordinary custom endpoint, which is every one that declares no streamFormat.+ for (const wire of ["openai-sse", undefined] as const) {+ const adapter = composeOpenAiTransportEndpoint(wire);+ expect(adapter.getToolNameLimit()).toBe(64);++ const payload = payloadNamingTheLongTool();+ adapter.reset();+ adapter.prepareRequest(payload, { messages: [] });++ const onTheWire = payload.tools[0].function.name;+ expect(onTheWire.length).toBe(64);+ expect(onTheWire).not.toBe(REAL_LONG_NAME);+ expect(payload.tool_choice.function.name).toBe(onTheWire);+ expect(adapter.getToolNameMap().get(onTheWire)).toBe(REAL_LONG_NAME);+ }+});++test("a provider override can also ARM the codec, not only disarm it", () => {+ // The override is consulted in both directions. An aggregator normalizes the+ // RESPONSE to openai-sse whatever the adapter declares (OpenRouter and LiteLLM+ // both hardcode that), so a composition whose adapter would answer+ // "anthropic-sse" on its own still gets a decoding parser — and must encode.+ const provider = customEndpointProvider("openai-sse");+ const transport = new OpenAIProviderTransport(provider, "relay-model", "sk-test");+ const adapter = new OpenAIAPIFormat("relay-model", "anthropic-sse");++ // Composed alone it would refuse, on the composed REQUEST wire.+ expect(adapter.getToolNameLimit()).toBeNull();++ new ComposedHandler(transport, "corp@relay-model", "relay-model", 8080, { adapter });+ expect(adapter.getToolNameLimit()).toBe(64);+});