@gajae-code/ai 0.4.5 → 0.5.1

package/src/providers/composer-discipline.ts

@@ -0,0 +1,38 @@
+/**
+ * Anchor/edit discipline for composer-harness models (xai grok-composer-*,
+ * cursor composer-*).
+ *
+ * Composer models are trained on a proprietary coding-agent harness
+ * (Cursor / Grok Build) and carry habits that break this agent's hashline
+ * edit workflow when driven through a generic provider. Observed in live
+ * sessions with grok-composer-2.5-fast:
+ *
+ *  - they print files with shell commands (`sed -n`, `cat`, `grep -n`) or
+ *    python heredocs whose output carries NO line anchors, then FABRICATE the
+ *    2-char anchor hash the edit tool requires (e.g. guessed "617hp" where
+ *    the file had "617ca" → "Edit rejected: N anchors do not match");
+ *  - they mutate files out-of-band via python heredocs (pathlib write_text /
+ *    str.replace), which invalidates every previously seen anchor and defeats
+ *    the read-cache snapshot that powers stale-anchor recovery;
+ *  - they arithmetically renumber anchors after their own edits instead of
+ *    copying them from the latest tool output;
+ *  - they leak reasoning prose into heredoc bodies, producing shell/python
+ *    syntax errors.
+ *
+ * This prompt is the per-request countermeasure, pinned ahead of the host
+ * system prompt on both the openai-completions path and the cursor RPC path.
+ */
+
+/** Matches composer-harness model ids on any provider (xai grok-composer-*, cursor composer-*). */
+export function isComposerHarnessModel(modelId: string): boolean {
+	return modelId.toLowerCase().includes("composer");
+}
+
+export const COMPOSER_EDIT_DISCIPLINE_PROMPT = `File-editing discipline for this harness (this OVERRIDES contrary habits from your training):
+
+- Read file contents ONLY with the provided read/search tools. NEVER print files through shell commands (sed, cat, awk, head, grep) or scripts — that output carries no line anchors, and the edit tool accepts ONLY anchors.
+- Modify files ONLY with the provided edit/write tools. NEVER mutate files through shell redirection, sed -i, or inline python scripts — out-of-band writes invalidate every known anchor and break edit recovery.
+- A line anchor (e.g. "42sr") is a line number plus a 2-char content hash. You CANNOT compute the hash yourself: copy anchors verbatim from the MOST RECENT read/search/edit output of that exact file. NEVER guess, renumber, or arithmetically shift an anchor.
+- After ANY edit to a file (including your own), anchors you saw earlier are stale. Re-read the edited region, or copy the fresh anchors printed in the edit result, before issuing the next edit.
+- If an edit is rejected with "anchors do not match", the rejection message prints the current lines WITH fresh anchors. Retry using exactly those printed anchors.
+- A shell command string must contain only the command itself. NEVER interleave reasoning or commentary into command strings or heredocs.`;

package/src/providers/cursor.ts

@@ -30,6 +30,7 @@ import { AssistantMessageEventStream } from "../utils/event-stream";
 import { parseStreamingJson } from "../utils/json-parse";
 import { formatErrorMessageWithRetryAfter } from "../utils/retry-after";
 import { toolWireSchema } from "../utils/schema/wire";
