@gajae-code/ai 0.4.4 → 0.5.0

package/src/models.ts

@@ -1,6 +1,7 @@
 import { enrichModelThinking } from "./model-thinking";
 import MODELS from "./models.json" with { type: "json" };
 import type { Api, KnownProvider, Model, Usage } from "./types";
+import { isClaudeForcedToolChoiceIncapableModelId } from "./utils/tool-choice-capability";
 
 /**
  * Static bundled model registry loaded from `models.json`.
@@ -10,28 +11,53 @@ import type { Api, KnownProvider, Model, Usage } from "./types";
  *
  * For runtime-aware resolution, use `createModelManager()` / `resolveProviderModels()`.
  */
-const modelRegistry: Map<string, Map<string, Model<Api>>> = new Map();
-for (const [provider, models] of Object.entries(MODELS)) {
+const providerNames = Object.keys(MODELS) as KnownProvider[];
+const providerModelRegistry: Map<string, Map<string, Model<Api>>> = new Map();
+
+function getProviderModels(provider: GeneratedProvider): Map<string, Model<Api>> | undefined {
+	const cached = providerModelRegistry.get(provider);
+	if (cached) return cached;
+	const models = MODELS[provider];
+	if (!models) return undefined;
 	const providerModels = new Map<string, Model<Api>>();
 	for (const [id, model] of Object.entries(models)) {
-		providerModels.set(id, enrichModelThinking(model as Model<Api>));
+		providerModels.set(id, applyBundledCompatDefaults(enrichModelThinking(model as Model<Api>)));
+	}
+	providerModelRegistry.set(provider, providerModels);
+	return providerModels;
+}
+
+/**
+ * Bundled-catalog compat defaults applied at load time so stale committed
+ * models.json snapshots still receive policy-critical fields (e.g. Claude
+ * Mythos rejecting forced tool use) without a full regeneration.
+ */
+function applyBundledCompatDefaults(model: Model<Api>): Model<Api> {
+	if (
+		(model.api === "anthropic-messages" || model.api === "bedrock-converse-stream") &&
+		isClaudeForcedToolChoiceIncapableModelId(model.id) &&
+		(model.compat as { toolChoiceSupport?: string } | undefined)?.toolChoiceSupport === undefined
+	) {
+		return { ...model, compat: { ...(model.compat ?? {}), toolChoiceSupport: "auto" } as Model<Api>["compat"] };
 	}
-	modelRegistry.set(provider, providerModels);
+	return model;
 }
 
 export type GeneratedProvider = keyof typeof MODELS;
 
 export function getBundledModel<TApi extends Api = Api>(provider: GeneratedProvider, modelId: string): Model<TApi> {
-	const providerModels = modelRegistry.get(provider);
+	const providerModels = getProviderModels(provider);
 	return providerModels?.get(modelId) as Model<TApi>;
 }
 
 export function getBundledProviders(): KnownProvider[] {
-	return Array.from(modelRegistry.keys()) as KnownProvider[];
+	// Defensive copy: the old eager path returned a fresh Array.from(...), so
+	// callers may freely mutate their result without corrupting enumeration.
+	return providerNames.slice();
 }
 
 export function getBundledModels(provider: GeneratedProvider): Model<Api>[] {
-	const models = modelRegistry.get(provider);
+	const models = getProviderModels(provider);
 	return models ? (Array.from(models.values()) as Model<Api>[]) : [];
 }
 

package/src/provider-models/openai-compat.ts

@@ -11,6 +11,7 @@ import {
 } from "../utils/discovery/openai-compatible";
 import { toFireworksPublicModelId } from "../utils/fireworks-model-id";
 import { getGitHubCopilotBaseUrl, OPENCODE_HEADERS, parseGitHubCopilotApiKey } from "../utils/oauth/github-copilot";
+import { isClaudeForcedToolChoiceIncapableModelId } from "../utils/tool-choice-capability";
 import { createBundledReferenceMap, createReferenceResolver } from "./bundled-references";
 
 const MODELS_DEV_URL = "https://models.dev/api.json";
@@ -68,6 +69,9 @@ async function fetchModelsDevPayload(fetchImpl: typeof fetch = fetch): Promise<u
 	return response.json();
 }
 
