Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

fix(adapters): a reversible 64-char tool-name codec on every OpenAI wire (item 7)

Jack Rudenko2e18042c6750
diff --git a/packages/cli/src/adapters/base-api-format.ts b/packages/cli/src/adapters/base-api-format.ts
index b6b31ef8..80643738 100644
--- a/packages/cli/src/adapters/base-api-format.ts
+++ b/packages/cli/src/adapters/base-api-format.ts
@@ -16,7 +16,7 @@ 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 { truncateToolName } from "./tool-name-utils.js";
+import { type ToolNameBindings, encodeToolName, newToolNameBindings } from "./tool-name-utils.js";
/**
* The OPTIONAL parameters {@link BaseAPIFormat.applyOpenAISamplingParams} adds
@@ -26,6 +26,13 @@ import { truncateToolName } from "./tool-name-utils.js";
*/
const OPTIONAL_SAMPLING_PARAMS: readonly string[] = ["stop", "top_p"];
+/**
+ * OpenAI validates a function name against `^[a-zA-Z0-9_-]{1,64}$` on both the
+ * Chat Completions and the Responses shape. 64 is that limit, not a guess about
+ * any one model.
+ */
+const OPENAI_TOOL_NAME_LIMIT = 64;
+
/**
* Match a model ID against a model family name, handling vendor-prefixed IDs.
*
@@ -128,10 +135,18 @@ export abstract class BaseAPIFormat implements APIFormat, ModelDialect {
protected readonly wireFormat?: StreamFormat;
/**
- * Map of truncated tool names back to original names.
- * Populated during prepareRequest() when tool names are truncated.
+ * This request's tool-name bindings, in both directions.
+ *
+ * PER REQUEST, and REPLACED rather than cleared — never mutated after it has
+ * been handed out. Handlers are cached one per model while `claudish serve`
+ * hosts several conversations, so the instance is shared: clearing the map
+ * that request A's parser is still decoding with, because request B started,
+ * turns A's tool calls into names nothing recognises — and `keepOnlyRealTools`
+ * then drops them with no error anywhere. `adapters.md` records the same
+ * hazard class for `getHeaders`. `reset()` mints a new pair; the old one stays
+ * whole for whoever is still reading it.
*/
- protected toolNameMap: Map<string, string> = new Map();
+ protected toolNameBindings: ToolNameBindings = newToolNameBindings();
constructor(modelId: string, wireFormat?: StreamFormat) {
this.modelId = modelId;
@@ -244,11 +259,30 @@ export abstract class BaseAPIFormat implements APIFormat, ModelDialect {
}
/**
- * Maximum tool name length allowed by this model's API.
- * Returns null if no limit (default).
+ * 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
+ * truncated at all — and a real 65-character MCP name
+ * (`mcp__plugin_browser-use_browser-use__retry_with_browser_use_agent`) fails
+ * 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 {
- return 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;
}
/**
@@ -264,18 +298,22 @@ export abstract class BaseAPIFormat implements APIFormat, ModelDialect {
}
/**
- * Get the tool name map (truncated -> original).
- * Use after prepareRequest() to get the mapping for response processing.
+ * This request's decode map (encoded → original).
+ *
+ * Read it ONCE, immediately after `prepareRequest`, and thread that reference
+ * onward — do not re-read it after an `await`. `reset()` replaces the
+ * bindings, so a later read on a shared handler returns the NEXT request's
+ * map.
*/
getToolNameMap(): Map<string, string> {
- return this.toolNameMap;
+ return this.toolNameBindings.byEncoded;
}
/**
- * Restore a potentially truncated tool name to its original.
+ * Restore a possibly-encoded tool name to its original.
*/
restoreToolName(name: string): string {
- return this.toolNameMap.get(name) || name;
+ return this.toolNameBindings.byEncoded.get(name) || name;
}
/**
@@ -309,6 +347,12 @@ export abstract class BaseAPIFormat implements APIFormat, ModelDialect {
prepareRequest(request: any, originalRequest: any): any {
const prepared = this.prepareRequestCommon(request, originalRequest) ?? request;
+ // Tool-name encoding lives in the TEMPLATE, not in the hook, so that every
+ // adapter gets it exactly once and no subclass can lose it by overriding
+ // `prepareRequestCommon` without calling super — which is how it came to be
+ // on OpenAIAPIFormat and Xiaomi alone. One call site for the whole tree.
+ this.encodeToolNames(prepared);
+
if (!this.isAnthropicWire()) {
return this.applyNativeReasoning(prepared, originalRequest) ?? prepared;
}
@@ -631,7 +675,9 @@ export abstract class BaseAPIFormat implements APIFormat, ModelDialect {
* Reset internal state between requests (prevents state contamination)
*/
reset(): void {
- this.toolNameMap.clear();
+ // REPLACE, never clear: a parser from the previous request may still be
+ // decoding with the old map. See {@link toolNameBindings}.
+ this.toolNameBindings = newToolNameBindings();
}
// ─── ComposedHandler integration (Phase 1c) ───────────────────────
@@ -765,52 +811,73 @@ export abstract class BaseAPIFormat implements APIFormat, ModelDialect {
}
/**
- * Truncate tool names in the request payload if the model has a name length limit.
- * Handles both Chat Completions format ({type:"function", function:{name}})
- * and Responses API format ({type:"function", name}).
- * Stores the mapping in this.toolNameMap for reverse mapping in responses.
+ * Rewrite every tool name in this payload into what the wire accepts, and
+ * record the way back.
+ *
+ * THREE places carry a tool name, and all three must agree or the request is
+ * worse than it was before:
+ *
+ * 1. `tools[]` — what the model may call. Both shapes: Chat Completions
+ * `{type:"function", function:{name}}` and the Responses API's flat
+ * `{type:"function", name}`.
+ * 2. The HISTORY — `messages[]` assistant `tool_calls`, and the Responses
+ * API's `input[]` `function_call` items. A history naming a tool that is
+ * not in `tools[]` is rejected by strict endpoints and confuses every
+ * other one.
+ * 3. `tool_choice` — pointing at a name the model was never offered is a
+ * 400 on the first forced-tool turn.
+ *
+ * Encoding runs on the BUILT payload rather than inside each builder because
+ * that is where all three live, and because the map has to be minted
+ * somewhere both the payload and the parser can see.
+ *
+ * Idempotent: an already-encoded name transforms to itself and is bound to
+ * itself, so a delegating adapter that runs this after its inner adapter
+ * already did changes nothing.
*/
- protected truncateToolNames(request: any): void {
+ protected encodeToolNames(request: any): void {
const limit = this.getToolNameLimit();
- if (!limit || !request.tools) return;
-
- for (const tool of request.tools) {
- const originalName = tool.function?.name || tool.name;
- if (originalName && originalName.length > limit) {
- const truncated = truncateToolName(originalName, limit);
- this.toolNameMap.set(truncated, originalName);
- if (tool.function?.name) {
- tool.function.name = truncated;
- } else if (tool.name) {
- tool.name = truncated;
+ if (!limit || !request) return;
+
+ const encode = (name: string) => encodeToolName(name, limit, this.toolNameBindings);
+
+ if (Array.isArray(request.tools)) {
+ for (const tool of request.tools) {
+ if (tool?.function?.name) {
+ tool.function.name = encode(tool.function.name);
+ } else if (tool?.name) {
+ tool.name = encode(tool.name);
}
}
}
- }
-
- /**
- * Truncate tool names in assistant message history (for messages array).
- * This is needed because historical tool_use blocks in the conversation
- * may contain names that exceed the model's limit.
- */
- protected truncateToolNamesInMessages(messages: any[]): void {
- const limit = this.getToolNameLimit();
- if (!limit) return;
- for (const msg of messages) {
- if (msg.role === "assistant" && Array.isArray(msg.tool_calls)) {
+ if (Array.isArray(request.messages)) {
+ for (const msg of request.messages) {
+ if (msg?.role !== "assistant" || !Array.isArray(msg.tool_calls)) continue;
for (const tc of msg.tool_calls) {
- const name = tc.function?.name;
- if (name && name.length > limit) {
- const truncated = truncateToolName(name, limit);
- tc.function.name = truncated;
- if (!this.toolNameMap.has(truncated)) {
- this.toolNameMap.set(truncated, name);
- }
- }
+ if (tc?.function?.name) tc.function.name = encode(tc.function.name);
}
}
}
+
+ // Responses API history. `input` holds `function_call` items rather than an
+ // assistant message with `tool_calls`, so the branch above cannot see them.
+ if (Array.isArray(request.input)) {
+ for (const item of request.input) {
+ if (item?.type === "function_call" && item.name) item.name = encode(item.name);
+ }
+ }
+
+ const choice = request.tool_choice;
+ if (choice && typeof choice === "object") {
+ // `{type:"function", function:{name}}` (chat) and `{type:"function", name}`
+ // (responses). The string forms — "auto"/"none"/"required" — name nothing.
+ if (choice.function?.name) {
+ choice.function.name = encode(choice.function.name);
+ } else if (choice.name) {
+ choice.name = encode(choice.name);
+ }
+ }
}
}
diff --git a/packages/cli/src/adapters/grok-model-dialect.ts b/packages/cli/src/adapters/grok-model-dialect.ts
index 5da3d92c..034a8f4f 100644
--- a/packages/cli/src/adapters/grok-model-dialect.ts
+++ b/packages/cli/src/adapters/grok-model-dialect.ts
@@ -288,9 +288,15 @@ export class GrokModelDialect extends BaseAPIFormat {
}
/**
- * Reset internal state (useful between requests)
+ * Reset internal state (useful between requests).
+ *
+ * `super.reset()` is load-bearing: it mints this request's tool-name
+ * bindings. Without it they accumulate for the life of the process, because
+ * this override used to replace the base entirely — harmless while nothing
+ * encoded names, not harmless now.
*/
- reset(): void {
+ override reset(): void {
+ super.reset();
this.xmlBuffer = "";
}
}
diff --git a/packages/cli/src/adapters/local-adapter.ts b/packages/cli/src/adapters/local-adapter.ts
index 621e794f..adeb8f49 100644
--- a/packages/cli/src/adapters/local-adapter.ts
+++ b/packages/cli/src/adapters/local-adapter.ts
@@ -138,14 +138,14 @@ export class LocalModelAdapter extends BaseAPIFormat {
// ─── Request post-processing ────────────────────────────────────────
protected override prepareRequestCommon(request: any, originalRequest: any): any {
- // Delegate to inner adapter (Qwen tool name truncation, etc.)
+ // Delegate to inner adapter (Qwen tool name encoding, etc.). The inner
+ // adapter's template encodes the names into ITS bindings; this adapter's
+ // template then runs over an already-encoded payload and changes nothing.
+ // `getToolNameMap()` below merges both, so there is no eager copy here —
+ // copying into this instance's bindings would also mean mutating a map the
+ // previous request's parser may still be holding.
this.innerAdapter.prepareRequest(request, originalRequest);
- // Merge inner adapter's tool name map
- for (const [k, v] of this.innerAdapter.getToolNameMap()) {
- this.toolNameMap.set(k, v);
- }
-
// Strip cloud-only thinking params that local providers don't understand
delete request.enable_thinking;
delete request.thinking_budget;
diff --git a/packages/cli/src/adapters/openai-api-format.ts b/packages/cli/src/adapters/openai-api-format.ts
index 6070905c..6a377089 100644
--- a/packages/cli/src/adapters/openai-api-format.ts
+++ b/packages/cli/src/adapters/openai-api-format.ts
@@ -40,15 +40,9 @@ export class OpenAIAPIFormat extends BaseAPIFormat {
return 128;
}
- /** Tool name truncation — a wire-agnostic API constraint. */
- protected override prepareRequestCommon(request: any, _originalRequest: any): any {
- this.truncateToolNames(request);
- if (request.messages) {
- this.truncateToolNamesInMessages(request.messages);
- }
-
- return request;
- }
+ // Tool-name encoding used to live here, and here ONLY, which is why no other
+ // OpenAI-shaped adapter did it. It is now in `prepareRequest`'s template, so
+ // this hook has nothing left to do.
/**
* OpenAI's own reasoning knob. Not called on the Anthropic wire.
diff --git a/packages/cli/src/adapters/tool-name-codec.test.ts b/packages/cli/src/adapters/tool-name-codec.test.ts
new file mode 100644
index 00000000..9b8ec4e1
--- /dev/null
+++ b/packages/cli/src/adapters/tool-name-codec.test.ts
@@ -0,0 +1,210 @@
+/**
+ * Item 7 — the reversible 64-char tool-name codec, and the one pass that
+ * applies it.
+ *
+ * ## Provenance of the inputs
+ *
+ * REQUEST-side. `test-fixtures/sse-responses/` holds response streams, not
+ * inbound bodies, so no capture in the tree can reach a payload builder or
+ * `prepareRequest`. The payloads below are constructed inline and assert only
+ * this tree's own contract. No `.sse` fixture was invented. The decode half,
+ * which IS response-side, is exercised in
+ * `handlers/shared/stream-parsers/tool-name-mangling.test.ts`.
+ */
+
+import { expect, test } from "bun:test";
+import { AnthropicAPIFormat } from "./anthropic-api-format.js";
+import { DefaultAPIFormat } from "./base-api-format.js";
+import { CodexAPIFormat } from "./codex-api-format.js";
+import { GeminiAPIFormat } from "./gemini-api-format.js";
+import { OpenAIAPIFormat } from "./openai-api-format.js";
+import { TOOL_NAME_SHAPE, encodeToolName, newToolNameBindings } from "./tool-name-utils.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";
+
+const WIRE_CHARSET = /^[A-Za-z0-9_-]{1,64}$/;
+
+test("the motivating name is genuinely over the limit", () => {
+ expect(REAL_LONG_NAME.length).toBeGreaterThan(64);
+});
+
+test("a name that already fits the wire is returned untouched", () => {
+ const b = newToolNameBindings();
+ expect(encodeToolName("Read", 64, b)).toBe("Read");
+ expect(encodeToolName("mcp__magus__team", 64, b)).toBe("mcp__magus__team");
+});
+
+test("an over-long name becomes exactly 64 wire-legal characters, and decodes", () => {
+ const b = newToolNameBindings();
+ const encoded = encodeToolName(REAL_LONG_NAME, 64, b);
+
+ expect(encoded.length).toBe(64);
+ expect(encoded).toMatch(WIRE_CHARSET);
+ // It must also satisfy the ONE definition of a tool name's shape, or the
+ // recovery path and the stats recorder will reject what we ourselves sent.
+ expect(TOOL_NAME_SHAPE.test(encoded)).toBe(true);
+ expect(b.byEncoded.get(encoded)).toBe(REAL_LONG_NAME);
+});
+
+test("characters the wire refuses are mapped out", () => {
+ const b = newToolNameBindings();
+ const encoded = encodeToolName("server.tool:v2", 64, b);
+ expect(encoded).toBe("server_tool_v2");
+ expect(encoded).toMatch(WIRE_CHARSET);
+ expect(b.byEncoded.get(encoded)).toBe("server.tool:v2");
+});
+
+test("SHORT names that transform onto each other do not collide", () => {
+ // The defect this closes: `a.b` and `a_b` both charset-map to `a_b`, at a
+ // length no truncation rule would ever look at. Whichever registered last
+ // used to own the name, so the model's call went to the wrong tool.
+ const b = newToolNameBindings();
+ const first = encodeToolName("a_b", 64, b);
+ const second = encodeToolName("a.b", 64, b);
+
+ expect(first).toBe("a_b");
+ expect(second).not.toBe(first);
+ expect(second).toMatch(WIRE_CHARSET);
+ expect(b.byEncoded.get(first)).toBe("a_b");
+ expect(b.byEncoded.get(second)).toBe("a.b");
+});
+
+test("an identity encoding still CLAIMS the name, whichever order they arrive in", () => {
+ const b = newToolNameBindings();
+ // Reverse order of the previous test: the dotted one goes first and takes
+ // `a_b`; the literal `a_b` must then be moved, not silently overwritten.
+ const dotted = encodeToolName("a.b", 64, b);
+ const literal = encodeToolName("a_b", 64, b);
+
+ expect(dotted).toBe("a_b");
+ expect(literal).not.toBe(dotted);
+ expect(b.byEncoded.get(dotted)).toBe("a.b");
+ expect(b.byEncoded.get(literal)).toBe("a_b");
+});
+
+test("encoding is stable within a request", () => {
+ const b = newToolNameBindings();
+ const once = encodeToolName(REAL_LONG_NAME, 64, b);
+ const twice = encodeToolName(REAL_LONG_NAME, 64, b);
+ expect(twice).toBe(once);
+ // …and deterministic across requests, so a name in HISTORY encodes to the
+ // same thing as the same name in `tools[]`.
+ expect(encodeToolName(REAL_LONG_NAME, 64, newToolNameBindings())).toBe(once);
+});
+
+test("encoding an already-encoded name is the identity — the pass is idempotent", () => {
+ const first = newToolNameBindings();
+ const encoded = encodeToolName(REAL_LONG_NAME, 64, first);
+ const second = newToolNameBindings();
+ expect(encodeToolName(encoded, 64, second)).toBe(encoded);
+});
+
+// ─── The limit is a rule about the wire ─────────────────────────────────────
+
+test("64 on OpenAI-shaped wires, null on every other", () => {
+ expect(new OpenAIAPIFormat("gpt-4o").getToolNameLimit()).toBe(64);
+ expect(new CodexAPIFormat("gpt-5.1-codex").getToolNameLimit()).toBe(64);
+ expect(new DefaultAPIFormat("anything").getToolNameLimit()).toBe(64);
+
+ expect(new GeminiAPIFormat("gemini-3-pro").getToolNameLimit()).toBeNull();
+ expect(new AnthropicAPIFormat("claude-x").getToolNameLimit()).toBeNull();
+});
+
+test("the COMPOSED wire wins over a dialect's own default", () => {
+ // A dialect self-selects by model name and always answers "openai-sse" for
+ // itself. Under a wire whose parser holds no map, it must not encode.
+ expect(new DefaultAPIFormat("anything", "anthropic-sse").getToolNameLimit()).toBeNull();
+ expect(new DefaultAPIFormat("anything", "ollama-jsonl").getToolNameLimit()).toBeNull();
+ expect(new DefaultAPIFormat("anything", "gemini-sse").getToolNameLimit()).toBeNull();
+ expect(new DefaultAPIFormat("anything", "openai-sse").getToolNameLimit()).toBe(64);
+});
+
+// ─── One pass, all three places a name lives ────────────────────────────────
+
+test("tools, history and tool_choice are encoded, and they agree", () => {
+ const fmt = new OpenAIAPIFormat("gpt-4o");
+ fmt.reset();
+ const payload = {
+ model: "gpt-4o",
+ tools: [{ type: "function", function: { name: REAL_LONG_NAME } }],
+ messages: [
+ { role: "user", content: "go" },
+ {
+ role: "assistant",
+ tool_calls: [{ id: "c1", type: "function", function: { name: REAL_LONG_NAME } }],
+ },
+ { role: "tool", tool_call_id: "c1", content: "done" },
+ ],
+ tool_choice: { type: "function", function: { name: REAL_LONG_NAME } },
+ };
+
+ fmt.prepareRequest(payload, { messages: [] });
+
+ const onTheWire = payload.tools[0].function.name;
+ expect(onTheWire.length).toBe(64);
+ expect(onTheWire).not.toBe(REAL_LONG_NAME);
+ // All three agree — a history or a tool_choice naming something absent from
+ // tools[] is a 400 on strict endpoints and confusion everywhere else.
+ expect((payload.messages[1] as any).tool_calls[0].function.name).toBe(onTheWire);
+ expect(payload.tool_choice.function.name).toBe(onTheWire);
+ expect(fmt.getToolNameMap().get(onTheWire)).toBe(REAL_LONG_NAME);
+ expect(fmt.restoreToolName(onTheWire)).toBe(REAL_LONG_NAME);
+});
+
+test("the Responses API's own two shapes are encoded too", () => {
+ const fmt = new CodexAPIFormat("gpt-5.1-codex");
+ fmt.reset();
+ const payload = {
+ model: "gpt-5.1-codex",
+ // Flat tools, and history as `input` items rather than assistant messages.
+ tools: [{ type: "function", name: REAL_LONG_NAME }],
+ input: [
+ { type: "function_call", call_id: "c1", name: REAL_LONG_NAME, arguments: "{}" },
+ { type: "function_call_output", call_id: "c1", output: "ok" },
+ ],
+ tool_choice: { type: "function", name: REAL_LONG_NAME },
+ };
+
+ fmt.prepareRequest(payload, { messages: [] });
+
+ const onTheWire = payload.tools[0].name;
+ expect(onTheWire.length).toBe(64);
+ expect(payload.input[0].name).toBe(onTheWire);
+ expect(payload.tool_choice.name).toBe(onTheWire);
+ expect(fmt.getToolNameMap().get(onTheWire)).toBe(REAL_LONG_NAME);
+});
+
+test("a wire with no limit leaves every name alone", () => {
+ const fmt = new GeminiAPIFormat("gemini-3-pro");
+ fmt.reset();
+ const payload = {
+ tools: [{ function: { name: REAL_LONG_NAME } }],
+ tool_choice: { type: "function", function: { name: REAL_LONG_NAME } },
+ };
+ fmt.prepareRequest(payload, { messages: [] });
+ expect(payload.tools[0].function.name).toBe(REAL_LONG_NAME);
+ expect(payload.tool_choice.function.name).toBe(REAL_LONG_NAME);
+});
+
+// ─── The map is per request ─────────────────────────────────────────────────
+
+test("reset() mints a new map instead of clearing the one already handed out", () => {
+ const fmt = new OpenAIAPIFormat("gpt-4o");
+ fmt.reset();
+ fmt.prepareRequest({ tools: [{ type: "function", function: { name: REAL_LONG_NAME } }] }, {});
+
+ // What request A's parser is holding.
+ const mapA = fmt.getToolNameMap();
+ const encodedA = [...mapA.keys()][0];
+ expect(mapA.get(encodedA)).toBe(REAL_LONG_NAME);
+
+ // Request B starts on the same cached handler.
+ fmt.reset();
+ fmt.prepareRequest({ tools: [{ type: "function", function: { name: "Read" } }] }, {});
+
+ // A's map still decodes. Clearing it here would have turned A's tool calls
+ // into names nothing recognises, and the allowlist drops those in silence.
+ expect(mapA.get(encodedA)).toBe(REAL_LONG_NAME);
+ expect(fmt.getToolNameMap()).not.toBe(mapA);
+});
diff --git a/packages/cli/src/adapters/tool-name-utils.ts b/packages/cli/src/adapters/tool-name-utils.ts
index 12e5a154..e73bd422 100644
--- a/packages/cli/src/adapters/tool-name-utils.ts
+++ b/packages/cli/src/adapters/tool-name-utils.ts
@@ -57,3 +57,100 @@ export function truncateToolName(name: string, maxLength: number): string {
);
return truncated;
}
+
+// ─── The wire codec ─────────────────────────────────────────────────────────
+
+/**
+ * Characters an OpenAI-shaped wire accepts in a function name.
+ *
+ * This is a DIFFERENT question from {@link TOOL_NAME_SHAPE}, and the two must
+ * not be merged. `TOOL_NAME_SHAPE` answers "may this string occupy a tool-name
+ * slot in something we parsed" — it stays the single definition of that, and it
+ * deliberately admits `.`, because a name we READ may legally contain one.
+ * This charset answers "what will the endpoint accept", and OpenAI's function
+ * name is validated against `^[a-zA-Z0-9_-]{1,64}$`, which admits no dot.
+ *
+ * Anything outside it is mapped to `_`, and the map records the way back.
+ */
+const UNWIRABLE_CHARACTER = /[^A-Za-z0-9_-]/g;
+
+/** The two directions of one request's codec. Both are per-request; see reset(). */
+export interface ToolNameBindings {
+ /** encoded → original. This is the map the stream parser decodes with. */
+ byEncoded: Map<string, string>;
+ /** original → encoded. Makes the encoding stable within a request. */
+ byOriginal: Map<string, string>;
+}
+
+/** A fresh, empty pair of bindings. */
+export function newToolNameBindings(): ToolNameBindings {
+ return { byEncoded: new Map(), byOriginal: new Map() };
+}
+
+/** `prefix` + `_` + 8 hex, exactly `limit` characters. */
+function hashedForm(transformed: string, original: string, limit: number, salt: number): string {
+ const seed = salt === 0 ? original : `${original}#${salt}`;
+ const prefix = transformed.slice(0, Math.max(0, limit - 9));
+ return `${prefix}_${hashToolName(seed)}`;
+}
+
+/**
+ * Encode a tool name for an OpenAI-shaped wire, reversibly.
+ *
+ * Two transformations, in this order:
+ *
+ * 1. **Charset.** Every character outside {@link UNWIRABLE_CHARACTER}'s
+ * complement becomes `_`.
+ * 2. **Length and collisions.** A transformed name longer than `limit`, OR one
+ * already bound to a DIFFERENT original, becomes
+ * `prefix + "_" + hash8(original)`.
+ *
+ * Step 2's collision arm is not an optimisation. Charset-mapping makes `a.b`
+ * and `a_b` the same string, so two different tools can claim one encoded name
+ * at ANY length — and the map would then decode every call to whichever of them
+ * was registered last, silently handing the model's call to the wrong tool.
+ * Length was never the only way to collide.
+ *
+ * Every binding is recorded, identity ones included, because an identity
+ * encoding CLAIMS that name: without the record, a later `a.b` would transform
+ * onto an unregistered `a_b` and win it from the real `a_b`.
+ *
+ * The hash is the collision GUARD, not an inverse. A codec cannot be reversible
+ * from an arbitrary-length name into a 64-character slot — the map is
+ * authoritative, and that is why it must reach the parser intact.
+ */
+export function encodeToolName(
+ original: string,
+ limit: number,
+ bindings: ToolNameBindings
+): string {
+ const already = bindings.byOriginal.get(original);
+ if (already !== undefined) return already;
+
+ const transformed = original.replace(UNWIRABLE_CHARACTER, "_");
+ const takenByAnother = (name: string) => {
+ const owner = bindings.byEncoded.get(name);
+ return owner !== undefined && owner !== original;
+ };
+
+ let encoded =
+ transformed.length <= limit ? transformed : hashedForm(transformed, original, limit, 0);
+ if (takenByAnother(encoded)) {
+ // Salt only ever advances on a hash8 collision between two DIFFERENT
+ // originals, which is vanishingly rare — but "vanishingly rare" and
+ // "silently hands the model's call to another tool" is the wrong pair.
+ let salt = 0;
+ do {
+ encoded = hashedForm(transformed, original, limit, salt++);
+ } while (takenByAnother(encoded));
+ }
+
+ bindings.byEncoded.set(encoded, original);
+ bindings.byOriginal.set(original, encoded);
+ if (encoded !== original) {
+ log(
+ `[ToolName] Encoded: "${original}" -> "${encoded}" (${original.length} -> ${encoded.length})`
+ );
+ }
+ return encoded;
+}
diff --git a/packages/cli/src/adapters/xiaomi-model-dialect.ts b/packages/cli/src/adapters/xiaomi-model-dialect.ts
index 553fff8f..89789352 100644
--- a/packages/cli/src/adapters/xiaomi-model-dialect.ts
+++ b/packages/cli/src/adapters/xiaomi-model-dialect.ts
@@ -19,19 +19,11 @@ export class XiaomiModelDialect extends BaseAPIFormat {
};
}
- override getToolNameLimit(): number {
- return 64;
- }
-
- protected override prepareRequestCommon(request: any, _originalRequest: any): any {
- // Truncate tool names to 64 chars — a wire-agnostic API constraint.
- this.truncateToolNames(request);
- if (request.messages) {
- this.truncateToolNamesInMessages(request.messages);
- }
-
- return request;
- }
+ // The 64-char limit and the truncation call that used to stand here are gone:
+ // `BaseAPIFormat.getToolNameLimit()` now returns 64 for every OpenAI-shaped
+ // wire, and `prepareRequest`'s template applies it. Xiaomi enforces the limit
+ // strictly, which is why this dialect was the only adapter in the tree that
+ // ever truncated at all — it is no longer special.
protected override applyNativeReasoning(request: any, originalRequest: any): any {
// Xiaomi's own API doesn't support thinking params.
diff --git a/packages/cli/src/handlers/composed-handler.ts b/packages/cli/src/handlers/composed-handler.ts
index fc0ac8d7..6fd015d2 100644
--- a/packages/cli/src/handlers/composed-handler.ts
+++ b/packages/cli/src/handlers/composed-handler.ts
@@ -1488,7 +1488,11 @@ export class ComposedHandler implements ModelHandler {
return createResponsesStreamHandler(c, response, {
modelName: this.bareModelName,
onTokenUpdate,
- toolNameMap: adapter.getToolNameMap(),
+ // The map THIS request captured right after prepareRequest — not a
+ // fresh read. This runs after an awaited fetch, and on a handler
+ // shared by two conversations the adapter's own map may already
+ // belong to the next request by now.
+ toolNameMap,
contextWindow: lookupModelForProvider(this.bareModelName, this.provider.name),
onApiError,
priorInputTokens,
diff --git a/packages/cli/src/handlers/shared/format/openai-tools.ts b/packages/cli/src/handlers/shared/format/openai-tools.ts
index ed1aea68..2b2c8e9b 100644
--- a/packages/cli/src/handlers/shared/format/openai-tools.ts
+++ b/packages/cli/src/handlers/shared/format/openai-tools.ts
@@ -317,6 +317,12 @@ export type ResponsesToolChoice = string | { type: "function"; name: string };
* @param choice - the inbound `tool_choice`, if any
* @param encodeName - applied to the named tool, so a wire that renames tools
* names the SAME tool here as in `tools[]`. Identity when omitted.
+ *
+ * NOTE on `encodeName`: production does not pass it. Tool-name encoding runs as
+ * a post-pass over the BUILT payload (`BaseAPIFormat.encodeToolNames`), because
+ * the name also lives in the message history, which no `tool_choice` mapper can
+ * reach — and because the codec's map is minted there. The hook stays for a
+ * builder that ever has the bindings in hand before it builds.
*/
export function mapToolChoiceToOpenAI(
choice: ClaudeToolChoice | null | undefined,
diff --git a/packages/cli/src/handlers/shared/stream-parsers/openai-sse.ts b/packages/cli/src/handlers/shared/stream-parsers/openai-sse.ts
index 45ddaee9..75d231fb 100644
--- a/packages/cli/src/handlers/shared/stream-parsers/openai-sse.ts
+++ b/packages/cli/src/handlers/shared/stream-parsers/openai-sse.ts
@@ -420,7 +420,11 @@ export function createStreamingResponseHandler(
// The `<function=NAME><parameter=P>` envelope carries no
// types, so every value arrives as a string. The schemas are
// what turn `"5"` back into 5 and `"true"` into true.
- toolSchemas as ToolSchema[] | undefined
+ toolSchemas as ToolSchema[] | undefined,
+ // Recovery reads the name the MODEL wrote, which is the
+ // encoded one. The allowlist is built from the client's
+ // originals, so an undecoded name is dropped in silence.
+ toolNameMap ? (name: string) => toolNameMap.get(name) ?? name : undefined
);
if (state.tools.size > 0 && state.accumulatedText.length > 0) {
log(
@@ -835,13 +839,14 @@ export function createStreamingResponseHandler(
const accumulatedName =
(state.pendingToolName.get(idx) ?? "") + tc.function.name;
state.pendingToolName.set(idx, accumulatedName);
+ // THIS IS THE DECODE POINT: it reads the accumulated name,
+ // never a single chunk's fragment. Decoding a fragment
+ // misses the map, and the allowlist then drops the call
+ // in silence.
+ const restoredName = toolNameMap?.get(accumulatedName) || accumulatedName;
if (!t) {
// The hand-written "close thinking, then close text"
// pair that used to stand here is `openTool`'s job now.
- // Restore truncated tool name to original if mapping exists.
- // THIS IS THE DECODE POINT: it reads the accumulated name,
- // never a single chunk's fragment.
- const restoredName = toolNameMap?.get(accumulatedName) || accumulatedName;
t = {
id: tc.id || `tool_${Date.now()}_${idx}`,
name: restoredName,
@@ -871,6 +876,28 @@ export function createStreamingResponseHandler(
if (isWebSearchToolCall(restoredName)) {
warnWebSearchUnsupported(restoredName, target);
}
+ } else if (t.name !== restoredName) {
+ // A LATER fragment completed the name. The tool was
+ // created from the first fragment, so its name is a
+ // prefix — and a prefix of an encoded name decodes to
+ // nothing, which is how a call gets dropped without a
+ // word anywhere.
+ if (t.started) {
+ // The block is already on the wire under the short
+ // name; it cannot be recalled. "error" is deliberate
+ // — it is what carries this to the structural log.
+ log(
+ `[Streaming] error: tool block ${t.blockIndex} was started as "${t.name}" but the full name is "${restoredName}" — the client sees the wrong name`
+ );
+ } else {
+ t.name = restoredName;
+ t.buffered =
+ (!!toolSchemas && toolSchemas.length > 0) ||
+ behavior?.shouldBufferTool?.(restoredName) === true;
+ if (isWebSearchToolCall(restoredName)) {
+ warnWebSearchUnsupported(restoredName, target);
+ }
+ }
}
// Only send content_block_start immediately if NOT buffering
if (!t.started && !t.buffered) {
diff --git a/packages/cli/src/handlers/shared/stream-parsers/tool-name-mangling.test.ts b/packages/cli/src/handlers/shared/stream-parsers/tool-name-mangling.test.ts
index 93777ace..f8216d45 100644
--- a/packages/cli/src/handlers/shared/stream-parsers/tool-name-mangling.test.ts
+++ b/packages/cli/src/handlers/shared/stream-parsers/tool-name-mangling.test.ts
@@ -1,5 +1,6 @@
import { describe, expect, it } from "bun:test";
+import { encodeToolName, newToolNameBindings } from "../../../adapters/tool-name-utils.js";
import { createStreamingResponseHandler } from "./openai-sse.js";
const ctx: any = {
@@ -154,3 +155,162 @@ describe("openai-sse tool-name recovery", () => {
expect(unadvertised.observed).toEqual([]);
});
});
+
+// ─── Item 7: decoding the encoded name back ─────────────────────────────────
+//
+// These frames are CONSTRUCTED, as every frame in this file always has been:
+// the decode paths below cannot be reached from any capture in the tree (no
+// capture carries a >64-char tool name, and none splits `function.name` across
+// chunks). Nothing here is a `.sse` fixture, and no capture was invented.
+
+/** A real 65-char MCP name, and what the codec sends in its place. */
+const ORIGINAL = "mcp__plugin_browser-use_browser-use__retry_with_browser_use_agent";
+const ENCODED = encodeToolName(ORIGINAL, 64, newToolNameBindings());
+
+const longNameAdapter = {
+ getToolNameMap: () => new Map([[ENCODED, ORIGINAL]]),
+ processTextContent: (text: string) => ({
+ cleanedText: text,
+ extractedToolCalls: [],
+ wasTransformed: false,
+ }),
+};
+
+const longNameSchemas = [
+ {
+ name: ORIGINAL,
+ input_schema: {
+ type: "object",
+ properties: { task: { type: "string" } },
+ required: ["task"],
+ },
+ },
+];
+
+async function parseWithLongName(frames: string[]) {
+ const observed: string[] = [];
+ const response = createStreamingResponseHandler(
+ ctx,
+ sseResponse(frames),
+ longNameAdapter,
+ "test-model",
+ null,
+ undefined,
+ longNameSchemas,
+ longNameAdapter.getToolNameMap(),
+ undefined,
+ { onToolCallObserved: (name) => observed.push(name) }
+ );
+ const wire = await response.text();
+ return { observed, toolUses: toolUseStarts(wire), argumentJson: inputJson(wire) };
+}
+
+/** The `input_json_delta` payload, concatenated — where a tool's arguments land. */
+function inputJson(wire: string): string {
+ let json = "";
+ for (const frame of wire.split("\n\n")) {
+ const dataLine = frame.split("\n").find((line) => line.startsWith("data: "));
+ if (!dataLine || dataLine === "data: [DONE]") continue;
+ try {
+ const data = JSON.parse(dataLine.slice(6));
+ if (data.type === "content_block_delta" && data.delta?.type === "input_json_delta") {
+ json += data.delta.partial_json ?? "";
+ }
+ } catch {}
+ }
+ return json;
+}
+
+describe("openai-sse: the 64-char tool-name codec, decoded", () => {
+ it("decodes a name the model returned whole", async () => {
+ const result = await parseWithLongName([
+ dataFrame({
+ choices: [
+ {
+ delta: {
+ tool_calls: [
+ {
+ index: 0,
+ id: "call_0",
+ type: "function",
+ function: { name: ENCODED, arguments: '{"task":"x"}' },
+ },
+ ],
+ },
+ finish_reason: null,
+ },
+ ],
+ }),
+ finishFrame("tool_calls"),
+ "data: [DONE]\n\n",
+ ]);
+
+ expect(result.toolUses).toHaveLength(1);
+ expect(result.toolUses[0].name).toBe(ORIGINAL);
+ expect(result.observed).toEqual([ORIGINAL]);
+ });
+
+ it("decodes a name that arrived in FRAGMENTS across chunks", async () => {
+ // The defect: the tool is created from the first fragment, and a prefix of
+ // an encoded name decodes to nothing — so the call is dropped with no error
+ // anywhere. Decoding must happen against the ACCUMULATED name, and the tool
+ // created early must be revised when the rest arrives.
+ const head = ENCODED.slice(0, 7);
+ const mid = ENCODED.slice(7, 40);
+ const tail = ENCODED.slice(40);
+
+ const result = await parseWithLongName([
+ dataFrame({
+ choices: [
+ {
+ delta: {
+ tool_calls: [{ index: 0, id: "call_0", type: "function", function: { name: head } }],
+ },
+ finish_reason: null,
+ },
+ ],
+ }),
+ dataFrame({
+ choices: [
+ { delta: { tool_calls: [{ index: 0, function: { name: mid } }] }, finish_reason: null },
+ ],
+ }),
+ dataFrame({
+ choices: [
+ { delta: { tool_calls: [{ index: 0, function: { name: tail } }] }, finish_reason: null },
+ ],
+ }),
+ dataFrame({
+ choices: [
+ {
+ delta: { tool_calls: [{ index: 0, function: { arguments: '{"task":"x"}' } }] },
+ finish_reason: null,
+ },
+ ],
+ }),
+ finishFrame("tool_calls"),
+ "data: [DONE]\n\n",
+ ]);
+
+ expect(result.toolUses).toHaveLength(1);
+ expect(result.toolUses[0].name).toBe(ORIGINAL);
+ // The arguments that arrived after the name survived the revision.
+ expect(result.argumentJson).toBe('{"task":"x"}');
+ expect(result.observed).toEqual([ORIGINAL]);
+ });
+
+ it("decodes a call RECOVERED from prose", async () => {
+ // The model writes the name it was given — the encoded one — while the
+ // recovery allowlist is built from the client's originals. Undecoded, the
+ // allowlist drops it and nothing says so.
+ const result = await parseWithLongName([
+ textFrame(`<function=${ENCODED}><parameter=task>x`),
+ finishFrame("stop"),
+ "data: [DONE]\n\n",
+ ]);
+
+ expect(result.toolUses).toHaveLength(1);
+ expect(result.toolUses[0].name).toBe(ORIGINAL);
+ expect(result.observed).toEqual([ORIGINAL]);
+ });
+});
diff --git a/packages/cli/src/handlers/shared/tool-call-recovery.ts b/packages/cli/src/handlers/shared/tool-call-recovery.ts
index ad48feb0..e24e5cef 100644
--- a/packages/cli/src/handlers/shared/tool-call-recovery.ts
+++ b/packages/cli/src/handlers/shared/tool-call-recovery.ts
@@ -76,15 +76,24 @@ export function hasExtractableFunctionTag(text: string): boolean {
/**
* Drop extracted calls that are not real tools.
*
- * Two gates. The shape gate rejects a name that is not an identifier, which is
- * how a swallowed argument value is caught. The allowlist gate rejects a
- * well-shaped name the client never advertised, which is how a hallucinated tool
- * is caught. The allowlist is the request's own tool list, so it is exact rather
- * than a hardcoded roster.
+ * Three steps, and the ORDER is the design:
+ *
+ * 1. **Shape.** Reject a name that is not an identifier — this is how a
+ * swallowed argument value is caught. It runs on the name as it came off
+ * the WIRE, which is the only name `TOOL_NAME_SHAPE`'s 64-character bound
+ * describes.
+ * 2. **Decode.** On a wire that renames tools, the model wrote the encoded
+ * name; the client's own name may legitimately be longer than the wire
+ * allows. Decoding before step 1 would fail a real 65-character MCP name on
+ * a shape rule that was never about it.
+ * 3. **Allowlist.** Reject a well-shaped name the client never advertised —
+ * this is how a hallucinated tool is caught. The allowlist is the request's
+ * own tool list, so it is exact rather than a hardcoded roster.
*/
function keepOnlyRealTools(
extracted: ExtractedToolCall[],
- knownToolNames?: string[]
+ knownToolNames?: string[],
+ decodeToolName?: (name: string) => string
): ExtractedToolCall[] {
const kept: ExtractedToolCall[] = [];
for (const call of extracted) {
@@ -96,16 +105,18 @@ function keepOnlyRealTools(
);
continue;
}
+ const decoded = decodeToolName ? decodeToolName(call.name) : call.name;
+ const named = decoded === call.name ? call : { ...call, name: decoded };
if (!knownToolNames || knownToolNames.length === 0) {
- kept.push(call);
+ kept.push(named);
continue;
}
- const canonical = knownToolNames.find((t) => t.toLowerCase() === call.name.toLowerCase());
+ const canonical = knownToolNames.find((t) => t.toLowerCase() === named.name.toLowerCase());
if (!canonical) {
- log(`[ToolRecovery] Dropped extracted call for unadvertised tool: ${call.name}`);
+ log(`[ToolRecovery] Dropped extracted call for unadvertised tool: ${named.name}`);
continue;
}
- kept.push(canonical === call.name ? call : { ...call, name: canonical });
+ kept.push(canonical === named.name ? named : { ...named, name: canonical });
}
return kept;
}
@@ -226,18 +237,24 @@ function normalizeAgainstSchema(
*
* `toolSchemas`, when supplied, types the extracted values: the envelope format
* carries no types, so every value arrives as a string.
+ *
+ * `decodeToolName`, when supplied, turns the name the MODEL wrote back into the
+ * client's own. The model was given the encoded roster, so on a renaming wire
+ * every recovered call carries an encoded name that `knownToolNames` — built
+ * from the client's originals — would otherwise reject in silence.
*/
export function extractToolCallsFromText(
text: string,
knownToolNames?: string[],
- toolSchemas?: ToolSchema[]
+ toolSchemas?: ToolSchema[],
+ decodeToolName?: (name: string) => string
): ExtractedToolCall[] {
// Tried FIRST, and short-circuits: a response that is nothing but function
// tags is unambiguous, and reading it as a delimited envelope beats six
// regexes scanning for fragments of one.
const envelope = parseFunctionTagEnvelope(text);
if (envelope) {
- return keepOnlyRealTools(envelope, knownToolNames).map((call) =>
+ return keepOnlyRealTools(envelope, knownToolNames, decodeToolName).map((call) =>
normalizeAgainstSchema(call, toolSchemas)
);
}
@@ -460,7 +477,7 @@ export function extractToolCallsFromText(
}
}
- return keepOnlyRealTools(extracted, knownToolNames);
+ return keepOnlyRealTools(extracted, knownToolNames, decodeToolName);
}
/**