@gajae-code/ai 0.12.12 → 0.12.13

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [0.12.13] - 2026-08-06
+
+### Changed
+
+- Anthropic prompt caching now defaults to top-level automatic caching (`cache_control: { type: "ephemeral" }`) for every Claude-family model, including through non-canonical Anthropic-compatible gateways (Cloudflare AI Gateway, GitHub Copilot, GitLab Duo, Vercel AI Gateway, zenmux, etc.), instead of only `api.anthropic.com`. Non-Claude models on unknown compatible endpoints keep the previous no-cache default; `compat.promptCacheMode: "none"`, `compat.promptCacheMode: "explicit"`, and configured or per-request `cacheRetention: "none"` still opt out. Non-canonical Claude models get the default ~5m cache lifetime unless the endpoint sets `compat.supportsLongCacheRetention: true`.
+
+### Fixed
+
+- `todo_write` raw argument rejections now carry bounded, authority-controlled correction codes for each rejected shape: unknown root keys, unknown operation-entry keys, done/drop entries missing a task or phase target, and unknown init list-entry keys. Each code maps to a fixed correction message naming the accepted shape (never echoing the offending input), so invalid calls surface specific guidance while valid payloads keep the existing passthrough/coercion path (#3916).
+- Anthropic Sonnet 5 now exposes Anthropic's real `xhigh` and `max` thinking efforts on the Messages API (`minimal`/`low`/`medium`/`high`/`xhigh`/`max`), matching official support. The previous generic `kind === opus` gate excluded it from the full preset range; the capability predicate is now an explicit version-scoped list (Opus 4.7+, Sonnet 5+), so older Sonnet generations and Bedrock Converse routes stay fail-closed at their previously advertised levels (issue #3913).
+- Alibaba Token Plan now exposes Qwen 3.8 Max under the provider-supported `qwen3.8-max` wire id instead of the rejected `qwen-3.8-max` spelling; catalog regeneration canonicalizes a legacy discovered alias rather than retaining a broken duplicate (#3909).
+- Canonicalized first-class MiniMax M3 catalog ids (issue #3896). The bundled catalog previously shipped stale lowercase `minimax-m3` duplicates (512K) next to the canonical `MiniMax-M3` (1M) on all four first-class MiniMax providers, plus a non-official `minimax-v3` entry under `minimax-code`. The lowercase `minimax-m3` entries and `minimax-v3` are removed; `MiniMax-M3` is the single canonical first-class id (the regen-safe 1M pin in `applyGeneratedModelPolicy` now keys on `MiniMax-M3` / `MiniMax-M3[1m]` instead of the removed lowercase id), `DEFAULT_MODEL_PER_PROVIDER` points at `MiniMax-M3`, and the official Anthropic Token Plan id `MiniMax-M3[1m]` is first-class on the `minimax` / `minimax-cn` Anthropic routes with 1M context semantics. Unrelated catalog providers keep their own `minimax-m3` contracts.
+- Anthropic thinking-replay repair now also triggers when the mutation/signature `invalid_request_error` arrives as a statusless in-stream SSE `error` event (issue #3900). Proxies such as CLIProxyAPI forward the upstream 400 body over an HTTP 200 SSE stream, so the thrown error carries no HTTP status; the classifiers previously required `status === 400` and let the session loop on an unrecoverable replay rejection. Statusless errors still require the full `invalid_request_error` thinking wording, so unrelated transport failures never claim the one-shot repair.
+- Anthropic thinking-replay repair now also recovers when a proxy masks the rejection entirely (issue #3900). Live CLIProxyAPI captures replace the upstream 400 body with a generic `{"type":"api_error","message":"An error occurred while processing the request."}` SSE event on an HTTP 200 response, which names no cause and matches no transient phrase, so the turn died on the first attempt. Such a masked rejection now takes the same one-shot latest-then-full-history repair, but only before the first token and only while the request actually replays signed `thinking`/`redacted_thinking` blocks; masked failures on requests without replayed thinking still surface immediately. The classifier is exported as `isAnthropicMaskedProxyRejection`.
+
+- Anthropic cache-control resolution now falls back to `model.cacheRetention` at the provider boundary, preserving configured retention and request-over-model precedence through special dispatch wrappers such as GitLab Duo. A configured `cacheRetention: "none"` can no longer be dropped and replaced by the new automatic Claude-family cache marker.
+- Anthropic explicit prompt caching now advances its conversation breakpoint during tool-use loops by marking the latest completed assistant tool-use turn while leaving the newest tool result uncached. Previously it kept refreshing only the original human message until another human turn arrived, pinning proxy cache reads to the static tools/system prefix throughout long agentic runs.
 ## [0.12.12] - 2026-08-05
 
 ### Fixed
@@ -9,6 +26,7 @@
 - OpenAI Responses and Azure OpenAI Responses now map the first-event timeout into the SDK request/setup timeout the same way Completions does, so a never-resolving pre-headers fetch on a provider-owned lazy stream cannot wait the SDK's 10-minute default before any transport watchdog exists. Alibaba Responses honors an explicit shorter first-event override before headers; Azure/env-pinned setup timeouts normalize to the typed `stream_first_event_timeout` failure.
 - OpenAI Codex cost estimates now treat an explicit response `service_tier` as authoritative, so a request for priority processing that the provider serves at the default tier is no longer charged the priority multiplier; the requested tier remains the fallback when the terminal response omits the field.
 - Added shared `isReasoningContentReplayError` classifier and `stripUnusableReasoningItems` repair for the DeepSeek-family reasoning-content replay rejection ("The `reasoning_content` in the thinking mode must be passed back to the API"). The classifier detects the error across message carrier shapes; the repair removes only `reasoning` items whose `encrypted_content` a proxy stripped to empty, preserving all non-reasoning history (text, tool calls, tool outputs). The agent loop consumes both for a bounded repair-and-resend circuit breaker.
+- Codex statusless HTTP 200 SSE `invalid_request_error` events retry once without a forced named function choice only when the exact rejected name is still present in the request's serialized tools, before any output is emitted (#3669).
 
 ## [0.12.11] - 2026-08-03
 

package/dist/types/providers/anthropic.d.ts

@@ -50,6 +50,19 @@ export declare function isAnthropicThinkingBlockMutationError(error: unknown): b
  * than only the latest one.
  */
 export declare function isAnthropicThinkingSignatureInvalidError(error: unknown): boolean;
+/**
+ * CLIProxyAPI replaces Anthropic's rejection body wholesale instead of forwarding
+ * it: the client only ever sees
+ * `{"type":"error","error":{"type":"api_error","message":"An error occurred while
+ * processing the request."}}`, delivered as an in-stream SSE `error` event on an
+ * HTTP 200 response, so neither the status nor the message survives. Captured CPA
+ * traces for that masked shape carry the thinking-integrity 400 upstream (issue
+ * #3900), and the generic body matches no transient phrase either, so the turn
+ * dies unrecoverably. Nothing in the payload names the cause; callers must pair
+ * this with a request that actually replays signed thinking blocks before
+ * treating it as a thinking-replay rejection.
+ */
+export declare function isAnthropicMaskedProxyRejection(error: unknown): boolean;
 export declare const claudeCodeVersion = "2.1.219";
 export declare const claudeCodeEntrypoint = "sdk-cli";
 export declare const claudeToolPrefix: string;

package/dist/types/types.d.ts

@@ -537,7 +537,7 @@ export type TSchema = ZodType | TJsonSchema;
 export type Static<S> = S extends ZodType ? z.infer<S> : S extends {
     static: infer T;
 } ? T : unknown;
-export type RawArgumentRejectionCode = "ask-intent-review-requires-positive-round" | "ask-intent-contract-requires-non-empty-authority" | "ask-deep-interview-metadata-requires-deep-interview-gate";
+export type RawArgumentRejectionCode = "ask-intent-review-requires-positive-round" | "ask-intent-contract-requires-non-empty-authority" | "ask-deep-interview-metadata-requires-deep-interview-gate" | "todo-write-unknown-root-key" | "todo-write-unknown-op-entry-key" | "todo-write-done-drop-requires-target" | "todo-write-unknown-init-entry-key";
 export type RawArgumentValidationResult = {
     outcome: "passthrough";
 } | {
@@ -790,8 +790,10 @@ export interface AnthropicCompat extends ToolChoiceCompat {
     supportsLongCacheRetention?: boolean;
     /**
      * Prompt-cache transport accepted by this Anthropic-compatible endpoint.
-     * Canonical Anthropic defaults to `"automatic"`; noncanonical endpoints default
-     * to `"none"` and must explicitly opt into generated `"explicit"` markers.
+     * Canonical Anthropic and Claude-family models default to `"automatic"`;
+     * noncanonical non-Claude endpoints default to `"none"`. Set `"automatic"` to
+     * opt an otherwise unknown compatible endpoint into top-level caching, `"none"`
+     * to opt out, or `"explicit"` for endpoints that require block-level markers.
      */
     promptCacheMode?: "none" | "explicit" | "automatic";
 }

package/dist/types/utils/tool-choice-capability.d.ts

@@ -26,6 +26,11 @@ export declare function markToolChoiceIncapability(model: Model<Api>, maxSupport
 export declare function resolveToolChoice(model: Model<Api>, requested: ToolChoice | undefined, compat?: ToolChoiceCompat): ResolveToolChoiceResult;
 /** Detects provider errors indicating forced tool_choice is unsupported. */
 export declare function isForcedToolChoiceUnsupportedError(error: unknown, sentForcedToolChoice: boolean): boolean;
+/**
+ * Detects Codex's statusless SSE rejection for a named function tool choice.
+ * This is intentionally separate from the shared HTTP-400 classifier.
+ */
+export declare function isCodexStatuslessNamedToolChoiceNotFoundError(error: unknown, forcedToolName: string | undefined, sentToolNames: readonly string[]): boolean;
 export type { ToolChoiceCompat, ToolChoiceSupport, ToolChoiceSupportSource } from "../types";
 export interface ResolveToolChoiceResult {
     requestedChoice: ToolChoice | undefined;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/ai",
-	"version": "0.12.12",
+	"version": "0.12.13",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -40,7 +40,7 @@
 	"dependencies": {
 		"@anthropic-ai/sdk": "^0.94.0",
 		"@bufbuild/protobuf": "^2.12.0",
-		"@gajae-code/utils": "0.12.12",
+		"@gajae-code/utils": "0.12.13",
 		"openai": "^6.36.0",
 		"partial-json": "^0.1.7",
 		"zod": "4.4.3"

package/src/model-thinking.ts

@@ -379,8 +379,18 @@ export function supportsAnthropicAdaptiveThinkingDisplay(modelId: string): boole
 function anthropicModelHasRealXHighEffort<TApi extends Api>(model: ApiModel<TApi>): boolean {
 	if (model.api !== "anthropic-messages") return false;
 	const parsedModel = parseKnownModel(model.id);
-	if (parsedModel.family !== "anthropic" || parsedModel.kind !== "opus") return false;
-	return semverGte(parsedModel.version, "4.7");
+	if (parsedModel.family !== "anthropic") return false;
+	// Explicit capability predicate instead of a generic `kind === opus` gate:
+	// Sonnet 5 officially exposes Anthropic's real xhigh and max presets on
+	// the Messages API just like Opus 4.7+. Older Sonnet generations do not,
+	// so the predicate stays fail-closed for them.
+	if (parsedModel.kind === "opus") {
+		return semverGte(parsedModel.version, "4.7");
+	}
+	if (parsedModel.kind === "sonnet") {
+		return semverGte(parsedModel.version, "5.0");
+	}
+	return false;
 }
 
 function applyGeneratedModelPolicy(model: ApiModel<Api>): void {
@@ -457,10 +467,11 @@ function applyGeneratedModelPolicy(model: ApiModel<Api>): void {
 		};
 	}
 	// MiniMax-M3's official Token Plan routes expose a 1M context window.
-	// Scope the correction to the four first-class regional MiniMax routes;
-	// unrelated catalog aliases and providers keep their own contracts.
+	// Scope the correction to the four first-class regional MiniMax routes
+	// (canonical id plus the Anthropic Token Plan `[1m]` id); unrelated
+	// catalog aliases and providers keep their own contracts.
 	if (
-		model.id === "minimax-m3" &&
+		(model.id === "MiniMax-M3" || model.id === "MiniMax-M3[1m]") &&
 		(model.provider === "minimax" ||
 			model.provider === "minimax-cn" ||
 			model.provider === "minimax-code" ||
@@ -690,10 +701,16 @@ function inferAnthropicSupportedEfforts<TApi extends Api>(
 			// Converse lacks it (same split as Opus 4.7+ below).
 			return model.api === "anthropic-messages" ? DEFAULT_REASONING_EFFORTS_WITH_XHIGH : DEFAULT_REASONING_EFFORTS;
 		}
-		if (parsedModel.kind !== "opus") return DEFAULT_REASONING_EFFORTS;
-		return anthropicModelHasRealXHighEffort(model)
-			? DEFAULT_REASONING_EFFORTS_WITH_XHIGH_AND_MAX
-			: DEFAULT_REASONING_EFFORTS_WITH_MAX;
+		if (anthropicModelHasRealXHighEffort(model)) {
+			// Opus 4.7+ and Sonnet 5 expose both Anthropic's real xhigh and
+			// max presets on the Messages API.
+			return DEFAULT_REASONING_EFFORTS_WITH_XHIGH_AND_MAX;
+		}
+		if (parsedModel.kind === "opus") {
+			// Opus 4.6 exposes max but not the newer xhigh literal.
+			return DEFAULT_REASONING_EFFORTS_WITH_MAX;
+		}
+		return DEFAULT_REASONING_EFFORTS;
 	}
 	return inferFallbackEfforts(model);
 }

package/src/models.json

@@ -89,8 +89,8 @@
 				"maxLevel": "xhigh"
 			}
 		},
-		"qwen-3.8-max": {
-			"id": "qwen-3.8-max",
+		"qwen3.8-max": {
+			"id": "qwen3.8-max",
 			"name": "Qwen3.8 Max",
 			"api": "openai-responses",
 			"provider": "alibaba-token-plan",
@@ -3952,7 +3952,7 @@
 			"thinking": {
 				"mode": "anthropic-adaptive",
 				"minLevel": "minimal",
-				"maxLevel": "high"
+				"maxLevel": "max"
 			}
 		},
 		"claude-opus-5": {
@@ -4740,7 +4740,7 @@
 			"thinking": {
 				"mode": "anthropic-adaptive",
 				"minLevel": "minimal",
-				"maxLevel": "high"
+				"maxLevel": "max"
 			}
 		},
 		"claude-sonnet-4-5": {
@@ -9866,7 +9866,7 @@
 			"thinking": {
 				"mode": "anthropic-adaptive",
 				"minLevel": "minimal",
-				"maxLevel": "high"
+				"maxLevel": "max"
 			}
 		},
 		"gemini-2.5-pro": {
@@ -40201,8 +40201,8 @@
 				"maxLevel": "xhigh"
 			}
 		},
-		"minimax-m3": {
-			"id": "minimax-m3",
+		"MiniMax-M3": {
+			"id": "MiniMax-M3",
 			"name": "MiniMax-M3",
 			"api": "anthropic-messages",
 			"provider": "minimax",
@@ -40213,12 +40213,12 @@
 				"image"
 			],
 			"cost": {
-				"input": 0.6,
-				"output": 2.4,
-				"cacheRead": 0.12,
+				"input": 0.3,
+				"output": 1.2,
+				"cacheRead": 0.06,
 				"cacheWrite": 0
 			},
-			"contextWindow": 512000,
+			"contextWindow": 1000000,
 			"maxTokens": 128000,
 			"thinking": {
 				"mode": "budget",
@@ -40226,9 +40226,9 @@
 				"maxLevel": "xhigh"
 			}
 		},
-		"MiniMax-M3": {
-			"id": "MiniMax-M3",
-			"name": "MiniMax-M3",
+		"MiniMax-M3[1m]": {
+			"id": "MiniMax-M3[1m]",
+			"name": "MiniMax-M3[1m]",
 			"api": "anthropic-messages",
 			"provider": "minimax",
 			"baseUrl": "https://api.minimax.io/anthropic",
@@ -40421,8 +40421,8 @@
 				"maxLevel": "xhigh"
 			}
 		},
-		"minimax-m3": {
-			"id": "minimax-m3",
+		"MiniMax-M3": {
+			"id": "MiniMax-M3",
 			"name": "MiniMax-M3",
 			"api": "anthropic-messages",
 			"provider": "minimax-cn",
@@ -40433,12 +40433,12 @@
 				"image"
 			],
 			"cost": {
-				"input": 0.6,
-				"output": 2.4,
-				"cacheRead": 0.12,
+				"input": 0.3,
+				"output": 1.2,
+				"cacheRead": 0.06,
 				"cacheWrite": 0
 			},
-			"contextWindow": 512000,
+			"contextWindow": 1000000,
 			"maxTokens": 128000,
 			"thinking": {
 				"mode": "budget",
@@ -40446,9 +40446,9 @@
 				"maxLevel": "xhigh"
 			}
 		},
-		"MiniMax-M3": {
-			"id": "MiniMax-M3",
-			"name": "MiniMax-M3",
+		"MiniMax-M3[1m]": {
+			"id": "MiniMax-M3[1m]",
+			"name": "MiniMax-M3[1m]",
 			"api": "anthropic-messages",
 			"provider": "minimax-cn",
 			"baseUrl": "https://api.minimaxi.com/anthropic",
@@ -40713,37 +40713,6 @@
 				"maxLevel": "high"
 			}
 		},
-		"minimax-m3": {
-			"id": "minimax-m3",
-			"name": "MiniMax-M3",
-			"api": "openai-completions",
-			"provider": "minimax-code",
-			"baseUrl": "https://api.minimax.io/v1",
-			"reasoning": true,
-			"input": [
-				"text",
-				"image"
-			],
-			"cost": {
-				"input": 0,
-				"output": 0,
-				"cacheRead": 0,
-				"cacheWrite": 0
-			},
-			"contextWindow": 512000,
-			"maxTokens": 128000,
-			"compat": {
-				"supportsStore": false,
-				"supportsDeveloperRole": false,
-				"supportsReasoningEffort": false,
-				"reasoningContentField": "reasoning_content"
-			},
-			"thinking": {
-				"mode": "effort",
-				"minLevel": "minimal",
-				"maxLevel": "high"
-			}
-		},
 		"MiniMax-M3": {
 			"id": "MiniMax-M3",
 			"name": "MiniMax-M3",
@@ -40774,37 +40743,6 @@
 				"minLevel": "minimal",
 				"maxLevel": "high"
 			}
-		},
-		"minimax-v3": {
-			"id": "minimax-v3",
-			"name": "MiniMax-V3",
-			"api": "openai-completions",
-			"provider": "minimax-code",
-			"baseUrl": "https://api.minimax.io/v1",
-			"reasoning": true,
-			"input": [
-				"text",
-				"image"
-			],
-			"cost": {
-				"input": 0,
-				"output": 0,
-				"cacheRead": 0,
-				"cacheWrite": 0
-			},
-			"contextWindow": 512000,
-			"maxTokens": 128000,
-			"compat": {
-				"supportsStore": false,
-				"supportsDeveloperRole": false,
-				"supportsReasoningEffort": false,
-				"reasoningContentField": "reasoning_content"
-			},
-			"thinking": {
-				"mode": "effort",
-				"minLevel": "minimal",
-				"maxLevel": "high"
-			}
 		}
 	},
 	"minimax-code-cn": {
@@ -41048,37 +40986,6 @@
 				"maxLevel": "high"
 			}
 		},
-		"minimax-m3": {
-			"id": "minimax-m3",
-			"name": "MiniMax-M3",
-			"api": "openai-completions",
-			"provider": "minimax-code-cn",
-			"baseUrl": "https://api.minimaxi.com/v1",
-			"reasoning": true,
-			"input": [
-				"text",
-				"image"
-			],
-			"cost": {
-				"input": 0,
-				"output": 0,
-				"cacheRead": 0,
-				"cacheWrite": 0
-			},
-			"contextWindow": 512000,
-			"maxTokens": 128000,
-			"compat": {
-				"supportsStore": false,
-				"supportsDeveloperRole": false,
-				"supportsReasoningEffort": false,
-				"reasoningContentField": "reasoning_content"
-			},
-			"thinking": {
-				"mode": "effort",
-				"minLevel": "minimal",
-				"maxLevel": "high"
-			}
-		},
 		"MiniMax-M3": {
 			"id": "MiniMax-M3",
 			"name": "MiniMax-M3",
@@ -60445,7 +60352,7 @@
 			"thinking": {
 				"mode": "anthropic-adaptive",
 				"minLevel": "minimal",
-				"maxLevel": "high"
+				"maxLevel": "max"
 			}
 		},
 		"deepseek-v4-flash": {
@@ -75442,7 +75349,7 @@
 			"thinking": {
 				"mode": "anthropic-adaptive",
 				"minLevel": "minimal",
-				"maxLevel": "high"
+				"maxLevel": "max"
 			}
 		},
 		"arcee-ai/trinity-large-preview": {
@@ -81719,7 +81626,7 @@
 			"thinking": {
 				"mode": "anthropic-adaptive",
 				"minLevel": "minimal",
-				"maxLevel": "high"
+				"maxLevel": "max"
 			}
 		},
 		"anthropic/claude-sonnet-5-free": {
@@ -81744,7 +81651,7 @@
 			"thinking": {
 				"mode": "anthropic-adaptive",
 				"minLevel": "minimal",
-				"maxLevel": "high"
+				"maxLevel": "max"
 			}
 		},
 		"baidu/ernie-5.0-thinking-preview": {

package/src/provider-models/descriptors.ts

@@ -365,9 +365,9 @@ export const DEFAULT_MODEL_PER_PROVIDER: Record<KnownProvider, string> = {
 	"google-antigravity": "gemini-3-pro-high",
 	"google-gemini-cli": "gemini-2.5-pro",
 	"google-vertex": "gemini-3-pro-preview",
-	minimax: "minimax-m3",
-	"minimax-code": "minimax-m3",
-	"minimax-code-cn": "minimax-m3",
+	minimax: "MiniMax-M3",
+	"minimax-code": "MiniMax-M3",
+	"minimax-code-cn": "MiniMax-M3",
 	"openai-codex": "gpt-5.5",
 	"gitlab-duo": "duo-chat-sonnet-4-5",
 } as Record<KnownProvider, string>;

package/src/providers/anthropic.ts

@@ -395,8 +395,20 @@ export function isAnthropicFastModeUnsupportedError(error: unknown): boolean {
 	return false;
 }
 
+/**
+ * Proxies (e.g. CLIProxyAPI) can deliver Anthropic's 400 body as an in-stream
+ * SSE `error` event on an HTTP 200 response; the thrown error then carries no
+ * HTTP status at all (issue #3900). Accept both the direct 400 and the
+ * statusless SSE shape — the strict `invalid_request_error` message checks in
+ * each matcher keep the statusless branch from claiming unrelated failures.
+ */
+function isAnthropicInvalidRequestStatus(error: unknown): boolean {
+	const status = extractHttpStatusFromError(error);
+	return status === 400 || status === undefined;
+}
+
 export function isAnthropicThinkingBlockMutationError(error: unknown): boolean {
-	if (extractHttpStatusFromError(error) !== 400) return false;
+	if (!isAnthropicInvalidRequestStatus(error)) return false;
 	const message = error instanceof Error ? error.message : String(error);
 	return (
 		/invalid_request_error/i.test(message) &&
@@ -414,7 +426,7 @@ export function isAnthropicThinkingBlockMutationError(error: unknown): boolean {
  * than only the latest one.
  */
 export function isAnthropicThinkingSignatureInvalidError(error: unknown): boolean {
-	if (extractHttpStatusFromError(error) !== 400) return false;
+	if (!isAnthropicInvalidRequestStatus(error)) return false;
 	const message = error instanceof Error ? error.message : String(error);
 	return (
 		/invalid_request_error/i.test(message) &&
@@ -423,6 +435,27 @@ export function isAnthropicThinkingSignatureInvalidError(error: unknown): boolea
 	);
 }
 
+/**
+ * CLIProxyAPI replaces Anthropic's rejection body wholesale instead of forwarding
+ * it: the client only ever sees
+ * `{"type":"error","error":{"type":"api_error","message":"An error occurred while
+ * processing the request."}}`, delivered as an in-stream SSE `error` event on an
+ * HTTP 200 response, so neither the status nor the message survives. Captured CPA
+ * traces for that masked shape carry the thinking-integrity 400 upstream (issue
+ * #3900), and the generic body matches no transient phrase either, so the turn
+ * dies unrecoverably. Nothing in the payload names the cause; callers must pair
+ * this with a request that actually replays signed thinking blocks before
+ * treating it as a thinking-replay rejection.
+ */
+export function isAnthropicMaskedProxyRejection(error: unknown): boolean {
+	const status = extractHttpStatusFromError(error);
+	if (status !== undefined && status !== 400) return false;
+	const message = error instanceof Error ? error.message : String(error);
+	// A body that still names its error type is classified by the strict matchers.
+	if (/invalid_request_error/i.test(message)) return false;
+	return /"type"\s*:\s*"api_error"/.test(message) && /an error occurred while processing/i.test(message);
+}
+
 function hasStrictAnthropicTools(params: MessageCreateParamsStreaming): boolean {
 	const tools = params.tools as Array<{ strict?: unknown }> | undefined;
 	return tools?.some(tool => tool.strict === true) ?? false;
@@ -447,12 +480,21 @@ function dropAnthropicStrictTools(params: MessageCreateParamsStreaming): void {
 	}
 }
 
+function isClaudeFamilyModel(model: Model<"anthropic-messages">): boolean {
+	// Classify the same identifier the request body serializes (`params.model =
+	// model.id` in buildParams); a differing `wireModelId` is not dispatched by
+	// this transport, so it must not drive the cache decision either.
+	const id = model.id;
+	const shortId = id.includes("/") ? id.slice(id.lastIndexOf("/") + 1) : id;
+	return shortId.toLowerCase().startsWith("claude-");
+}
+
 function getCacheControl(
 	model: Model<"anthropic-messages">,
 	baseUrl: string,
 	cacheRetention?: CacheRetention,
 ): { mode: AnthropicCacheMode; cacheControl?: AnthropicCacheControl } {
-	const retention = resolveCacheRetention(cacheRetention, "long");
+	const retention = resolveCacheRetention(cacheRetention ?? model.cacheRetention, "long");
 	if (retention === "none") return { mode: "none" };
 
 	const isCanonicalApi = isAnthropicApiBaseUrl(baseUrl);
@@ -462,7 +504,7 @@ function getCacheControl(
 			? "none"
 			: promptCacheMode === "explicit"
 				? "explicit"
-				: isCanonicalApi
+				: promptCacheMode === "automatic" || isCanonicalApi || isClaudeFamilyModel(model)
 					? "automatic"
 					: "none";
 	if (mode === "none") return { mode };
@@ -1847,7 +1889,12 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 						!options?.fallbackManaged &&
 						!repairAllAssistantThinking &&
 						firstTokenTime === undefined &&
-						(thinkingSignatureInvalid || isAnthropicThinkingBlockMutationError(streamFailure))
+						(thinkingSignatureInvalid ||
+							isAnthropicThinkingBlockMutationError(streamFailure) ||
+							// Masked proxy rejection: unclassifiable on its own, so the replayed
+							// request shape is the evidence. Without signed thinking blocks in
+							// flight there is nothing to repair and the error must surface.
+							(isAnthropicMaskedProxyRejection(streamFailure) && hasNativeThinkingBlocks(params.messages)))
 					) {
 						// The mutation 400 blames the "latest assistant message", but its cited
 						// `messages.N.content.M` path can point at an EARLIER replayed turn, so the
@@ -2285,10 +2332,11 @@ function applyExplicitPromptCaching(params: AnthropicCacheParams, cacheControl:
 	const currentUser = params.messages[currentUserIndex];
 	if (!currentUser) return;
 
-	// A tool result is encoded as role "user" on the wire, but belongs to the
-	// preceding assistant turn. Anchor that assistant turn, not the tool result,
-	// so changing tool output does not invalidate the reusable conversation prefix.
-	for (let index = currentUserIndex - 1; index >= 0; index--) {
+	// Tool results are encoded as role "user" on the wire but belong to the
+	// assistant tool-use turn immediately before them. Anchor the latest completed
+	// assistant turn so the reusable prefix advances during an agent tool loop,
+	// while keeping the newest tool output outside the cache boundary.
+	for (let index = params.messages.length - 1; index >= 0; index--) {
 		const message = params.messages[index];
 		if (message?.role !== "assistant" || !Array.isArray(message.content)) continue;
 		if (

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

@@ -66,6 +66,7 @@ import {
 	toolWireSchema,
 } from "../utils/schema";
 import {
+	isCodexStatuslessNamedToolChoiceNotFoundError,
 	isForcedToolChoiceUnsupportedError,
 	markToolChoiceIncapability,
 	resolveToolChoice,
@@ -247,9 +248,7 @@ async function retryCodexInitialTransportWithoutToolChoice(
 	requestBodyForState: RequestBody;
 	transport: CodexTransport;
 }> {
-	if (
-		!isForcedToolChoiceUnsupportedError(error, isForcedCodexToolChoice(requestContext.transformedBody.tool_choice))
-	) {
+	if (!isCodexForcedToolChoiceUnsupportedError(error, requestContext.transformedBody)) {
 		throw error;
 	}
 	const reason = await finalizeErrorMessage(error, requestContext.rawRequestDump);
@@ -1527,7 +1526,7 @@ async function tryRetryWithoutForcedToolChoice(
 		context.output.content.length > 0 ||
 		context.firstTokenTime !== undefined ||
 		context.options?.signal?.aborted ||
-		!isForcedToolChoiceUnsupportedError(error, isForcedCodexToolChoice(runtime.requestBodyForState.tool_choice))
+		!isCodexForcedToolChoiceUnsupportedError(error, runtime.requestBodyForState)
 	) {
 		return false;
 	}
@@ -1579,6 +1578,30 @@ async function tryRetryWithoutForcedToolChoice(
 function isForcedCodexToolChoice(choice: RequestBody["tool_choice"]): boolean {
 	return !!choice && choice !== "none" && choice !== "auto";
 }
+function isCodexForcedToolChoiceUnsupportedError(error: unknown, body: RequestBody): boolean {
+	if (isForcedToolChoiceUnsupportedError(error, isForcedCodexToolChoice(body.tool_choice))) {
+		return true;
+	}
+	return isCodexStatuslessNamedToolChoiceNotFoundError(
+		error,
+		codexNamedFunctionToolChoiceName(body.tool_choice),
+		codexSerializedToolNames(body.tools),
+	);
+}
+
+function codexNamedFunctionToolChoiceName(choice: RequestBody["tool_choice"]): string | undefined {
+	if (!choice || typeof choice !== "object") return undefined;
+	const namedChoice = choice as { type?: unknown; name?: unknown };
+	return namedChoice.type === "function" && typeof namedChoice.name === "string" ? namedChoice.name : undefined;
+}
+
+function codexSerializedToolNames(tools: RequestBody["tools"]): string[] {
+	if (!Array.isArray(tools)) return [];
+	return tools.flatMap(tool => {
+		const name = (tool as { name?: unknown }).name;
+		return typeof name === "string" ? [name] : [];
+	});
+}
 
 /**
  * Handles `websocket_connection_limit_reached` errors by closing the stale connection

package/src/types.ts

@@ -743,7 +743,11 @@ export type Static<S> = S extends ZodType ? z.infer<S> : S extends { static: inf
 export type RawArgumentRejectionCode =
 	| "ask-intent-review-requires-positive-round"
 	| "ask-intent-contract-requires-non-empty-authority"
-	| "ask-deep-interview-metadata-requires-deep-interview-gate";
+	| "ask-deep-interview-metadata-requires-deep-interview-gate"
+	| "todo-write-unknown-root-key"
+	| "todo-write-unknown-op-entry-key"
+	| "todo-write-done-drop-requires-target"
+	| "todo-write-unknown-init-entry-key";
 
 export type RawArgumentValidationResult =
 	| { outcome: "passthrough" }
@@ -947,8 +951,10 @@ export interface AnthropicCompat extends ToolChoiceCompat {
 	supportsLongCacheRetention?: boolean;
 	/**
 	 * Prompt-cache transport accepted by this Anthropic-compatible endpoint.
-	 * Canonical Anthropic defaults to `"automatic"`; noncanonical endpoints default
-	 * to `"none"` and must explicitly opt into generated `"explicit"` markers.
+	 * Canonical Anthropic and Claude-family models default to `"automatic"`;
+	 * noncanonical non-Claude endpoints default to `"none"`. Set `"automatic"` to
+	 * opt an otherwise unknown compatible endpoint into top-level caching, `"none"`
+	 * to opt out, or `"explicit"` for endpoints that require block-level markers.
 	 */
 	promptCacheMode?: "none" | "explicit" | "automatic";
 }

package/src/utils/tool-choice-capability.ts

@@ -165,7 +165,10 @@ export function resolveToolChoice(
 
 /** Detects provider errors indicating forced tool_choice is unsupported. */
 export function isForcedToolChoiceUnsupportedError(error: unknown, sentForcedToolChoice: boolean): boolean {
-	if (!sentForcedToolChoice || extractHttpStatusFromError(error) !== 400) return false;
+	const status = extractHttpStatusFromError(error);
+	if (!sentForcedToolChoice || status !== 400) {
+		return false;
+	}
 	const message = errorMessage(error);
 	return (
 		// `by <something>` continuations ("not supported by billing") describe a
@@ -179,6 +182,35 @@ export function isForcedToolChoiceUnsupportedError(error: unknown, sentForcedToo
 		/tool[_\s-]?choices?\s+['"`][^'"`\r\n]+['"`]\s+not\s+found\s+in\s+['"`]tools['"`]\s+parameter\b/is.test(message)
 	);
 }
+/**
+ * Detects Codex's statusless SSE rejection for a named function tool choice.
+ * This is intentionally separate from the shared HTTP-400 classifier.
+ */
+export function isCodexStatuslessNamedToolChoiceNotFoundError(
+	error: unknown,
+	forcedToolName: string | undefined,
+	sentToolNames: readonly string[],
+): boolean {
+	if (
+		extractHttpStatusFromError(error) !== undefined ||
+		extractProviderErrorCode(error) !== "invalid_request_error" ||
+		!forcedToolName
+	) {
+		return false;
+	}
+	const match =
+		/^Tool choice '([^']+)' not found in 'tools' parameter\.$/.exec(errorMessage(error)) ??
+		/^Codex error event: Tool choice '([^']+)' not found in 'tools' parameter\. \(code=invalid_request_error\)$/.exec(
+			errorMessage(error),
+		);
+	return match?.[1] === forcedToolName && sentToolNames.includes(forcedToolName);
+}
+
+function extractProviderErrorCode(error: unknown): string | undefined {
+	if (!error || typeof error !== "object") return undefined;
+	const code = (error as { code?: unknown }).code;
+	return typeof code === "string" ? code : undefined;
+}
 
 export type { ToolChoiceCompat, ToolChoiceSupport, ToolChoiceSupportSource } from "../types";
 

package/src/utils/validation.ts

@@ -965,6 +965,11 @@ const RAW_ARGUMENT_REJECTION_MESSAGES: Record<RawArgumentRejectionCode, string>
 		"deepInterview.intent_contract requires non-empty items and confirmation_options",
 	"ask-deep-interview-metadata-requires-deep-interview-gate":
 		"deepInterview metadata cannot be combined with a non-deep-interview workflowGate",
+	"todo-write-unknown-root-key": "todo_write root accepts only an ops array of operation entries",
+	"todo-write-unknown-op-entry-key":
+		"todo_write operation entries accept only op, list, task, phase, items, and text keys",
+	"todo-write-done-drop-requires-target": "todo_write done and drop entries require a task or phase target",
+	"todo-write-unknown-init-entry-key": "todo_write init list entries accept only phase and items keys",
 };
 
 /**