+function anthropicToolChoiceCompat(modelId: string): Pick<Model<"anthropic-messages">, "compat"> {
+	return isClaudeForcedToolChoiceIncapableModelId(modelId) ? { compat: { toolChoiceSupport: "auto" } } : {};
+}
 function mapAnthropicModelsDev(payload: unknown, baseUrl: string): Model<"anthropic-messages">[] {
 	if (!isRecord(payload)) {
 		return [];
@@ -106,6 +110,7 @@ function mapAnthropicModelsDev(payload: unknown, baseUrl: string): Model<"anthro
 			},
 			contextWindow: toPositiveNumber(model.limit?.context, UNK_CONTEXT_WINDOW),
 			maxTokens: toPositiveNumber(model.limit?.output, UNK_MAX_TOKENS),
+			...anthropicToolChoiceCompat(modelId),
 		});
 	}
 
@@ -141,7 +146,10 @@ function buildAnthropicReferenceMap(
 		(model): model is Model<"anthropic-messages"> => model.api === "anthropic-messages",
 	);
 	for (const model of bundledModels) {
-		merged.set(model.id, model);
+		merged.set(model.id, {
+			...model,
+			compat: { ...(model.compat ?? {}), ...anthropicToolChoiceCompat(model.id).compat },
+		});
 	}
 	return merged;
 }

package/src/providers/amazon-bedrock.ts

@@ -25,6 +25,7 @@ import type {
 	ThinkingContent,
 	Tool,
 	ToolCall,
+	ToolChoice,
 	ToolResultMessage,
 } from "../types";
 import { normalizeToolCallId, resolveCacheRetention } from "../utils";
