Skip to content

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.ts
index 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.ts
index 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.ts
index 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 adapters
const map = new Map(super.getToolNameMap());
diff --git a/packages/cli/src/adapters/tool-name-utils.ts b/packages/cli/src/adapters/tool-name-utils.ts
index 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.ts
index 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 file
type 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.ts
new file mode 100644
index 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);
+});