@gajae-code/ai 0.12.19 → 0.12.20

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.12.20] - 2026-08-09
+
+### Fixed
+
+- OpenAI Responses transports no longer send tool declarations whose names the provider reserves for its own built-ins. OpenCode Zen/Go reject `web_search` as a custom function with `invalid tools in request: custom function name "web_search" is reserved`, and that rejection is request-scoped — one colliding declaration failed the entire tools array before any token streamed, so the bundled `critic`, `planner`, and `architect` agents failed 100% of the time on those providers (#4104). The collision is dropped rather than renamed, because a renamed function tool returns as a `function_call` under the wire alias and that path does not populate `Tool.customWireName`, which would leave the agent-loop dispatcher unable to route the call. `compat.reservedToolNames` overrides the per-provider default.
+
 ## [0.12.19] - 2026-08-08
 
 ## [0.12.18] - 2026-08-08
@@ -21,6 +27,7 @@
 ### Fixed
 
 - Codex named-tool fallback now keeps its downgraded request body across later same-turn provider retries and uses an independent one-shot budget, so retries cannot reintroduce `tool_choice` or suppress a later capability downgrade (#3669).
+- `google-generative-ai` and `google-vertex` generate-content streams now consume newline-delimited JSON responses when the response media type declares NDJSON or JSONL, while preserving standard event-stream parsing and diagnostics.
 - Anthropic requests rejected with `A maximum of 4 blocks with cache_control may be provided. Found N.` now step their generated breakpoints down instead of dying on the first attempt (#3934, supersedes #3943). An Anthropic-compatible gateway may attach its own block-level cache markers before forwarding, and those never appear in the params we serialize, so the total is unpredictable locally and the rejection itself is the only usable signal. Because that rejection says "too many", not "none allowed", recovery gives up one breakpoint at a time: explicit mode normally emits two (a conversation-prefix anchor plus a current-turn refresh point), so the first retry keeps the prefix anchor — the higher-value marker — and only a second rejection disables generated caching entirely. The reduced budget persists for the provider session so later turns neither re-trigger the 400 nor lose more caching than the endpoint requires. Only a genuine breakpoint-overflow `invalid_request_error` is claimed — other `cache_control` complaints, unrelated 400s, non-400 statuses, and our own pre-flight validation failure still surface immediately. The classifier is exported as `isAnthropicCacheBreakpointOverflowError`.
 ## [0.12.15] - 2026-08-06
 

package/dist/types/openai-completions-compat.d.ts

@@ -1,6 +1,6 @@
 import type { Model, OpenAICompat } from "./types";
 type ResolvedToolStrictMode = NonNullable<OpenAICompat["toolStrictMode"]> | "mixed";
-export type ResolvedOpenAICompat = Required<Omit<OpenAICompat, "openRouterRouting" | "vercelGatewayRouting" | "extraBody" | "toolStrictMode" | "toolChoiceSupport" | "supportsResponsesSessionAffinity">> & {
+export type ResolvedOpenAICompat = Required<Omit<OpenAICompat, "openRouterRouting" | "vercelGatewayRouting" | "extraBody" | "toolStrictMode" | "toolChoiceSupport" | "supportsResponsesSessionAffinity" | "reservedToolNames">> & {
     openRouterRouting?: OpenAICompat["openRouterRouting"];
     vercelGatewayRouting?: OpenAICompat["vercelGatewayRouting"];
     extraBody?: OpenAICompat["extraBody"];

package/dist/types/providers/openai-responses.d.ts

@@ -31,4 +31,6 @@ export declare function supportsFreeformApplyPatch(model: Model<"openai-response
 /** @internal Exported for tests. */
 export declare function mapOpenAIResponsesToolChoiceForTools(choice: ToolChoice | undefined, tools: Tool[], model: Model<"openai-responses">): OpenAIResponsesToolChoice;
 /** @internal Exported for tests. */
+export declare function resolveReservedToolNames(model: Model<"openai-responses">): readonly string[];
+/** @internal Exported for tests. */
 export declare function convertTools(tools: Tool[], strictMode: boolean, model: Model<"openai-responses">): OpenAITool[];

package/dist/types/types.d.ts

@@ -540,6 +540,22 @@ 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" | "todo-write-unknown-root-key" | "todo-write-unknown-op-entry-key" | "todo-write-done-drop-requires-target" | "todo-write-unknown-init-entry-key";
+/**
+ * Optional structured detail attached to a raw-argument rejection. The fixed
+ * per-code guidance in `RAW_ARGUMENT_REJECTION_MESSAGES` explains the shape;
+ * this names what the caller actually sent that was wrong, so a retry can
+ * differ from the failed call.
+ */
+export interface RawArgumentRejectionDetail {
+    /** Offending keys, in payload order. */
+    readonly rejectedKeys?: readonly string[];
+    /**
+     * Correction for a rejected key whose replacement is exact and
+     * unambiguous. Never populate this from fuzzy or edit-distance matching:
+     * a wrong suggestion costs more turns than no suggestion.
+     */
+    readonly hint?: string;
+}
 export type RawArgumentValidationResult = {
     outcome: "passthrough";
 } | {
@@ -548,6 +564,7 @@ export type RawArgumentValidationResult = {
 } | {
     outcome: "reject";
     code?: RawArgumentRejectionCode;
+    detail?: RawArgumentRejectionDetail;
 };
 export interface Tool<TParameters extends TSchema = TSchema> {
     name: string;
@@ -701,6 +718,27 @@ export interface OpenAICompat extends ToolChoiceCompat {
      * HTTPS origin automatically; known non-OpenAI providers remain excluded.
      */
     supportsResponsesSessionAffinity?: boolean;
+    /**
+     * Tool names the provider reserves for its own built-ins and refuses to
+     * accept as custom function declarations. A colliding tool is **dropped**
+     * from the declared tools array rather than renamed: a renamed function
+     * tool would come back as a `function_call` under the wire alias, and that
+     * path does not populate `Tool.customWireName`, leaving the agent-loop
+     * dispatcher unable to route it — trading a loud 400 for a silent
+     * unresolvable call. Dropping the declaration is intentionally a loss of
+     * capability, leaving the agent in the same state as any provider that
+     * simply has no such tool. The filter preserves declaration order and does
+     * not mutate the caller's array.
+     *
+     * Without this, one reserved name rejects the ENTIRE tools array with a
+     * single 400 and no tokens ever stream — every agent carrying that tool
+     * fails 100% of the time on that provider.
+     *
+     * Resolution precedence: an explicit array (including `[]`) on the model's
+     * `compat` replaces the built-in provider default, so `[]` opts a reserved
+     * provider out of the drop entirely.
+     */
+    reservedToolNames?: string[];
     /**
      * Whether the provider's chat-completions endpoint accepts multiple
      * leading `system`/`developer` messages. When false, ordered system

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/ai",
-	"version": "0.12.19",
+	"version": "0.12.20",
 	"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.19",
+		"@gajae-code/utils": "0.12.20",
 		"openai": "^6.36.0",
 		"partial-json": "^0.1.7",
 		"zod": "4.4.3"

package/src/openai-completions-compat.ts

@@ -12,6 +12,7 @@ export type ResolvedOpenAICompat = Required<
 		| "toolStrictMode"
 		| "toolChoiceSupport"
 		| "supportsResponsesSessionAffinity"
+		| "reservedToolNames"
 	>
 > & {
 	openRouterRouting?: OpenAICompat["openRouterRouting"];

package/src/providers/anthropic.ts

@@ -316,10 +316,33 @@ let warnedStopSequencesTrim = false;
 
 const ANTHROPIC_PROVIDER_SESSION_STATE_KEY = "anthropic-messages";
 
+/**
+ * Scope of a classified replayed-thinking repair currently applied to this
+ * session: `latest` drops native thinking from the newest assistant turn, `all`
+ * stops replaying native thinking entirely. Persisted across stream
+ * re-invocations so a repair that keeps being rejected is not re-attempted from
+ * scratch on every turn (issue #4011), and released again by the first stream
+ * that completes. Unclassifiable masked `api_error` repairs remain local to the
+ * current stream invocation because a transient masked failure must not degrade
+ * later turns.
+ */
+type AnthropicThinkingReplayRepairScope = "none" | "latest" | "all";
+
+/**
+ * Repairs are bounded independently of `PROVIDER_MAX_RETRIES` because they do
+ * not consume the provider retry budget: without their own ceiling an
+ * unacceptable request shape retries forever (issue #4011). The ceiling spans
+ * the session rather than a single stream, and only a completed stream re-arms
+ * it — an unacceptable shape never completes, so it can never buy more repairs.
+ */
+const ANTHROPIC_MAX_THINKING_REPAIRS = 2;
+
 type AnthropicProviderSessionState = ProviderSessionState & {
 	strictToolsDisabled: boolean;
 	fastModeDisabled: boolean;
 	generatedCacheBudget: GeneratedCacheBudget;
+	thinkingReplayRepairScope: AnthropicThinkingReplayRepairScope;
+	thinkingReplayRepairAttempts: number;
 };
 
 function createAnthropicProviderSessionState(): AnthropicProviderSessionState {
@@ -327,10 +350,14 @@ function createAnthropicProviderSessionState(): AnthropicProviderSessionState {
 		strictToolsDisabled: false,
 		fastModeDisabled: false,
 		generatedCacheBudget: 2,
+		thinkingReplayRepairScope: "none",
+		thinkingReplayRepairAttempts: 0,
 		close: () => {
 			state.strictToolsDisabled = false;
 			state.fastModeDisabled = false;
 			state.generatedCacheBudget = 2;
+			state.thinkingReplayRepairScope = "none";
+			state.thinkingReplayRepairAttempts = 0;
 		},
 	};
 	return state;
@@ -1449,8 +1476,9 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 			let strictFallbackErrorMessage: string | undefined;
 			let dropFastMode = providerSessionState?.fastModeDisabled ?? false;
 			let droppedForcedToolChoice = false;
-			let repairLatestAssistantThinking = false;
-			let repairAllAssistantThinking = false;
+			let thinkingReplayRepairScope: AnthropicThinkingReplayRepairScope =
+				providerSessionState?.thinkingReplayRepairScope ?? "none";
+			let thinkingReplayRepairAttempts = providerSessionState?.thinkingReplayRepairAttempts ?? 0;
 			let generatedCacheBudget: GeneratedCacheBudget = providerSessionState?.generatedCacheBudget ?? 2;
 			const prepareParams = async (): Promise<MessageCreateParamsStreaming> => {
 				// Degradation state is cumulative: every fallback rebuild must merge all
@@ -1465,7 +1493,10 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 					isOAuthToken,
 					options,
 					disableStrictTools,
-					{ repairLatestAssistantThinking, repairAllAssistantThinking },
+					{
+						repairLatestAssistantThinking: thinkingReplayRepairScope === "latest",
+						repairAllAssistantThinking: thinkingReplayRepairScope === "all",
+					},
 					generatedCacheBudget,
 				);
 				if (droppedForcedToolChoice) {
@@ -1878,6 +1909,16 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 					if (output.stopReason === "aborted" || output.stopReason === "error") {
 						throw new Error(output.errorMessage ?? "An unknown error occurred");
 					}
+					// The first stream that completes is the only evidence available that this
+					// session is not the #4011 loop, which never produced one. Release the
+					// repair escalation and the budget it consumed: the masked `api_error`
+					// branch above fires on an error nobody can classify, so keeping its
+					// guess would silently strip native thinking replay from every later
+					// turn of the session over what may have been one transient blip.
+					if (providerSessionState && (thinkingReplayRepairScope !== "none" || thinkingReplayRepairAttempts > 0)) {
+						providerSessionState.thinkingReplayRepairScope = "none";
+						providerSessionState.thinkingReplayRepairAttempts = 0;
+					}
 					break;
 				} catch (streamError) {
 					const localAbortReason = activeAbortTracker.getLocalAbortReason();
@@ -1932,31 +1973,47 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 						continue;
 					}
 					const thinkingSignatureInvalid = isAnthropicThinkingSignatureInvalidError(streamFailure);
+					const thinkingBlocksImmutable = isAnthropicThinkingBlockMutationError(streamFailure);
+					const maskedProxyRejection = isAnthropicMaskedProxyRejection(streamFailure);
 					if (
 						!options?.fallbackManaged &&
-						!repairAllAssistantThinking &&
+						thinkingReplayRepairScope !== "all" &&
+						thinkingReplayRepairAttempts < ANTHROPIC_MAX_THINKING_REPAIRS &&
 						firstTokenTime === undefined &&
 						(thinkingSignatureInvalid ||
-							isAnthropicThinkingBlockMutationError(streamFailure) ||
+							thinkingBlocksImmutable ||
 							// 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)))
+							(maskedProxyRejection && 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
-						// latest-only repair gets rejected identically. Escalate to the full-history
-						// repair instead of burning the single retry on one scope.
-						const escalateToAll: boolean = thinkingSignatureInvalid || repairLatestAssistantThinking;
+						// "cannot be modified" means the cited blocks must be replayed byte for
+						// byte, so editing that turn again can never converge — the only recovery
+						// is to stop replaying native thinking at all. The invalid-signature 400
+						// cites blocks anywhere in history and needs the same full-history scope.
+						// Only the unclassifiable masked rejection is worth probing latest-first.
+						const nextScope: AnthropicThinkingReplayRepairScope =
+							thinkingSignatureInvalid || thinkingBlocksImmutable || thinkingReplayRepairScope === "latest"
+								? "all"
+								: "latest";
+						thinkingReplayRepairAttempts++;
 						logger.debug("anthropic: repairing assistant thinking replay after provider rejection", {
 							model: model.id,
-							scope: escalateToAll ? "all" : "latest",
+							scope: nextScope,
+							attempt: thinkingReplayRepairAttempts,
 							error: streamFailure instanceof Error ? streamFailure.message : String(streamFailure),
 						});
-						repairLatestAssistantThinking = !escalateToAll;
-						repairAllAssistantThinking = escalateToAll;
+						thinkingReplayRepairScope = nextScope;
+						if (providerSessionState) {
+							providerSessionState.thinkingReplayRepairAttempts = thinkingReplayRepairAttempts;
+							if (!maskedProxyRejection) {
+								providerSessionState.thinkingReplayRepairScope = nextScope;
+							}
+						}
 						params = await prepareParams();
-						providerRetryAttempt = 0;
+						// The provider retry budget is deliberately NOT reset here: a repair that
+						// keeps being rejected must run out instead of renewing the budget it is
+						// supposed to consume (issue #4011).
 						resetOutputForRetry();
 						continue;
 					}

package/src/providers/google-shared.ts

@@ -2,7 +2,7 @@
  * Shared utilities for Google Generative AI and Google Cloud Code Assist providers.
  */
 
-import { extractHttpStatusFromError, readSseJson } from "@gajae-code/utils";
+import { extractHttpStatusFromError, readJsonl, readSseJson } from "@gajae-code/utils";
 import { calculateCost } from "../models";
 import type {
 	Api,
@@ -914,13 +914,36 @@ export function streamGoogleGenAI<T extends "google-generative-ai" | "google-ver
 				throw new Error("Google API returned an empty response body");
 			}
 
-			const googleStream = readSseJson<GenerateContentResponse>(response.body, options?.signal, event =>
-				options?.onSseEvent?.(
-					{ event: event.event, data: event.data, raw: [...event.raw] },
-					model,
-					options?.attemptScope,
-				),
-			);
+			const mediaType = (response.headers.get("content-type") ?? "").split(";", 1)[0]?.trim().toLowerCase() ?? "";
+			const isJsonLines =
+				mediaType === "application/x-ndjson" ||
+				mediaType === "application/ndjson" ||
+				mediaType === "application/jsonl" ||
+				mediaType === "application/x-jsonl";
+			const rawEventObserver = options?.onSseEvent;
+			const googleStream = isJsonLines
+				? readJsonl<GenerateContentResponse>(
+						response.body,
+						options?.signal,
+						rawEventObserver
+							? raw => {
+									if (raw.trim().length === 0) return;
+									rawEventObserver({ event: null, data: raw, raw: [raw] }, model, options?.attemptScope);
+								}
+							: undefined,
+					)
+				: readSseJson<GenerateContentResponse>(
+						response.body,
+						options?.signal,
+						rawEventObserver
+							? event =>
+									rawEventObserver(
+										{ event: event.event, data: event.data, raw: [...event.raw] },
+										model,
+										options?.attemptScope,
+									)
+							: undefined,
+					);
 
 			stream.push({ type: "start", partial: output });
 			await consumeGoogleStream({

package/src/providers/openai-responses.ts

@@ -860,10 +860,37 @@ function isForcedOpenAIResponsesToolChoice(choice: unknown): boolean {
 	return !!choice && choice !== "none" && choice !== "auto";
 }
 
+/**
+ * Tool names an OpenAI-compatible endpoint reserves for its own built-ins and
+ * refuses as custom function declarations.
+ *
+ * OpenCode Zen/Go reject `web_search` with
+ * `invalid tools in request: custom function name "web_search" is reserved`.
+ * The rejection is request-scoped: one colliding declaration fails the WHOLE
+ * tools array before any token streams, so every agent carrying that tool is
+ * permanently broken on the provider rather than losing a single capability.
+ *
+ * The collision is dropped rather than renamed. A renamed function tool would
+ * come back as a `function_call` under the wire alias, and that path does not
+ * populate `Tool.customWireName`, so the agent-loop dispatcher could not route
+ * it — trading a loud 400 for a silent unresolvable call. Dropping leaves the
+ * agent in the same state as any provider that simply has no web search.
+ */
+const PROVIDER_RESERVED_TOOL_NAMES: Record<string, readonly string[]> = {
+	"opencode-go": ["web_search"],
+	"opencode-zen": ["web_search"],
+};
+
+/** @internal Exported for tests. */
+export function resolveReservedToolNames(model: Model<"openai-responses">): readonly string[] {
+	return model.compat?.reservedToolNames ?? PROVIDER_RESERVED_TOOL_NAMES[model.provider] ?? [];
+}
 /** @internal Exported for tests. */
 export function convertTools(tools: Tool[], strictMode: boolean, model: Model<"openai-responses">): OpenAITool[] {
 	const allowFreeform = supportsFreeformApplyPatch(model);
-	const payloads = tools.map(tool => {
+	const reserved = resolveReservedToolNames(model);
+	const declarable = reserved.length === 0 ? tools : tools.filter(tool => !reserved.includes(tool.name));
+	const payloads = declarable.map(tool => {
 		if (allowFreeform && tool.customFormat) {
 			return {
 				type: "custom",

package/src/types.ts

@@ -759,10 +759,27 @@ export type RawArgumentRejectionCode =
 	| "todo-write-done-drop-requires-target"
 	| "todo-write-unknown-init-entry-key";
 
+/**
+ * Optional structured detail attached to a raw-argument rejection. The fixed
+ * per-code guidance in `RAW_ARGUMENT_REJECTION_MESSAGES` explains the shape;
+ * this names what the caller actually sent that was wrong, so a retry can
+ * differ from the failed call.
+ */
+export interface RawArgumentRejectionDetail {
+	/** Offending keys, in payload order. */
+	readonly rejectedKeys?: readonly string[];
+	/**
+	 * Correction for a rejected key whose replacement is exact and
+	 * unambiguous. Never populate this from fuzzy or edit-distance matching:
+	 * a wrong suggestion costs more turns than no suggestion.
+	 */
+	readonly hint?: string;
+}
+
 export type RawArgumentValidationResult =
 	| { outcome: "passthrough" }
 	| { outcome: "accept"; arguments: ToolCall["arguments"] }
-	| { outcome: "reject"; code?: RawArgumentRejectionCode };
+	| { outcome: "reject"; code?: RawArgumentRejectionCode; detail?: RawArgumentRejectionDetail };
 
 export interface Tool<TParameters extends TSchema = TSchema> {
 	name: string;
@@ -869,6 +886,27 @@ export interface OpenAICompat extends ToolChoiceCompat {
 	 * HTTPS origin automatically; known non-OpenAI providers remain excluded.
 	 */
 	supportsResponsesSessionAffinity?: boolean;
+	/**
+	 * Tool names the provider reserves for its own built-ins and refuses to
+	 * accept as custom function declarations. A colliding tool is **dropped**
+	 * from the declared tools array rather than renamed: a renamed function
+	 * tool would come back as a `function_call` under the wire alias, and that
+	 * path does not populate `Tool.customWireName`, leaving the agent-loop
+	 * dispatcher unable to route it — trading a loud 400 for a silent
+	 * unresolvable call. Dropping the declaration is intentionally a loss of
+	 * capability, leaving the agent in the same state as any provider that
+	 * simply has no such tool. The filter preserves declaration order and does
+	 * not mutate the caller's array.
+	 *
+	 * Without this, one reserved name rejects the ENTIRE tools array with a
+	 * single 400 and no tokens ever stream — every agent carrying that tool
+	 * fails 100% of the time on that provider.
+	 *
+	 * Resolution precedence: an explicit array (including `[]`) on the model's
+	 * `compat` replaces the built-in provider default, so `[]` opts a reserved
+	 * provider out of the drop entirely.
+	 */
+	reservedToolNames?: string[];
 	/**
 	 * Whether the provider's chat-completions endpoint accepts multiple
 	 * leading `system`/`developer` messages. When false, ordered system

package/src/utils/validation.ts

@@ -25,7 +25,7 @@
 import { structuredCloneJSON } from "@gajae-code/utils";
 import type { ZodType } from "zod/v4";
 import type { $ZodIssue as ZodIssue } from "zod/v4/core";
-import type { RawArgumentRejectionCode, Tool, ToolCall } from "../types";
+import type { RawArgumentRejectionCode, RawArgumentRejectionDetail, Tool, ToolCall } from "../types";
 import { upgradeJsonSchemaTo202012 } from "./schema/draft";
 import {
 	isJsonSchemaValueValid,
@@ -972,6 +972,33 @@ const RAW_ARGUMENT_REJECTION_MESSAGES: Record<RawArgumentRejectionCode, string>
 	"todo-write-unknown-init-entry-key": "todo_write init list entries accept only phase and items keys",
 };
 
+/** Bounds on model-supplied text echoed back into a rejection message. */
+const MAX_REJECTED_KEYS = 8;
+const MAX_REJECTED_KEY_LENGTH = 64;
+const MAX_REJECTION_HINT_LENGTH = 200;
+
+function clamp(value: string, limit: number): string {
+	return value.length > limit ? `${value.slice(0, limit)}…` : value;
+}
+
+/**
+ * Renders the offending keys (and an exact correction, when the rejecting
+ * contract supplied one) as a clause appended to the fixed per-code guidance.
+ * Returns undefined when there is nothing concrete to name.
+ */
+function formatRejectionDetail(detail: RawArgumentRejectionDetail): string | undefined {
+	const keys = Array.isArray(detail.rejectedKeys)
+		? detail.rejectedKeys.filter(key => typeof key === "string" && key.length > 0).slice(0, MAX_REJECTED_KEYS)
+		: [];
+	const hint = typeof detail.hint === "string" && detail.hint.length > 0 ? detail.hint : undefined;
+	if (keys.length === 0) return hint ? clamp(hint, MAX_REJECTION_HINT_LENGTH) : undefined;
+
+	const label = keys.length === 1 ? "rejected key" : "rejected keys";
+	const rendered = keys.map(key => `"${clamp(key, MAX_REJECTED_KEY_LENGTH)}"`).join(", ");
+	const suffix = hint ? ` (${clamp(hint, MAX_REJECTION_HINT_LENGTH)})` : "";
+	return `${label}: ${rendered}${suffix}`;
+}
+
 /**
  * Validates tool call arguments against the tool's schema (Zod or plain JSON
  * Schema). Applies LLM-quirk coercions (numeric strings, JSON-string
@@ -989,7 +1016,11 @@ export function validateToolArguments(tool: Tool, toolCall: ToolCall): ToolCall[
 			typeof code === "string" && Object.hasOwn(RAW_ARGUMENT_REJECTION_MESSAGES, code)
 				? RAW_ARGUMENT_REJECTION_MESSAGES[code as RawArgumentRejectionCode]
 				: undefined;
-		throw new Error(correction ? `${base}; ${correction}` : base);
+		if (!correction) throw new Error(base);
+		// Detail is only echoed alongside authority-controlled guidance, and only
+		// after clamping — the keys themselves come from the rejected payload.
+		const detail = rawValidation.detail ? formatRejectionDetail(rawValidation.detail) : undefined;
+		throw new Error(detail ? `${base}; ${correction}; ${detail}` : `${base}; ${correction}`);
 	}
 	const rawArgs = rawValidation?.outcome === "accept" ? rawValidation.arguments : originalArgs;
 	const ctx = getValidationContext(tool);