Skip to content

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

fix(adapters): map tool_choice any to required, from one shared mapper (item 10)

Jack Rudenkod170a3ff3b80
diff --git a/packages/cli/src/adapters/base-api-format.ts b/packages/cli/src/adapters/base-api-format.ts
index abc6f5b8..b6b31ef8 100644
--- a/packages/cli/src/adapters/base-api-format.ts
+++ b/packages/cli/src/adapters/base-api-format.ts
@@ -41,7 +41,10 @@ export function matchesModelFamily(modelId: string, family: string): boolean {
return lower.startsWith(fam) || lower.includes(`/${fam}`);
}
import { convertMessagesToOpenAI } from "../handlers/shared/format/openai-messages.js";
-import { convertToolsToOpenAI } from "../handlers/shared/format/openai-tools.js";
+import {
+ convertToolsToOpenAI,
+ mapToolChoiceToOpenAI,
+} from "../handlers/shared/format/openai-tools.js";
export interface ToolCall {
id: string;
@@ -665,6 +668,17 @@ export abstract class BaseAPIFormat implements APIFormat, ModelDialect {
};
if (tools.length > 0) {
payload.tools = tools;
+
+ // This builder had no tool_choice handling at ALL, which is easy to miss
+ // because it holds no copy of the mapping to grep for. It is not dead:
+ // `ComposedHandler.getAdapter()` is `explicitAdapter || resolvedDialect`,
+ // so every provider profile that supplies no explicit Layer-1 format
+ // builds its payload here — and dropped the caller's tool_choice
+ // entirely, not just `any`.
+ const toolChoice = mapToolChoiceToOpenAI(claudeRequest.tool_choice);
+ if (toolChoice !== undefined) {
+ payload.tool_choice = toolChoice;
+ }
}
if (claudeRequest.max_tokens) {
payload.max_tokens = claudeRequest.max_tokens;
diff --git a/packages/cli/src/adapters/codex-api-format.ts b/packages/cli/src/adapters/codex-api-format.ts
index 86f6436d..9cf96d67 100644
--- a/packages/cli/src/adapters/codex-api-format.ts
+++ b/packages/cli/src/adapters/codex-api-format.ts
@@ -11,6 +11,7 @@
* This format handles Codex models only. All other OpenAI models use OpenAIAPIFormat.
*/
+import { mapToolChoiceToResponsesAPI } from "../handlers/shared/format/openai-tools.js";
import { log } from "../logger.js";
import type { StreamFormat } from "../providers/transport/types.js";
import {
@@ -129,6 +130,14 @@ export class CodexAPIFormat extends BaseAPIFormat {
}
return tool;
});
+
+ // The Responses API spells tool_choice as Chat Completions does, except
+ // that the function form is flat. Gated on there being tools, for the
+ // same reason Gemini is.
+ const toolChoice = mapToolChoiceToResponsesAPI(claudeRequest.tool_choice);
+ if (toolChoice !== undefined) {
+ payload.tool_choice = toolChoice;
+ }
}
return payload;
diff --git a/packages/cli/src/adapters/gemini-api-format.ts b/packages/cli/src/adapters/gemini-api-format.ts
index a9c1c504..534d3e18 100644
--- a/packages/cli/src/adapters/gemini-api-format.ts
+++ b/packages/cli/src/adapters/gemini-api-format.ts
@@ -13,6 +13,7 @@
* Used with GeminiProviderTransport (direct API) and AntigravityProviderTransport (OAuth).
*/
+import { mapToolChoiceToGemini } from "../handlers/shared/format/openai-tools.js";
import { convertToolsToGemini } from "../handlers/shared/gemini-schema.js";
import { filterIdentity } from "../handlers/shared/openai-compat.js";
import { log } from "../logger.js";
@@ -213,6 +214,18 @@ export class GeminiAPIFormat extends BaseAPIFormat {
// Tools — convertTools returns Gemini format [{functionDeclarations: [...]}] or []
if (tools && tools.length > 0) {
payload.tools = tools;
+
+ // `toolConfig` is Gemini's `tool_choice`, and this format had none at all
+ // — every forced-tool turn ran as if the caller had said `auto`. Gated on
+ // there being tools: a functionCallingConfig with nothing to call is a
+ // request-level 400.
+ const toolConfig = mapToolChoiceToGemini(claudeRequest.tool_choice);
+ if (toolConfig) {
+ payload.toolConfig = toolConfig;
+ log(
+ `[GeminiAPIFormat] toolConfig.mode -> ${toolConfig.functionCallingConfig.mode} for ${this.modelId}`
+ );
+ }
}
// Thinking/reasoning configuration.
diff --git a/packages/cli/src/adapters/litellm-api-format.ts b/packages/cli/src/adapters/litellm-api-format.ts
index 55685942..46a10562 100644
--- a/packages/cli/src/adapters/litellm-api-format.ts
+++ b/packages/cli/src/adapters/litellm-api-format.ts
@@ -6,6 +6,7 @@
* - OpenAI-compatible payload with stream_options and tool_choice
*/
+import { mapToolChoiceToOpenAI } from "../handlers/shared/format/openai-tools.js";
import { log } from "../logger.js";
import { DefaultAPIFormat } from "./base-api-format.js";
@@ -109,14 +110,9 @@ export class LiteLLMAPIFormat extends DefaultAPIFormat {
payload.tools = tools;
}
- // Handle tool choice
- if (claudeRequest.tool_choice) {
- const { type, name } = claudeRequest.tool_choice;
- if (type === "tool" && name) {
- payload.tool_choice = { type: "function", function: { name } };
- } else if (type === "auto" || type === "none") {
- payload.tool_choice = type;
- }
+ const toolChoice = mapToolChoiceToOpenAI(claudeRequest.tool_choice);
+ if (toolChoice !== undefined) {
+ payload.tool_choice = toolChoice;
}
this.applyOpenAISamplingParams(payload, claudeRequest);
diff --git a/packages/cli/src/adapters/local-adapter.ts b/packages/cli/src/adapters/local-adapter.ts
index ab6d2cef..621e794f 100644
--- a/packages/cli/src/adapters/local-adapter.ts
+++ b/packages/cli/src/adapters/local-adapter.ts
@@ -11,6 +11,7 @@
* - MLX simple format for message conversion
*/
+import { mapToolChoiceToOpenAI } from "../handlers/shared/format/openai-tools.js";
import { log } from "../logger.js";
import { type AdapterResult, BaseAPIFormat } from "./base-api-format.js";
import { resolveModelDialect } from "./dialect-manager.js";
@@ -117,13 +118,12 @@ export class LocalModelAdapter extends BaseAPIFormat {
stream_options: { include_usage: true },
};
- // Tool choice mapping from Claude format
- if (claudeRequest.tool_choice && tools.length > 0) {
- const { type, name } = claudeRequest.tool_choice;
- if (type === "tool" && name) {
- payload.tool_choice = { type: "function", function: { name } };
- } else if (type === "auto" || type === "none") {
- payload.tool_choice = type;
+ // The tools.length guard is this adapter's own: a local relay handed a
+ // tool_choice with no tools to choose from rejects the whole request.
+ if (tools.length > 0) {
+ const toolChoice = mapToolChoiceToOpenAI(claudeRequest.tool_choice);
+ if (toolChoice !== undefined) {
+ payload.tool_choice = toolChoice;
}
}
diff --git a/packages/cli/src/adapters/openai-api-format.ts b/packages/cli/src/adapters/openai-api-format.ts
index f66437cc..6070905c 100644
--- a/packages/cli/src/adapters/openai-api-format.ts
+++ b/packages/cli/src/adapters/openai-api-format.ts
@@ -11,6 +11,7 @@
* Also serves as Layer 2 ModelDialect for OpenAI-native models (o1/o3 reasoning params).
*/
+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, type EffortLevel } from "./base-api-format.js";
@@ -329,13 +330,9 @@ export class OpenAIAPIFormat extends BaseAPIFormat {
payload.tools = tools;
}
- if (claudeRequest.tool_choice) {
- const { type, name } = claudeRequest.tool_choice;
- if (type === "tool" && name) {
- payload.tool_choice = { type: "function", function: { name } };
- } else if (type === "auto" || type === "none") {
- payload.tool_choice = type;
- }
+ const toolChoice = mapToolChoiceToOpenAI(claudeRequest.tool_choice);
+ if (toolChoice !== undefined) {
+ payload.tool_choice = toolChoice;
}
// Map Claude Code's effort (output_config.effort, or legacy
diff --git a/packages/cli/src/adapters/openrouter-api-format.ts b/packages/cli/src/adapters/openrouter-api-format.ts
index a05ee647..79fa49e2 100644
--- a/packages/cli/src/adapters/openrouter-api-format.ts
+++ b/packages/cli/src/adapters/openrouter-api-format.ts
@@ -10,7 +10,10 @@
* - Tool choice mapping from Claude format
*/
-import { convertToolsToOpenAI } from "../handlers/shared/format/openai-tools.js";
+import {
+ convertToolsToOpenAI,
+ mapToolChoiceToOpenAI,
+} from "../handlers/shared/format/openai-tools.js";
import { type AdapterResult, BaseAPIFormat } from "./base-api-format.js";
import { resolveModelDialect } from "./dialect-manager.js";
@@ -129,14 +132,9 @@ export class OpenRouterAPIFormat extends BaseAPIFormat {
payload.thinking = claudeRequest.thinking;
}
- // Tool choice mapping from Claude format
- if (claudeRequest.tool_choice) {
- const { type, name } = claudeRequest.tool_choice;
- if (type === "tool" && name) {
- payload.tool_choice = { type: "function", function: { name } };
- } else if (type === "auto" || type === "none") {
- payload.tool_choice = type;
- }
+ const toolChoice = mapToolChoiceToOpenAI(claudeRequest.tool_choice);
+ if (toolChoice !== undefined) {
+ payload.tool_choice = toolChoice;
}
this.applyOpenAISamplingParams(payload, claudeRequest);
diff --git a/packages/cli/src/adapters/tool-choice-mapping.test.ts b/packages/cli/src/adapters/tool-choice-mapping.test.ts
new file mode 100644
index 00000000..cbbc20a6
--- /dev/null
+++ b/packages/cli/src/adapters/tool-choice-mapping.test.ts
@@ -0,0 +1,160 @@
+/**
+ * Item 10 — `tool_choice: {type:"any"}` reaches the wire, from ONE mapper.
+ *
+ * Four adapters carried a verbatim copy of a three-branch mapping that handled
+ * `tool`, `auto` and `none` and silently dropped `any`. This pins both halves:
+ * that `any` now maps (to `required`, `ANY`, or the Responses spelling), and
+ * that there is one definition rather than four.
+ *
+ * ## Provenance of the inputs
+ *
+ * REQUEST-side, so no capture in this tree can reach it —
+ * `test-fixtures/sse-responses/` holds response streams, not inbound bodies.
+ * The inputs are constructed Anthropic request bodies written inline, asserting
+ * only this tree's own conversion contract. No `.sse` fixture was invented.
+ */
+
+import { expect, test } from "bun:test";
+import {
+ mapToolChoiceToGemini,
+ mapToolChoiceToOpenAI,
+ mapToolChoiceToResponsesAPI,
+} from "../handlers/shared/format/openai-tools.js";
+import { DefaultAPIFormat } from "./base-api-format.js";
+import { CodexAPIFormat } from "./codex-api-format.js";
+import { GeminiAPIFormat } from "./gemini-api-format.js";
+import { LiteLLMAPIFormat } from "./litellm-api-format.js";
+import { LocalModelAdapter } from "./local-adapter.js";
+import { OpenAIAPIFormat } from "./openai-api-format.js";
+import { OpenRouterAPIFormat } from "./openrouter-api-format.js";
+
+const MESSAGES = [{ role: "user", content: "hi" }];
+const TOOLS = [
+ {
+ type: "function",
+ function: { name: "Read", description: "d", parameters: { type: "object" } },
+ },
+];
+
+/** Every OpenAI Chat-Completions-shaped builder. */
+const CHAT_BUILDERS: [string, () => { buildPayload: (r: any, m: any[], t: any[]) => any }][] = [
+ ["BaseAPIFormat", () => new DefaultAPIFormat("some-model")],
+ ["OpenAIAPIFormat", () => new OpenAIAPIFormat("gpt-4o")],
+ ["LiteLLMAPIFormat", () => new LiteLLMAPIFormat("gpt-4o", "http://localhost:4000")],
+ ["OpenRouterAPIFormat", () => new OpenRouterAPIFormat("openai/gpt-4o")],
+ ["LocalModelAdapter", () => new LocalModelAdapter("qwen2.5-coder", "ollama")],
+];
+
+test('every OpenAI-shaped builder maps tool_choice "any" to "required"', () => {
+ for (const [name, make] of CHAT_BUILDERS) {
+ const payload = make().buildPayload(
+ { max_tokens: 100, tool_choice: { type: "any" } },
+ MESSAGES,
+ TOOLS
+ );
+ expect(`${name}: ${payload.tool_choice}`).toBe(`${name}: required`);
+ }
+});
+
+test("the other three Claude tool_choice types are unchanged", () => {
+ for (const [name, make] of CHAT_BUILDERS) {
+ const build = (tool_choice: any) =>
+ make().buildPayload({ max_tokens: 100, tool_choice }, MESSAGES, TOOLS).tool_choice;
+
+ expect(`${name}: ${build({ type: "auto" })}`).toBe(`${name}: auto`);
+ expect(`${name}: ${build({ type: "none" })}`).toBe(`${name}: none`);
+ expect(build({ type: "tool", name: "Read" })).toEqual({
+ type: "function",
+ function: { name: "Read" },
+ });
+ // A `tool` choice naming no tool, and an unknown type, send nothing.
+ expect(`${name}: ${build({ type: "tool" })}`).toBe(`${name}: undefined`);
+ expect(`${name}: ${build({ type: "frobnicate" })}`).toBe(`${name}: undefined`);
+ expect(`${name}: ${build(undefined)}`).toBe(`${name}: undefined`);
+ }
+});
+
+test("Gemini gets a toolConfig, which it had no handling for at all", () => {
+ const gemini = new GeminiAPIFormat("gemini-3-pro");
+ const geminiTools = [
+ { functionDeclarations: [{ name: "Read", parameters: { type: "object" } }] },
+ ];
+ const build = (tool_choice: any) =>
+ gemini.buildPayload({ max_tokens: 100, tool_choice }, MESSAGES, geminiTools).toolConfig;
+
+ expect(build({ type: "any" })).toEqual({ functionCallingConfig: { mode: "ANY" } });
+ expect(build({ type: "auto" })).toEqual({ functionCallingConfig: { mode: "AUTO" } });
+ expect(build({ type: "none" })).toEqual({ functionCallingConfig: { mode: "NONE" } });
+ expect(build({ type: "tool", name: "Read" })).toEqual({
+ functionCallingConfig: { mode: "ANY", allowedFunctionNames: ["Read"] },
+ });
+ expect(build(undefined)).toBeUndefined();
+
+ // No tools ⇒ no toolConfig: a functionCallingConfig with nothing to call is a
+ // request-level 400.
+ expect(
+ gemini.buildPayload({ max_tokens: 100, tool_choice: { type: "any" } }, MESSAGES, []).toolConfig
+ ).toBeUndefined();
+});
+
+test("Codex gets the Responses spelling, where the function form is flat", () => {
+ const codex = new CodexAPIFormat("gpt-5.1-codex");
+ const build = (tool_choice: any) =>
+ codex.buildPayload({ max_tokens: 100, tool_choice }, MESSAGES, TOOLS).tool_choice;
+
+ expect(build({ type: "any" })).toBe("required");
+ expect(build({ type: "tool", name: "Read" })).toEqual({ type: "function", name: "Read" });
+ expect(build(undefined)).toBeUndefined();
+ expect(
+ codex.buildPayload({ max_tokens: 100, tool_choice: { type: "any" } }, MESSAGES, []).tool_choice
+ ).toBeUndefined();
+});
+
+test("the mapper takes an encodeName, so tool_choice can name the wire's own name", () => {
+ const upper = (n: string) => n.toUpperCase();
+ expect(mapToolChoiceToOpenAI({ type: "tool", name: "Read" }, upper)).toEqual({
+ type: "function",
+ function: { name: "READ" },
+ });
+ expect(mapToolChoiceToResponsesAPI({ type: "tool", name: "Read" }, upper)).toEqual({
+ type: "function",
+ name: "READ",
+ });
+ expect(mapToolChoiceToGemini({ type: "tool", name: "Read" }, upper)).toEqual({
+ functionCallingConfig: { mode: "ANY", allowedFunctionNames: ["READ"] },
+ });
+ // encodeName applies to the NAME only — the string forms have no name to encode.
+ expect(mapToolChoiceToOpenAI({ type: "any" }, upper)).toBe("required");
+});
+
+test("there is ONE tool_choice mapping, not one per adapter", async () => {
+ // A structural guard: the four-branch literal that used to live in each
+ // builder must not come back. Anything assigning `payload.tool_choice` from a
+ // destructured `{ type, name }` is a second definition of this mapping.
+ const { readdirSync, readFileSync } = await import("node:fs");
+ const dir = new URL(".", import.meta.url).pathname;
+ const offenders: string[] = [];
+ const mapperUsers: string[] = [];
+
+ for (const file of readdirSync(dir)) {
+ if (!file.endsWith(".ts") || file.endsWith(".test.ts")) continue;
+ // The Anthropic wire forwards tool_choice verbatim — no mapping to share.
+ if (file === "anthropic-api-format.ts") continue;
+ const src = readFileSync(dir + file, "utf8");
+ if (/const \{ type, name \} = \w+\.tool_choice/.test(src)) offenders.push(file);
+ if (/mapToolChoiceTo(OpenAI|Gemini|ResponsesAPI)\(/.test(src)) mapperUsers.push(file);
+ }
+
+ expect(offenders).toEqual([]);
+ // Not vacuous: the walk really did read the adapters, and all six builders
+ // reach the shared mapper.
+ expect(mapperUsers.sort()).toEqual([
+ "base-api-format.ts",
+ "codex-api-format.ts",
+ "gemini-api-format.ts",
+ "litellm-api-format.ts",
+ "local-adapter.ts",
+ "openai-api-format.ts",
+ "openrouter-api-format.ts",
+ ]);
+});
diff --git a/packages/cli/src/handlers/shared/format/openai-tools.ts b/packages/cli/src/handlers/shared/format/openai-tools.ts
index 25b71b96..ed1aea68 100644
--- a/packages/cli/src/handlers/shared/format/openai-tools.ts
+++ b/packages/cli/src/handlers/shared/format/openai-tools.ts
@@ -278,3 +278,114 @@ function summarizeToolParameters(schema: any): any {
return summarized;
}
+
+// ─── tool_choice ────────────────────────────────────────────────────────────
+
+/**
+ * Claude's `tool_choice`, as Claude Code sends it.
+ *
+ * `any` is the one that used to fall through every OpenAI-shaped builder in
+ * this tree: four verbatim copies of a three-branch mapping each handled
+ * `tool`, `auto` and `none`, and silently omitted `any`. Omitting it inverts the
+ * caller's instruction — "you MUST call a tool" became "call one if you feel
+ * like it" — and there is no error anywhere, only a model that answers in prose
+ * when the harness was waiting for a call.
+ */
+export interface ClaudeToolChoice {
+ type?: string;
+ name?: string;
+}
+
+/** An OpenAI Chat Completions `tool_choice` value. */
+export type OpenAIToolChoice = string | { type: "function"; function: { name: string } };
+
+/** An OpenAI Responses API `tool_choice` value (the function form is flat). */
+export type ResponsesToolChoice = string | { type: "function"; name: string };
+
+/**
+ * Map Claude's `tool_choice` onto the OpenAI Chat Completions spelling.
+ *
+ * THE single definition for every OpenAI-shaped adapter — openai, openrouter,
+ * litellm and local each carried their own copy, and `adapters.md:476-482`
+ * records that class of duplication for these exact files. A fifth copy is how
+ * the next `any` gets forgotten.
+ *
+ * Returns `undefined` for "send no tool_choice at all", which is the right
+ * answer for an absent choice, an unrecognised type, and a `tool` choice that
+ * names no tool.
+ *
+ * @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.
+ */
+export function mapToolChoiceToOpenAI(
+ choice: ClaudeToolChoice | null | undefined,
+ encodeName?: (name: string) => string
+): OpenAIToolChoice | undefined {
+ if (!choice) return undefined;
+ const { type, name } = choice;
+
+ if (type === "tool" && name) {
+ return { type: "function", function: { name: encodeName ? encodeName(name) : name } };
+ }
+ // Claude's "any" means "you must call one of the tools"; OpenAI spells that
+ // "required".
+ if (type === "any") return "required";
+ if (type === "auto" || type === "none") return type;
+ return undefined;
+}
+
+/**
+ * The same mapping in the Responses API spelling, where the function form is
+ * `{type:"function", name}` rather than nesting it under `function`.
+ */
+export function mapToolChoiceToResponsesAPI(
+ choice: ClaudeToolChoice | null | undefined,
+ encodeName?: (name: string) => string
+): ResponsesToolChoice | undefined {
+ const mapped = mapToolChoiceToOpenAI(choice, encodeName);
+ if (mapped === undefined || typeof mapped === "string") return mapped;
+ return { type: "function", name: mapped.function.name };
+}
+
+/** Gemini's `toolConfig` — the same instruction in the protobuf spelling. */
+export interface GeminiToolConfig {
+ functionCallingConfig: {
+ mode: "AUTO" | "ANY" | "NONE";
+ allowedFunctionNames?: string[];
+ };
+}
+
+/**
+ * Map Claude's `tool_choice` onto Gemini's `toolConfig`.
+ *
+ * Gemini had NO tool_choice handling at all: `buildPayload` wrote `contents`,
+ * `generationConfig`, `systemInstruction`, `tools` and `thinkingConfig` and
+ * nothing else, so every forced-tool turn on `g@`/`go@`/`ag@` ran as if the
+ * caller had said `auto`.
+ *
+ * `mode` is a protobuf ENUM: `AUTO`, `ANY` and `NONE` are the spellings the
+ * server accepts, and a misspelling is a 400 on the first tool-using request of
+ * a session, not a degraded response. `tool` maps to `ANY` restricted by
+ * `allowedFunctionNames` — Gemini has no single-function mode.
+ */
+export function mapToolChoiceToGemini(
+ choice: ClaudeToolChoice | null | undefined,
+ encodeName?: (name: string) => string
+): GeminiToolConfig | undefined {
+ if (!choice) return undefined;
+ const { type, name } = choice;
+
+ if (type === "tool" && name) {
+ return {
+ functionCallingConfig: {
+ mode: "ANY",
+ allowedFunctionNames: [encodeName ? encodeName(name) : name],
+ },
+ };
+ }
+ if (type === "any") return { functionCallingConfig: { mode: "ANY" } };
+ if (type === "auto") return { functionCallingConfig: { mode: "AUTO" } };
+ if (type === "none") return { functionCallingConfig: { mode: "NONE" } };
+ return undefined;
+}