@@ -33,6 +34,11 @@ import { appendRawHttpRequestDumpFor400, type RawHttpRequestDump, withHttpStatus
 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 { resolveAwsCredentials } from "./aws-credentials";
 import { decodeEventStream } from "./aws-eventstream";
 import { signRequest } from "./aws-sigv4";
@@ -43,7 +49,7 @@ export type BedrockThinkingDisplay = "summarized" | "omitted";
 export interface BedrockOptions extends StreamOptions {
 	region?: string;
 	profile?: string;
-	toolChoice?: "auto" | "any" | "none" | { type: "tool"; name: string };
+	toolChoice?: ToolChoice;
 	/* See https://docs.aws.amazon.com/bedrock/latest/userguide/inference-reasoning.html for supported models. */
 	reasoning?: Effort;
 	/* Custom token budgets per thinking level. Overrides default budgets. */
@@ -191,11 +197,12 @@ export const streamBedrock: StreamFunction<"bedrock-converse-stream"> = (
 
 		try {
 			const cacheRetention = resolveCacheRetention(options.cacheRetention);
-			const toolConfig = convertToolConfig(context.tools, options.toolChoice);
+			const resolvedToolChoice = resolveToolChoice(model, options.toolChoice);
+			const toolConfig = convertToolConfig(context.tools, resolvedToolChoice.resolvedChoice);
 			let additionalModelRequestFields = buildAdditionalModelRequestFields(model, options);
 
 			// Bedrock rejects thinking + forced tool_choice ("any" or specific tool).
-			// When tool_choice forces tool use, disable thinking to avoid API errors.
+			// When the resolved tool_choice forces tool use, disable thinking to avoid API errors.
 			if (toolConfig?.toolChoice && additionalModelRequestFields) {
 				const tc = toolConfig.toolChoice;
 				if (tc.any || tc.tool) additionalModelRequestFields = undefined;
@@ -254,8 +261,45 @@ export const streamBedrock: StreamFunction<"bedrock-converse-stream"> = (
 				headers: baseHeaders,
 			});
 			const requestHeaders: Record<string, string> = { ...baseHeaders, ...signed };
+			const sentForcedToolChoice = Boolean(toolConfig?.toolChoice?.any || toolConfig?.toolChoice?.tool);
+			let fallbackRan = false;
+			const retryWithoutForcedToolChoice = async (reason: string) => {
+				fallbackRan = true;
+				markToolChoiceIncapability(model, "auto", reason);
+				stream.push({
+					type: "toolChoiceIncapability",
+					api: output.api,
+					provider: model.provider,
+					model: model.id,
+					requestedLevel: resolvedToolChoice.requestedLevel,
+					resolvedLevel: "auto",
+					reason,
+					registryKey: resolvedToolChoice.registryKey,
+				});
+				stripBedrockForcedToolChoiceForRetry(commandInput);
+				const retryBodyText = JSON.stringify(commandInput);
+				const retryBody = new TextEncoder().encode(retryBodyText);
+				const retrySigned = await signRequest({
+					method: "POST",
+					host,
+					path: urlPath,
+					body: retryBody,
+					region,
+					service: "bedrock",
+					credentials,
+					headers: baseHeaders,
+				});
+				if (rawRequestDump) rawRequestDump.body = commandInput;
+				return fetchWithRetry(url, {
+					method: "POST",
+					headers: { ...baseHeaders, ...retrySigned },
+					body: retryBody,
+					signal: options.signal,
+					maxAttempts: 1,
+				});
+			};
 
-			const response = await fetchWithRetry(url, {
+			let response = await fetchWithRetry(url, {
 				method: "POST",
 				headers: requestHeaders,
 				body,
@@ -263,6 +307,18 @@ export const streamBedrock: StreamFunction<"bedrock-converse-stream"> = (
 				maxAttempts: resolveRetryBudget(options.requestMaxRetries, 4) + 1,
 			});
 
+			if (!response.ok && sentForcedToolChoice) {
+				const errBody = await response.text().catch(() => "");
+				const error = withHttpStatus(
+					new Error(`Bedrock HTTP ${response.status}: ${errBody.slice(0, 1000)}`),
+					response.status,
+				);
+				if (firstTokenTime === undefined && !fallbackRan && isForcedToolChoiceUnsupportedError(error, true)) {
+					response = await retryWithoutForcedToolChoice(error.message);
+				} else {
+					throw error;
+				}
+			}
 			if (!response.ok) {
 				const errBody = await response.text().catch(() => "");
 				throw withHttpStatus(
@@ -273,65 +329,86 @@ export const streamBedrock: StreamFunction<"bedrock-converse-stream"> = (
 			if (!response.body) throw new Error("Bedrock response has no body");
 
 			// Track first event for the abort/diagnostic path (currently informational).
-			for await (const message of decodeEventStream(response.body)) {
-				const messageType = message.headers[":message-type"];
-				const eventType = message.headers[":event-type"];
-
-				if (messageType === "exception") {
-					const exceptionType = message.headers[":exception-type"] || "Exception";
-					const payload = safeParsePayload(message.payload) as { message?: string } | undefined;
-					const errorMessage = payload?.message || new TextDecoder().decode(message.payload);
-					const status = exceptionType === "validationException" ? 400 : 0;
-					const err = new Error(`${exceptionType}: ${errorMessage}`);
-					throw status ? withHttpStatus(err, status) : err;
-				}
-				if (messageType === "error") {
-					const code = message.headers[":error-code"] || "UnknownError";
-					const errorMessage = message.headers[":error-message"] || new TextDecoder().decode(message.payload);
-					throw new Error(`${code}: ${errorMessage}`);
-				}
-				if (messageType !== "event") continue;
-
-				const payload = safeParsePayload(message.payload);
-				if (!payload) continue;
-
-				switch (eventType) {
-					case "messageStart": {
-						// no-op: first event marker is implicit by stream entry.
-						const ev = payload as MessageStartEvent;
-						if (ev.role !== "assistant") {
-							throw new Error("Unexpected assistant message start but got user message start instead");
+			streamLoop: while (true) {
+				for await (const message of decodeEventStream(response.body)) {
+					const messageType = message.headers[":message-type"];
+					const eventType = message.headers[":event-type"];
+
+					if (messageType === "exception") {
+						const exceptionType = message.headers[":exception-type"] || "Exception";
+						const payload = safeParsePayload(message.payload) as { message?: string } | undefined;
+						const errorMessage = payload?.message || new TextDecoder().decode(message.payload);
+						const status = exceptionType === "validationException" ? 400 : 0;
+						const err = new Error(`${exceptionType}: ${errorMessage}`);
+						const error = status ? withHttpStatus(err, status) : err;
+						if (
+							firstTokenTime === undefined &&
+							sentForcedToolChoice &&
+							!fallbackRan &&
+							isForcedToolChoiceUnsupportedError(error, true)
+						) {
+							response = await retryWithoutForcedToolChoice(error.message);
+							if (!response.ok) {
+								const errBody = await response.text().catch(() => "");
+								throw withHttpStatus(
+									new Error(`Bedrock HTTP ${response.status}: ${errBody.slice(0, 1000)}`),
+									response.status,
+								);
+							}
+							if (!response.body) throw new Error("Bedrock response has no body");
+							continue streamLoop;
 						}
-						stream.push({ type: "start", partial: output });
-						break;
-					}
-					case "contentBlockStart": {
-						if (!firstTokenTime) firstTokenTime = Date.now();
-						handleContentBlockStart(payload as ContentBlockStartEvent, blocks, output, stream);
-						break;
-					}
-					case "contentBlockDelta": {
-						if (!firstTokenTime) firstTokenTime = Date.now();
-						handleContentBlockDelta(payload as ContentBlockDeltaEvent, blocks, output, stream);
-						break;
-					}
-					case "contentBlockStop": {
-						handleContentBlockStop(payload as ContentBlockStopEvent, blocks, output, stream);
-						break;
+						throw error;
 					}
-					case "messageStop": {
-						const ev = payload as MessageStopEvent;
-						output.stopReason = mapStopReason(ev.stopReason);
-						break;
+					if (messageType === "error") {
+						const code = message.headers[":error-code"] || "UnknownError";
+						const errorMessage = message.headers[":error-message"] || new TextDecoder().decode(message.payload);
+						throw new Error(`${code}: ${errorMessage}`);
 					}
-					case "metadata": {
-						handleMetadata(payload as MetadataEvent, model, output);
-						break;
+					if (messageType !== "event") continue;
+
+					const payload = safeParsePayload(message.payload);
+					if (!payload) continue;
+
+					switch (eventType) {
+						case "messageStart": {
+							// no-op: first event marker is implicit by stream entry.
+							const ev = payload as MessageStartEvent;
+							if (ev.role !== "assistant") {
+								throw new Error("Unexpected assistant message start but got user message start instead");
+							}
+							stream.push({ type: "start", partial: output });
+							break;
+						}
+						case "contentBlockStart": {
+							if (!firstTokenTime) firstTokenTime = Date.now();
+							handleContentBlockStart(payload as ContentBlockStartEvent, blocks, output, stream);
+							break;
+						}
+						case "contentBlockDelta": {
+							if (!firstTokenTime) firstTokenTime = Date.now();
+							handleContentBlockDelta(payload as ContentBlockDeltaEvent, blocks, output, stream);
+							break;
+						}
+						case "contentBlockStop": {
+							handleContentBlockStop(payload as ContentBlockStopEvent, blocks, output, stream);
+							break;
+						}
+						case "messageStop": {
+							const ev = payload as MessageStopEvent;
+							output.stopReason = mapStopReason(ev.stopReason);
+							break;
+						}
+						case "metadata": {
+							handleMetadata(payload as MetadataEvent, model, output);
+							break;
+						}
+						default:
+							// Unknown event types (Bedrock may add new ones) — ignore.
+							break;
 					}
-					default:
-						// Unknown event types (Bedrock may add new ones) — ignore.
-						break;
 				}
+				break;
 			}
 
 			if (options.signal?.aborted) throw new Error("Request was aborted");
@@ -714,7 +791,14 @@ function convertMessages(
 	return result;
 }
 
-function convertToolConfig(
+export function stripBedrockForcedToolChoiceForRetry<T extends { toolConfig?: { toolChoice?: unknown } }>(body: T): T {
+	if (body.toolConfig) {
+		body.toolConfig = { ...body.toolConfig, toolChoice: undefined };
+	}
+	return body;
+}
+
+export function convertToolConfig(
 	tools: Tool[] | undefined,
 	toolChoice: BedrockOptions["toolChoice"],
 ): WireToolConfig | undefined {
@@ -734,6 +818,7 @@ function convertToolConfig(
 			bedrockToolChoice = { auto: {} };
 			break;
 		case "any":
+		case "required":
 			bedrockToolChoice = { any: {} };
 			break;
 		default:
@@ -742,7 +827,7 @@ function convertToolConfig(
 			}
 	}
 
-	return { tools: bedrockTools, toolChoice: bedrockToolChoice };
+	return bedrockToolChoice ? { tools: bedrockTools, toolChoice: bedrockToolChoice } : { tools: bedrockTools };
 }
 
 function mapStopReason(reason: string | undefined): StopReason {

package/src/providers/anthropic.ts

@@ -65,6 +65,12 @@ import { resolveRetryBudget } from "../utils/retry-budget";
 import { COMBINATOR_KEYS, NO_STRICT, toolWireSchema } from "../utils/schema";
 import { spillToDescription } from "../utils/schema/spill";
 import { notifyRawSseEvent, wrapFetchForSseDebug } from "../utils/sse-debug";
+import {
+	isForcedToolChoiceUnsupportedError,
+	markToolChoiceIncapability,
+	type ResolveToolChoiceResult,
+	resolveToolChoice,
+} from "../utils/tool-choice-capability";
 import {
 	buildCopilotDynamicHeaders,
 	hasCopilotVisionInput,
@@ -875,12 +881,16 @@ async function getAnthropicStreamResponse(
 
 function getAnthropicCompat(
 	model: Model<"anthropic-messages">,
-): Required<NonNullable<Model<"anthropic-messages">["compat"]>> {
+): Required<Omit<NonNullable<Model<"anthropic-messages">["compat"]>, "toolChoiceSupport">> &
+	Pick<NonNullable<Model<"anthropic-messages">["compat"]>, "toolChoiceSupport"> {
 	return {
 		disableStrictTools: model.compat?.disableStrictTools ?? false,
 		disableAdaptiveThinking: model.compat?.disableAdaptiveThinking ?? false,
 		supportsEagerToolInputStreaming: model.compat?.supportsEagerToolInputStreaming ?? true,
 		supportsLongCacheRetention: model.compat?.supportsLongCacheRetention ?? true,
+		supportsToolChoice: model.compat?.supportsToolChoice ?? true,
+		supportsForcedToolChoice: model.compat?.supportsForcedToolChoice ?? true,
+		toolChoiceSupport: model.compat?.toolChoiceSupport,
 	};
 }
 
@@ -1074,8 +1084,10 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 				(providerSessionState?.strictToolsDisabled ?? false) || (model.compat?.disableStrictTools ?? false);
 			let strictFallbackErrorMessage: string | undefined;
 			let dropFastMode = providerSessionState?.fastModeDisabled ?? false;
+			let droppedForcedToolChoice = false;
 			const prepareParams = async (paramsOptions?: {
 				repairLatestAssistantThinking?: boolean;
+				dropForcedToolChoice?: boolean;
 			}): Promise<MessageCreateParamsStreaming> => {
 				let nextParams = buildParams(
 					model,
@@ -1086,6 +1098,9 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 					disableStrictTools,
 					paramsOptions?.repairLatestAssistantThinking === true,
 				);
+				if (paramsOptions?.dropForcedToolChoice === true) {
+					delete nextParams.tool_choice;
+				}
 				if (disableStrictTools) {
 					dropAnthropicStrictTools(nextParams);
 				}
@@ -1399,6 +1414,39 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 						firstTokenTime = undefined;
 						continue;
 					}
+					if (
+						!droppedForcedToolChoice &&
+						firstTokenTime === undefined &&
+						isSentForcedAnthropicToolChoice(params.tool_choice) &&
+						isForcedToolChoiceUnsupportedError(streamFailure, true)
+					) {
+						const message = await finalizeErrorMessage(streamFailure, rawRequestDump);
+						logger.debug("anthropic: forced tool_choice unsupported, retrying with auto tool choice", {
+							model: model.id,
+							error: message,
+						});
+						markToolChoiceIncapability(model, "auto", message);
+						stream.push({
+							type: "toolChoiceIncapability",
+							api: output.api,
+							provider: model.provider,
+							model: model.id,
+							requestedLevel: resolveToolChoice(model, options?.toolChoice).requestedLevel,
+							resolvedLevel: "auto",
+							reason: message,
+							registryKey: resolveToolChoice(model, options?.toolChoice).registryKey,
+						});
+						droppedForcedToolChoice = true;
+						params = await prepareParams({ dropForcedToolChoice: true });
+						providerRetryAttempt = 0;
+						output.content.length = 0;
+						output.responseId = undefined;
+						output.providerPayload = undefined;
+						output.usage = createEmptyUsage(copilotDynamicHeaders?.premiumRequests);
+						output.stopReason = "stop";
+						firstTokenTime = undefined;
+						continue;
+					}
 					if (
 						!thinkingRepairAttempted &&
 						firstTokenTime === undefined &&
@@ -1682,6 +1730,31 @@ function disableThinkingIfToolChoiceForced(params: MessageCreateParamsStreaming)
 	}
 }
 
+function mapAnthropicToolChoice(
+	toolChoice: NonNullable<ResolveToolChoiceResult["resolvedChoice"]>,
+	isOAuthToken: boolean,
+): NonNullable<MessageCreateParamsStreaming["tool_choice"]> | undefined {
+	if (typeof toolChoice === "string") {
+		if (toolChoice === "required") return { type: "any" };
+		return { type: toolChoice };
+	}
+	if ("function" in toolChoice) {
+		const name = typeof toolChoice.function === "string" ? toolChoice.function : toolChoice.function.name;
+		return { type: "tool", name: isOAuthToken ? applyClaudeToolPrefix(name) : name };
+	}
+	if ("name" in toolChoice && typeof toolChoice.name === "string") {
+		return {
+			...toolChoice,
+			type: "tool",
+			name: isOAuthToken ? applyClaudeToolPrefix(toolChoice.name) : toolChoice.name,
+		};
+	}
+	return toolChoice as NonNullable<MessageCreateParamsStreaming["tool_choice"]>;
+}
+function isSentForcedAnthropicToolChoice(toolChoice: MessageCreateParamsStreaming["tool_choice"] | undefined): boolean {
+	return toolChoice?.type === "any" || toolChoice?.type === "tool";
+}
+
 function ensureMaxTokensForThinking(params: MessageCreateParamsStreaming, model: Model<"anthropic-messages">): void {
 	const thinking = params.thinking;
 	if (thinking?.type !== "enabled") return;
@@ -2030,15 +2103,21 @@ function buildParams(
 	}
 
 	if (options?.toolChoice) {
-		if (typeof options.toolChoice === "string") {
-			params.tool_choice = { type: options.toolChoice };
-		} else if (isOAuthToken && options.toolChoice.name) {
-			params.tool_choice = {
-				...options.toolChoice,
-				name: applyClaudeToolPrefix(options.toolChoice.name),
-			};
-		} else {
-			params.tool_choice = options.toolChoice;
+		const resolution = resolveToolChoice(model, options.toolChoice);
+		if (resolution.degraded && resolution.supportSource !== "runtime") {
+			logger.debug("anthropic: degrading tool_choice for model capability", {
+				model: model.id,
+				requestedLevel: resolution.requestedLevel,
+				resolvedLevel: resolution.resolvedLevel,
+				reason: resolution.reason,
+				supportSource: resolution.supportSource,
+			});
+		}
+		if (resolution.resolvedChoice) {
+			const mappedToolChoice = mapAnthropicToolChoice(resolution.resolvedChoice, isOAuthToken);
+			if (mappedToolChoice) {
+				params.tool_choice = mappedToolChoice;
+			}
 		}
 	}
 

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

@@ -1,4 +1,4 @@
-import { $env, extractHttpStatusFromError } from "@gajae-code/utils";
+import { $env, extractHttpStatusFromError, logger } from "@gajae-code/utils";
 import { AzureOpenAI } from "openai";
 import type {
 	Tool as OpenAITool,
@@ -30,6 +30,11 @@ import { resolveRetryBudget } from "../utils/retry-budget";
 import { sanitizeSchemaForOpenAIResponses, toolWireSchema } from "../utils/schema";
 import { wrapFetchForSseDebug } from "../utils/sse-debug";
 import { mapToOpenAIResponsesToolChoice } from "../utils/tool-choice";
+import {
+	isForcedToolChoiceUnsupportedError,
+	markToolChoiceIncapability,
+	resolveToolChoice,
+} from "../utils/tool-choice-capability";
 import { normalizeOpenAIResponsesPromptCacheKey, supportsDeveloperRole } from "./openai-responses";
 import {
 	appendResponsesToolResultMessages,
@@ -130,7 +135,30 @@ export const streamAzureOpenAIResponses: StreamFunction<"azure-openai-responses"
 				url: `${baseUrl}/responses`,
 				body: params,
 			};
-			const openaiStream = await client.responses.create(params, { signal: requestSignal });
+			let openaiStream: Awaited<ReturnType<typeof client.responses.create>>;
+			try {
+				openaiStream = await client.responses.create(params, { signal: requestSignal });
+			} catch (error) {
+				if (!isForcedToolChoiceUnsupportedError(error, isForcedAzureResponsesToolChoice(params.tool_choice))) {
+					throw error;
+				}
+				const reason = await finalizeErrorMessage(error, 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,
+				});
+				delete params.tool_choice;
+				rawRequestDump = { ...rawRequestDump, body: params };
+				openaiStream = await client.responses.create(params, { signal: requestSignal });
+			}
 			const firstEventWatchdog = createWatchdog(
 				options?.streamFirstEventTimeoutMs ?? getStreamFirstEventTimeoutMs(idleTimeoutMs),
 				() => abortTracker.abortLocally(firstEventTimeoutAbortError),
@@ -278,7 +306,16 @@ function buildParams(
 	if (context.tools) {
 		params.tools = convertTools(context.tools);
 		if (options?.toolChoice) {
-			params.tool_choice = mapToOpenAIResponsesToolChoice(options.toolChoice);
+			const toolChoice = resolveToolChoice(model, options.toolChoice);
+			if (toolChoice.degraded && toolChoice.supportSource === "runtime") {
+				logger.debug("azure-openai-responses: degraded tool_choice after runtime capability discovery", {
+					model: model.id,
+					requestedLevel: toolChoice.requestedLevel,
+					resolvedLevel: toolChoice.resolvedLevel,
+					reason: toolChoice.reason,
+				});
+			}
+			params.tool_choice = mapToOpenAIResponsesToolChoice(toolChoice.resolvedChoice);
 		}
 	}
 
@@ -287,6 +324,10 @@ function buildParams(
 	return params;
 }
 
+function isForcedAzureResponsesToolChoice(choice: AzureOpenAIResponsesSamplingParams["tool_choice"]): boolean {
+	return !!choice && choice !== "none" && choice !== "auto";
+}
+
 function convertMessages(
 	model: Model<"azure-openai-responses">,
 	context: Context,

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.`;