+import { COMPOSER_EDIT_DISCIPLINE_PROMPT, isComposerHarnessModel } from "./composer-discipline";
 import type { McpToolDefinition } from "./cursor/gen/agent_pb";
 import {
 	AgentClientMessageSchema,
@@ -2284,12 +2285,18 @@ function findLastUserMessageIndex(messages: Message[]): number {
  * When no system prompts are provided, returns a single default greeting so we never emit
  * an empty `rootPromptMessagesJson` head.
  */
-export function buildCursorSystemPromptJsons(systemPrompt: readonly string[] | undefined): string[] {
+export function buildCursorSystemPromptJsons(systemPrompt: readonly string[] | undefined, modelId?: string): string[] {
 	const systemPrompts = normalizeSystemPrompts(systemPrompt);
 	if (systemPrompts.length === 0) {
 		return [JSON.stringify({ role: "system", content: "You are a helpful assistant." })];
 	}
-	return systemPrompts.map(content => JSON.stringify({ role: "system", content }));
+	const jsons = systemPrompts.map(content => JSON.stringify({ role: "system", content }));
+	// Composer-harness models need anchor/edit discipline pinned ahead of the
+	// host prompt (see composer-discipline.ts for the observed failure modes).
+	if (modelId !== undefined && isComposerHarnessModel(modelId)) {
+		jsons.unshift(JSON.stringify({ role: "system", content: COMPOSER_EDIT_DISCIPLINE_PROMPT }));
+	}
+	return jsons;
 }
 
 function buildRootPromptMessagesJson(
@@ -2501,7 +2508,7 @@ function buildGrpcRequest(
 } {
 	const blobStore = state.blobStore;
 
-	const systemPromptIds = buildCursorSystemPromptJsons(context.systemPrompt).map(json =>
+	const systemPromptIds = buildCursorSystemPromptJsons(context.systemPrompt, model.id).map(json =>
 		storeCursorBlob(blobStore, new TextEncoder().encode(json)),
 	);
 

package/src/providers/google-gemini-cli.ts

@@ -25,6 +25,11 @@ import { resolveRetryBudget } from "../utils/retry-budget";
 // Refresh is the sole responsibility of AuthStorage (broker-aware, single-flighted);
 // the stream provider trusts the access token threaded through `options.apiKey`.
 import { normalizeSchemaForCCA } from "../utils/schema";
+import {
+	isForcedToolChoiceUnsupportedError,
+	markToolChoiceIncapability,
+	resolveToolChoice,
+} from "../utils/tool-choice-capability";
 import { ANTIGRAVITY_SYSTEM_INSTRUCTION, getAntigravityUserAgent, getGeminiCliHeaders } from "./google-gemini-headers";
 import type { Content, FunctionCallingConfigMode, ThinkingConfig } from "./google-shared";
 import {
@@ -48,7 +53,7 @@ import {
 export type { GoogleThinkingLevel };
 
 export interface GoogleGeminiCliOptions extends StreamOptions {
-	toolChoice?: "auto" | "none" | "any";
+	toolChoice?: "auto" | "none" | "any" | "required";
 	/**
 	 * Thinking/reasoning configuration.
 	 * - Gemini 2.x models: use `budgetTokens` to set the thinking budget
@@ -324,7 +329,7 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 				...(needsClaudeThinkingBetaHeader(model) ? { "anthropic-beta": CLAUDE_THINKING_BETA_HEADER } : {}),
 				...(options?.headers ?? {}),
 			};
-			const requestBodyJson = JSON.stringify(requestBody);
+			let requestBodyJson = JSON.stringify(requestBody);
 			rawRequestDump = {
 				provider: model.provider,
 				api: output.api,
@@ -334,7 +339,13 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 				headers: requestHeaders,
 			};
 
-			const response = await fetchWithRetry(
+			const sentForcedToolChoice =
+				(requestBody.request.toolConfig?.functionCallingConfig?.mode === "ANY" ||
+					requestBody.request.toolConfig?.functionCallingConfig?.mode === "VALIDATED") &&
+				options?.toolChoice !== undefined &&
+				options.toolChoice !== "auto" &&
+				options.toolChoice !== "none";
+			let response = await fetchWithRetry(
 				attempt => `${endpoints[Math.min(attempt, endpoints.length - 1)]}/v1internal:streamGenerateContent?alt=sse`,
 				{
 					method: "POST",
@@ -347,6 +358,49 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 					fetch: options?.fetch,
 				},
 			);
+			if (!response.ok && sentForcedToolChoice) {
+				const errorText = await response.text();
+				const error = withHttpStatus(
+					new Error(`Cloud Code Assist API error (${response.status}): ${extractErrorMessage(errorText)}`),
+					response.status,
+				);
+				if (firstTokenTime === undefined && isForcedToolChoiceUnsupportedError(error, true)) {
+					const beforeMark = resolveToolChoice(model, options?.toolChoice);
+					markToolChoiceIncapability(model, "auto", error.message);
+					stream.push({
+						type: "toolChoiceIncapability",
+						api: model.api,
+						provider: model.provider,
+						model: model.id,
+						requestedLevel: beforeMark.requestedLevel,
+						resolvedLevel: "auto",
+						reason: error.message,
+						registryKey: beforeMark.registryKey,
+					});
+					requestBody = {
+						...requestBody,
+						request: { ...requestBody.request, toolConfig: undefined },
+					};
+					requestBodyJson = JSON.stringify(requestBody);
+					rawRequestDump = { ...rawRequestDump, body: requestBody };
+					response = await fetchWithRetry(
+						attempt =>
+							`${endpoints[Math.min(attempt, endpoints.length - 1)]}/v1internal:streamGenerateContent?alt=sse`,
+						{
+							method: "POST",
+							headers: requestHeaders,
+							body: requestBodyJson,
+							signal: options?.signal,
+							maxAttempts: 1,
+							defaultDelayMs: attempt => BASE_DELAY_MS * 2 ** attempt,
+							maxDelayMs: options?.maxRetryDelayMs ?? RATE_LIMIT_BUDGET_MS,
+							fetch: options?.fetch,
+						},
+					);
+				} else {
+					throw error;
+				}
+			}
 			if (!response.ok) {
 				const errorText = await response.text();
 				throw withHttpStatus(
@@ -743,13 +797,15 @@ export function buildRequest(
 		request.generationConfig = generationConfig;
 	}
 
+	const resolvedToolChoice = resolveToolChoice(model, options.toolChoice);
 	if (context.tools && context.tools.length > 0) {
 		const convertedTools = convertTools(context.tools, model);
 		request.tools = isAntigravity ? normalizeAntigravityTools(convertedTools) : convertedTools;
-		if (options.toolChoice) {
+		const resolved = resolvedToolChoice;
+		if (resolved.resolvedChoice) {
 			request.toolConfig = {
 				functionCallingConfig: {
-					mode: mapToolChoice(options.toolChoice),
+					mode: mapToolChoice(resolved.resolvedChoice as string),
 				},
 			};
 		}
@@ -763,11 +819,14 @@ export function buildRequest(
 	}
 
 	if (isAntigravity && isClaudeModel(model.id)) {
-		request.toolConfig = {
-			functionCallingConfig: {
-				mode: "VALIDATED" as FunctionCallingConfigMode,
-			},
-		};
+		const resolvedLevel = resolvedToolChoice.resolvedLevel;
+		if (resolvedLevel === "named" || resolvedLevel === "required") {
+			request.toolConfig = {
+				functionCallingConfig: {
+					mode: "VALIDATED" as FunctionCallingConfigMode,
+				},
+			};
+		}
 	}
 
 	if (isAntigravity && shouldInjectAntigravitySystemInstruction(model.id)) {

package/src/providers/google-shared.ts

@@ -22,6 +22,11 @@ import { normalizeSystemPrompts } from "../utils";
 import { AssistantMessageEventStream } from "../utils/event-stream";
 import { finalizeErrorMessage, type RawHttpRequestDump, withHttpStatus } from "../utils/http-inspector";
 import { normalizeSchemaForCCA, normalizeSchemaForGoogle, toolWireSchema } from "../utils/schema";
+import {
+	isForcedToolChoiceUnsupportedError,
+	markToolChoiceIncapability,
+	resolveToolChoice,
+} from "../utils/tool-choice-capability";
 import type {
 	Content,
 	FinishReason,
@@ -59,7 +64,7 @@ export type GoogleThinkingLevel = "THINKING_LEVEL_UNSPECIFIED" | "MINIMAL" | "LO
  * `google-gemini-cli` uses a different transport and request shape — do not extend this for it.
  */
 export interface GoogleSharedStreamOptions extends StreamOptions {
-	toolChoice?: "auto" | "none" | "any";
+	toolChoice?: "auto" | "none" | "any" | "required";
 	thinking?: {
 		enabled: boolean;
 		budgetTokens?: number;
@@ -366,6 +371,7 @@ export function mapToolChoice(choice: string): FunctionCallingConfigMode {
 		case "none":
 			return "NONE";
 		case "any":
+		case "required":
 			return "ANY";
 		default:
 			return "AUTO";
@@ -689,14 +695,15 @@ export function buildGoogleGenerateContentParams<T extends "google-generative-ai
 		...(context.tools && context.tools.length > 0 && { tools: convertTools(context.tools, model) }),
 	};
 
-	if (context.tools && context.tools.length > 0 && options.toolChoice) {
-		config.toolConfig = {
-			functionCallingConfig: {
-				mode: mapToolChoice(options.toolChoice),
-			},
-		};
-	} else {
-		config.toolConfig = undefined;
+	if (context.tools && context.tools.length > 0) {
+		const resolved = resolveToolChoice(model, options.toolChoice);
+		if (resolved.resolvedChoice) {
+			config.toolConfig = {
+				functionCallingConfig: {
+					mode: mapToolChoice(resolved.resolvedChoice as string),
+				},
+			};
+		}
 	}
 
 	if (options.thinking?.enabled && model.reasoning) {
@@ -789,14 +796,56 @@ export function streamGoogleGenAI<T extends "google-generative-ai" | "google-ver
 				headers: plan.headers,
 			};
 
-			const wireBody = paramsToWireBody(params);
+			let wireBody = paramsToWireBody(params);
+			const sentForcedToolChoice =
+				(params.config?.toolConfig?.functionCallingConfig?.mode === "ANY" ||
+					params.config?.toolConfig?.functionCallingConfig?.mode === "VALIDATED") &&
+				options?.toolChoice !== undefined &&
+				options.toolChoice !== "auto" &&
+				options.toolChoice !== "none";
 			const fetchImpl = plan.fetch ?? options?.fetch ?? (globalThis.fetch.bind(globalThis) as FetchImpl);
-			const response = await fetchImpl(plan.url, {
+			let response = await fetchImpl(plan.url, {
 				method: "POST",
 				headers: { ...plan.headers, "Content-Type": "application/json", Accept: "text/event-stream" },
 				body: JSON.stringify(wireBody),
 				signal: options?.signal,
 			});
+			if (!response.ok && sentForcedToolChoice) {
+				const errorText = await response.text().catch(() => "");
+				const error = withHttpStatus(
+					new Error(`Google API error (${response.status}): ${extractGoogleErrorMessage(errorText)}`),
+					response.status,
+				);
+				if (firstTokenTime === undefined && isForcedToolChoiceUnsupportedError(error, true)) {
+					const beforeMark = resolveToolChoice(model, options?.toolChoice);
+					markToolChoiceIncapability(model, "auto", error.message);
+					stream.push({
+						type: "toolChoiceIncapability",
+						api: model.api,
+						provider: model.provider,
+						model: model.id,
+						requestedLevel: beforeMark.requestedLevel,
+						resolvedLevel: "auto",
+						reason: error.message,
+						registryKey: beforeMark.registryKey,
+					});
+					const retryParams = {
+						...params,
+						config: params.config ? { ...params.config, toolConfig: undefined } : params.config,
+					};
+					params = retryParams;
+					rawRequestDump = { ...rawRequestDump, body: params };
+					wireBody = paramsToWireBody(params);
+					response = await fetchImpl(plan.url, {
+						method: "POST",
+						headers: { ...plan.headers, "Content-Type": "application/json", Accept: "text/event-stream" },
+						body: JSON.stringify(wireBody),
+						signal: options?.signal,
+					});
+				} else {
+					throw error;
+				}
+			}
 			if (!response.ok) {
 				const errorText = await response.text().catch(() => "");
 				throw withHttpStatus(
@@ -857,7 +906,7 @@ export function streamGoogleGenAI<T extends "google-generative-ai" | "google-ver
  * `abortSignal` is intentionally dropped — the SDK propagates it via `fetch.signal`,
  * which our caller already wires up through `options.signal`.
  */
-function paramsToWireBody(params: GenerateContentParameters): Record<string, unknown> {
+export function paramsToWireBody(params: GenerateContentParameters): Record<string, unknown> {
 	const body: Record<string, unknown> = { contents: params.contents };
 	const config = params.config;
 	if (!config) return body;

package/src/providers/ollama.ts

@@ -20,6 +20,11 @@ import { finalizeErrorMessage, type RawHttpRequestDump } from "../utils/http-ins
 import { parseStreamingJson } from "../utils/json-parse";
 import { resolveRetryBudget } from "../utils/retry-budget";
 import { toolWireSchema } from "../utils/schema/wire";
+import {
+	isForcedToolChoiceUnsupportedError,
+	markToolChoiceIncapability,
+	resolveToolChoice,
+} from "../utils/tool-choice-capability";
 import { transformMessages } from "./transform-messages";
 
 export interface OllamaChatOptions extends StreamOptions {
@@ -253,10 +258,22 @@ function convertTools(tools: Tool[] | undefined): OllamaFunctionTool[] | undefin
 	}));
 }
 
-function createChatBody(model: Model<"ollama-chat">, context: Context, options: OllamaChatOptions | undefined) {
+export function createChatBody(model: Model<"ollama-chat">, context: Context, options: OllamaChatOptions | undefined) {
 	const think = mapReasoning(options?.reasoning);
-	const toolChoice = mapToolChoice(options?.toolChoice);
-	const selectedTools = selectToolsForToolChoice(context.tools, options?.toolChoice);
+	const resolved = resolveToolChoice(model, options?.toolChoice);
+	const toolChoice = mapToolChoice(resolved.resolvedChoice);
+
+	// Ollama's wire protocol has no named forcing — a named request rides
+	// `tool_choice: "required"` with the tool list narrowed to the target
+	// (issue #1236). Narrow whenever the resolved choice still forces a tool.
+	const shouldNarrowToNamedTool =
+		resolved.requestedLevel === "named" &&
+		(resolved.resolvedLevel === "named" || resolved.resolvedLevel === "required") &&
+		resolved.targetToolName !== undefined;
+	const selectedTools =
+		shouldNarrowToNamedTool && resolved.targetToolName
+			? selectToolsForToolChoice(context.tools, { type: "tool", name: resolved.targetToolName })
+			: context.tools;
 	const tools = convertTools(selectedTools);
 	return {
 		model: model.id,
@@ -382,6 +399,7 @@ export const streamOllama: StreamFunction<"ollama-chat"> = (
 			}
 			const baseUrl = normalizeBaseUrl(model.baseUrl);
 			let body = createChatBody(model, context, options);
+			const sentForcedToolChoice = body.tool_choice === "required";
 			const replacementPayload = await options.onPayload?.(body, model);
 			if (replacementPayload !== undefined) {
 				body = replacementPayload as typeof body;
@@ -394,7 +412,7 @@ export const streamOllama: StreamFunction<"ollama-chat"> = (
 				url: `${baseUrl}/api/chat`,
 				body,
 			};
-			const response = await fetchWithRetry(`${baseUrl}/api/chat`, {
+			let response = await fetchWithRetry(`${baseUrl}/api/chat`, {
 				method: "POST",
 				headers: {
 					...model.headers,
@@ -408,6 +426,44 @@ export const streamOllama: StreamFunction<"ollama-chat"> = (
 				defaultDelayMs: OLLAMA_RETRY_DELAYS_MS,
 				fetch: options.fetch,
 			});
+			if (!response.ok && sentForcedToolChoice) {
+				const error = new Error(
+					`HTTP ${response.status} from ${baseUrl}/api/chat: ${await response.text().catch(() => "")}`,
+				);
+				(error as Error & { status?: number }).status = response.status;
+				if (firstTokenTime === undefined && isForcedToolChoiceUnsupportedError(error, true)) {
+					markToolChoiceIncapability(model, "auto", error.message);
+					stream.push({
+						type: "toolChoiceIncapability",
+						api: model.api,
+						provider: model.provider,
+						model: model.id,
+						requestedLevel: "required",
+						resolvedLevel: "auto",
+						reason: error.message,
+						registryKey: resolveToolChoice(model, options?.toolChoice).registryKey,
+					});
+					body = { ...body };
+					delete (body as { tool_choice?: unknown }).tool_choice;
+					rawRequestDump = { ...rawRequestDump, body };
+					response = await fetchWithRetry(`${baseUrl}/api/chat`, {
+						method: "POST",
+						headers: {
+							...model.headers,
+							...options.headers,
+							Authorization: `Bearer ${apiKey}`,
+							"Content-Type": "application/json",
+						},
+						body: JSON.stringify(body),
+						signal: options.signal,
+						maxAttempts: 1,
+						defaultDelayMs: OLLAMA_RETRY_DELAYS_MS,
+						fetch: options.fetch,
+					});
+				} else {
+					throw error;
+				}
+			}
 			if (!response.ok) {
 				throw new Error(`HTTP ${response.status} from ${baseUrl}/api/chat`);
 			}

package/src/providers/openai-codex-responses.ts

@@ -51,6 +51,11 @@ import { getOpenAIStreamIdleTimeoutMs, iterateWithIdleTimeout } from "../utils/i
 import { parseStreamingJson } from "../utils/json-parse";
 import { resolveRetryBudget } from "../utils/retry-budget";
 import { adaptSchemaForStrict, NO_STRICT, sanitizeSchemaForOpenAIResponses, toolWireSchema } from "../utils/schema";
+import {
+	isForcedToolChoiceUnsupportedError,
+	markToolChoiceIncapability,
+	resolveToolChoice,
+} from "../utils/tool-choice-capability";
 import { compactGrammarDefinition } from "./grammar";
 import { CODEX_BASE_URL, getCodexAccountId, OPENAI_HEADER_VALUES, OPENAI_HEADERS } from "./openai-codex/constants";
 import {
@@ -175,6 +180,47 @@ interface CodexRequestContext {
 	rawRequestDump: RawHttpRequestDump;
 }
 
+async function retryCodexInitialTransportWithoutToolChoice(
+	model: Model<"openai-codex-responses">,
+	options: OpenAICodexResponsesOptions | undefined,
+	requestSetup: CodexRequestSetup,
+	requestContext: CodexRequestContext,
+	stream: AssistantMessageEventStream,
+	error: unknown,
+): Promise<{
+	eventStream: AsyncGenerator<Record<string, unknown>>;
+	requestBodyForState: RequestBody;
+	transport: CodexTransport;
+}> {
+	if (
+		!isForcedToolChoiceUnsupportedError(error, isForcedCodexToolChoice(requestContext.transformedBody.tool_choice))
+	) {
+		throw error;
+	}
+	const reason = await finalizeErrorMessage(error, requestContext.rawRequestDump);
+	markToolChoiceIncapability(model, "auto", reason);
+	const resolvedToolChoice = resolveToolChoice(model, options?.toolChoice);
+	stream.push({
+		type: "toolChoiceIncapability",
+		api: model.api,
+		provider: model.provider,
+		model: model.id,
+		requestedLevel: resolvedToolChoice.requestedLevel,
+		resolvedLevel: "auto",
+		reason,
+		registryKey: resolvedToolChoice.registryKey,
+	});
+	const next = await openCodexSseTransportWithoutToolChoice(
+		model,
+		requestContext,
+		requestSetup,
+		options,
+		requestContext.websocketState,
+	);
+	requestContext.rawRequestDump = { ...requestContext.rawRequestDump, body: next.requestBodyForState };
+	return next;
+}
+
 interface CodexRequestSetup {
 	requestSignal: AbortSignal;
 	wrapCodexSseStream: (source: AsyncGenerator<Record<string, unknown>>) => AsyncGenerator<Record<string, unknown>>;
@@ -601,7 +647,16 @@ async function buildTransformedCodexRequestBody(
 	if (context.tools && context.tools.length > 0) {
 		params.tools = convertOpenAICodexResponsesTools(context.tools, model);
 		if (options?.toolChoice) {
-			const toolChoice = normalizeCodexToolChoice(options.toolChoice, context.tools, model);
+			const resolvedToolChoice = resolveToolChoice(model, options.toolChoice);
+			if (resolvedToolChoice.degraded && resolvedToolChoice.supportSource === "runtime") {
+				logCodexDebug("codex degraded tool_choice after runtime capability discovery", {
+					model: model.id,
+					requestedLevel: resolvedToolChoice.requestedLevel,
+					resolvedLevel: resolvedToolChoice.resolvedLevel,
+					reason: resolvedToolChoice.reason,
+				});
+			}
+			const toolChoice = normalizeCodexToolChoice(resolvedToolChoice.resolvedChoice, context.tools, model);
 			if (toolChoice) {
 				params.tool_choice = toolChoice;
 			}
@@ -754,6 +809,22 @@ async function openCodexSseTransport(
 	return { eventStream, requestBodyForState: structuredCloneJSON(body), transport: "sse" };
 }
 
+async function openCodexSseTransportWithoutToolChoice(
+	model: Model<"openai-codex-responses">,
+	requestContext: CodexRequestContext,
+	requestSetup: CodexRequestSetup,
+	options: OpenAICodexResponsesOptions | undefined,
+	state: CodexWebSocketSessionState | undefined,
+): Promise<{
+	eventStream: AsyncGenerator<Record<string, unknown>>;
+	requestBodyForState: RequestBody;
+	transport: CodexTransport;
+}> {
+	const body = structuredCloneJSON(requestContext.transformedBody);
+	delete body.tool_choice;
+	return openCodexSseTransport(model, requestContext, requestSetup, options, state, body);
+}
+
 async function reopenCodexWebSocketRuntimeStream(
 	context: CodexStreamProcessingContext,
 	runtime: CodexStreamRuntime,
@@ -1273,6 +1344,9 @@ async function recoverCodexStreamError(
 	runtime: CodexStreamRuntime,
 	error: unknown,
 ): Promise<boolean> {
+	if (await tryRetryWithoutForcedToolChoice(context, runtime, error)) {
+		return true;
+	}
 	if (await tryReconnectCodexWebSocketOnConnectionLimit(context, runtime, error)) {
 		return true;
 	}
@@ -1288,6 +1362,69 @@ async function recoverCodexStreamError(
 	return false;
 }
 
+async function tryRetryWithoutForcedToolChoice(
+	context: CodexStreamProcessingContext,
+	runtime: CodexStreamRuntime,
+	error: unknown,
+): Promise<boolean> {
+	if (
+		runtime.providerRetryAttempt > 0 ||
+		context.output.content.length > 0 ||
+		context.firstTokenTime !== undefined ||
+		context.options?.signal?.aborted ||
+		!isForcedToolChoiceUnsupportedError(error, isForcedCodexToolChoice(runtime.requestBodyForState.tool_choice))
+	) {
+		return false;
+	}
+
+	const reason = await finalizeErrorMessage(error, context.requestContext.rawRequestDump);
+	markToolChoiceIncapability(context.model, "auto", reason);
+	const resolvedToolChoice = resolveToolChoice(context.model, context.options?.toolChoice);
+	context.stream.push({
+		type: "toolChoiceIncapability",
+		api: context.model.api,
+		provider: context.model.provider,
+		model: context.model.id,
+		requestedLevel: resolvedToolChoice.requestedLevel,
+		resolvedLevel: "auto",
+		reason,
+		registryKey: resolvedToolChoice.registryKey,
+	});
+
+	runtime.providerRetryAttempt += 1;
+	runtime.currentItem = null;
+	runtime.currentBlock = null;
+	runtime.sawTerminalEvent = false;
+	runtime.nativeOutputItems.length = 0;
+	resetOutputState(context.output);
+	context.firstTokenTime = undefined;
+
+	const websocketState = context.requestContext.websocketState;
+	if (websocketState) {
+		resetCodexWebSocketAppendState(websocketState);
+		resetCodexSessionMetadata(websocketState);
+	}
+	const next = await openCodexSseTransportWithoutToolChoice(
+		context.model,
+		context.requestContext,
+		context.requestSetup,
+		context.options,
+		websocketState,
+	);
+	runtime.eventStream = next.eventStream;
+	runtime.requestBodyForState = next.requestBodyForState;
+	runtime.transport = next.transport;
+	if (websocketState) {
+		websocketState.lastTransport = next.transport;
+	}
+	context.requestContext.rawRequestDump = { ...context.requestContext.rawRequestDump, body: next.requestBodyForState };
+	return true;
+}
+
+function isForcedCodexToolChoice(choice: RequestBody["tool_choice"]): boolean {
+	return !!choice && choice !== "none" && choice !== "auto";
+}
+
 /**
  * Handles `websocket_connection_limit_reached` errors by closing the stale connection
  * and opening a fresh websocket. If content has already been emitted to the caller,
@@ -1546,7 +1683,19 @@ export const streamOpenAICodexResponses: StreamFunction<"openai-codex-responses"
 
 		try {
 			const requestContext = await buildCodexRequestContext(model, context, options, output);
-			const initialTransport = await openInitialCodexEventStream(model, options, requestSetup, requestContext);
+			let initialTransport: Awaited<ReturnType<typeof openInitialCodexEventStream>>;
+			try {
+				initialTransport = await openInitialCodexEventStream(model, options, requestSetup, requestContext);
+			} catch (error) {
+				initialTransport = await retryCodexInitialTransportWithoutToolChoice(
+					model,
+					options,
+					requestSetup,
+					requestContext,
+					stream,
+					error,
+				);
+			}
 			const runtime = createCodexStreamRuntime({
 				...initialTransport,
 				websocketState: requestContext.websocketState,

package/src/providers/openai-completions-compat.ts

@@ -4,12 +4,17 @@ type OpenAIReasoningEffort = "minimal" | "low" | "medium" | "high" | "xhigh" | "
 type ResolvedToolStrictMode = NonNullable<OpenAICompat["toolStrictMode"]> | "mixed";
 
 export type ResolvedOpenAICompat = Required<
-	Omit<OpenAICompat, "openRouterRouting" | "vercelGatewayRouting" | "extraBody" | "toolStrictMode">
+	Omit<
+		OpenAICompat,
+		"openRouterRouting" | "vercelGatewayRouting" | "extraBody" | "toolStrictMode" | "toolChoiceSupport"
+	>
 > & {
 	openRouterRouting?: OpenAICompat["openRouterRouting"];
 	vercelGatewayRouting?: OpenAICompat["vercelGatewayRouting"];
 	extraBody?: OpenAICompat["extraBody"];
 	toolStrictMode: ResolvedToolStrictMode;
+	/** Optional explicit capability override; resolved via deriveToolChoiceSupport. */
+	toolChoiceSupport?: OpenAICompat["toolChoiceSupport"];
 };
 
 function detectStrictModeSupport(provider: string, baseUrl: string): boolean {
@@ -191,6 +196,7 @@ export function detectOpenAICompat(model: Model<"openai-completions">, resolvedB
 		disableReasoningOnForcedToolChoice: isKimiModel || isAnthropicModel,
 		disableReasoningOnToolChoice: isDeepseekFamily && Boolean(model.reasoning) && !isOpenRouter,
 		supportsToolChoice: !isDirectDeepseekReasoning,
+		supportsForcedToolChoice: true,
 		maxTokensField: useMaxTokens ? "max_tokens" : "max_completion_tokens",
 		requiresToolResultName: isMistral,
 		requiresAssistantAfterToolResult: false,
@@ -254,6 +260,8 @@ export function resolveOpenAICompat(
 		reasoningEffortMap: { ...detected.reasoningEffortMap, ...(model.compat.reasoningEffortMap ?? {}) },
 		supportsUsageInStreaming: model.compat.supportsUsageInStreaming ?? detected.supportsUsageInStreaming,
 		supportsToolChoice: model.compat.supportsToolChoice ?? detected.supportsToolChoice,
+		supportsForcedToolChoice: model.compat.supportsForcedToolChoice ?? detected.supportsForcedToolChoice,
+		toolChoiceSupport: model.compat.toolChoiceSupport ?? detected.toolChoiceSupport,
 		maxTokensField: model.compat.maxTokensField ?? detected.maxTokensField,
 		requiresToolResultName: model.compat.requiresToolResultName ?? detected.requiresToolResultName,
 		requiresAssistantAfterToolResult: