@gajae-code/agent-core 0.15.4 → 0.15.6

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+## [0.15.6] - 2026-08-30
+
+## [0.15.5] - 2026-08-29
+
 ## [0.15.4] - 2026-08-29
 
 ### Added
@@ -12,9 +16,10 @@
 
 ### Changed
 
-- Escaped non-ASCII tool-call arguments whose every `\uXXXX` escape corroborates a decoded non-ASCII character inside a tool's declared `displaySafeEscapedArgFields` now degrade to a single warning and execute the decoded call, instead of discarding the turn and charging the bounded resample/managed-fallback retry chain. Previously even purely cosmetic display text (e.g. an `ask` question written in Korean or with emoji) burned the full resample budget and then failed the run closed, which made the default Anthropic presets error out on a model-side encoding habit. Raw-evidence corroboration is now per-scalar (offset + process-keyed scalar tag against any decoded non-ASCII character in a declared display field) rather than restricted to U+2014, and literal non-ASCII display text alongside a corroborated escape no longer needs evidence. Load-bearing fields, ASCII-landing escapes, missing/malformed evidence, and non-display-safe tools keep the fail-closed discard-and-reject behavior. (#4983)
+- Current provider adapters no longer mark syntactically valid `\uXXXX` arguments as guarded: JSON parsing has already produced the canonical string, so valid escaped Hangul, emoji, ASCII, and other scalars execute like literal UTF-8 in every tool. The existing `displaySafeEscapedArgFields` path remains only for compatibility with legacy producers that still attach non-malformed positional evidence. Malformed evidence, unauthenticated managed evidence, incomplete/conflicting arguments, and unpaired surrogates remain fail-closed.
 ### Fixed
 
+- Managed fallback snapshots now convert unauthenticated Unicode evidence into `incompleteArgumentsReason: "malformed"` instead of preserving a boolean-only guard that could lose the evidence needed by terminal validation.
 - Compaction no longer crashes on a persisted tool call whose `arguments` payload is null. `serializeConversation` passed that value straight into `Object.entries`, which threw `TypeError: Object.entries requires that input parameter not be null or undefined`. Because this runs inside compaction — itself the recovery path for context overflow — the failure surfaced as `Context overflow recovery failed: Object.entries requires ...`, and the next request went out uncompacted until the provider rejected it with `prompt is too long`. Malformed argument payloads now serialize as an empty argument list instead of aborting the summary.
 
 ## [0.15.2] - 2026-08-25

package/dist/types/agent.d.ts

@@ -5,7 +5,7 @@ import { type AssistantMessage, type AssistantMessageEvent, type CursorExecHandl
 import type { AppendOnlyContextManager } from "./append-only-context";
 import type { AttemptRunHandle, AttemptScope } from "./attempt-scope";
 import type { HarmonyAuditEvent } from "./harmony-leak";
-import type { AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, AgentToolContext, ManagedLogicalRunId, RunCancellationDomainBridge, RunResourceLedger, RunTerminalRequest, StreamFn, ToolCallContext } from "./types";
+import type { AgentEvent, AgentLoopConfig, AgentMessage, AgentMetadataResolverContext, AgentState, AgentTool, AgentToolContext, ManagedLogicalRunId, RunCancellationDomainBridge, RunResourceLedger, RunTerminalRequest, StreamFn, ToolCallContext } from "./types";
 /**
  * Whether persisted history ends at a point where a new model turn can resume.
  * Assistant-ended histories require an in-memory queued message and are handled
@@ -271,7 +271,7 @@ export declare class Agent {
      * only included for `"anthropic"` requests). Falls back to the static
      * {@link metadata} value when no resolver is set.
      */
-    metadataForProvider(provider: string): Record<string, unknown> | undefined;
+    metadataForProvider(provider: string, model?: Model, transport?: AgentMetadataResolverContext["transport"]): Record<string, unknown> | undefined;
     /**
      * Install a function that resolves request metadata at call time. The
      * resolver receives the target provider string and can gate provider-specific
@@ -280,7 +280,7 @@ export declare class Agent {
      * credential. Pass `undefined` to clear and revert to the static
      * {@link metadata} value.
      */
-    setMetadataResolver(resolver: ((provider: string) => Record<string, unknown> | undefined) | undefined): void;
+    setMetadataResolver(resolver: ((context: AgentMetadataResolverContext) => Record<string, unknown> | undefined) | undefined): void;
     /**
      * Read the active OpenTelemetry configuration. Returns `undefined` when
      * instrumentation is disabled. Callers spawning child runs (e.g. subagent
@@ -358,6 +358,18 @@ export declare class Agent {
     setProvisionalAssistantMessageEventInterceptor(fn: ((message: AssistantMessage, event: AssistantMessageEvent) => void) | undefined): void;
     setOnBeforeYield(fn: (() => Promise<void> | void) | undefined): void;
     setShouldPause(fn: AgentLoopConfig["shouldPause"] | undefined): void;
+    /** The currently installed cooperative pause checkpoint, if any. */
+    get shouldPause(): AgentLoopConfig["shouldPause"] | undefined;
+    /**
+     * Fence old-turn steering admission.
+     *
+     * The loop polls steering UPSTREAM of its pause checkpoint (and again on the
+     * immediate-interrupt path), so a cooperative stop alone cannot prevent one
+     * more old-turn model call once a steering message has already been dequeued.
+     * While the fence returns true the poll yields no messages AND does not
+     * dequeue, so the queue survives intact for the next turn.
+     */
+    setSteeringAdmissionFence(fn: (() => boolean) | undefined): void;
     setMaintainContext(fn: AgentLoopConfig["maintainContext"] | undefined): void;
     /**
      * Publish an event produced OUTSIDE the agent loop (a provider that executed the tool

package/dist/types/types.d.ts

@@ -6,6 +6,20 @@ import type { AgentRunCoverage, AgentRunSummary } from "./run-collector";
 import type { AgentTelemetryConfig } from "./telemetry";
 /** Stream function - can return sync or Promise for async config lookup */
 export type StreamFn = (...args: Parameters<typeof streamSimple>) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>;
+/**
+ * Request context supplied to provider-aware metadata resolvers.
+ *
+ * The model is the exact model selected for the concrete request (including
+ * fallback and ephemeral requests), while `transport` distinguishes the
+ * built-in stream path from a caller-supplied stream function. Metadata that
+ * carries provider identity must use both values to fail closed when routing
+ * is not the canonical provider path.
+ */
+export interface AgentMetadataResolverContext {
+    provider: string;
+    model?: Model;
+    transport?: "default" | "custom";
+}
 /** Stable identifier for a managed logical run, shared by all of its retry attempts. */
 export type ManagedLogicalRunId = number;
 /** A resource owned by a prompt run until its promise settles. */
@@ -233,7 +247,7 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * current when `AgentLoopConfig` was first constructed). Overrides the static
      * `metadata` field when present.
      */
-    metadataResolver?: (provider: string) => Record<string, unknown> | undefined;
+    metadataResolver?: (context: AgentMetadataResolverContext) => Record<string, unknown> | undefined;
     /**
      * Converts AgentMessage[] to LLM-compatible Message[] before each LLM call.
      *

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/agent-core",
-	"version": "0.15.4",
+	"version": "0.15.6",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -32,9 +32,9 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/ai": "0.15.4",
-		"@gajae-code/natives": "0.15.4",
-		"@gajae-code/utils": "0.15.4",
+		"@gajae-code/ai": "0.15.6",
+		"@gajae-code/natives": "0.15.6",
+		"@gajae-code/utils": "0.15.6",
 		"@opentelemetry/api": "^1.9.0"
 	},
 	"devDependencies": {

package/src/agent-loop.ts

@@ -14,6 +14,7 @@ import {
 	EventStream,
 	isProviderSafetyStopAuthenticated,
 	isZodSchema,
+	SERVER_OVERLOADED_PROVIDER_CODE,
 	streamSimple,
 	type ToolChoice,
 	type ToolResultMessage,
@@ -403,12 +404,57 @@ export const ESCAPED_NONASCII_RECOVERY_PROMPT = escapedNonAsciiRecoveryPrompt;
 const MAX_ESCAPED_NONASCII_RESAMPLES = 2;
 
 /** Whether any tool call in the turn carried `\uXXXX`-escaped arguments. */
+interface EscapedToolCallMetadata {
+	guarded: boolean;
+	malformed: boolean;
+	evidence: UnicodeEscapeEvidence | undefined;
+	incompleteArguments: boolean;
+	incompleteArgumentsReason: unknown;
+}
+
+const acceptedToolCallMetadata = new WeakMap<object, EscapedToolCallMetadata>();
+
+function escapedToolCallMetadata(
+	block: Extract<AssistantMessage["content"][number], { type: "toolCall" }>,
+): EscapedToolCallMetadata {
+	const guardRead = managedOwnPropertyRead(block, "escapedNonAsciiArguments");
+	const evidenceRead = managedOwnPropertyRead(block, "escapedUnicodeArgumentEvidence");
+	const incompleteRead = managedPropertyRead(block, "incompleteArguments");
+	const incompleteReasonRead = managedPropertyRead(block, "incompleteArgumentsReason");
+	const inheritedGuard = managedInheritedProperty(block, "escapedNonAsciiArguments");
+	const inheritedEvidence = managedInheritedProperty(block, "escapedUnicodeArgumentEvidence");
+	let evidence: UnicodeEscapeEvidence | undefined;
+	try {
+		evidence = managedUnicodeEscapeEvidence(evidenceRead.value);
+	} catch {
+		evidence = undefined;
+	}
+	const malformedMetadata =
+		!guardRead.ok ||
+		!evidenceRead.ok ||
+		!incompleteRead.ok ||
+		!incompleteReasonRead.ok ||
+		inheritedGuard ||
+		inheritedEvidence ||
+		(typeof incompleteRead.value === "string" && SANITIZER_SENTINELS.has(incompleteRead.value)) ||
+		(typeof incompleteReasonRead.value === "string" && SANITIZER_SENTINELS.has(incompleteReasonRead.value)) ||
+		(evidenceRead.present && (evidenceRead.value === undefined || evidence === undefined || evidence.malformed));
+	const incomplete = incompleteRead.ok && incompleteRead.value === true;
+	return {
+		guarded:
+			malformedMetadata ||
+			(guardRead.present && guardRead.value === true) ||
+			(evidenceRead.present && evidenceRead.value !== undefined),
+		malformed: malformedMetadata || incomplete,
+		evidence,
+		incompleteArguments: incomplete,
+		incompleteArgumentsReason:
+			!incompleteReasonRead.ok || malformedMetadata ? "malformed" : incompleteReasonRead.value,
+	};
+}
+
 function hasEscapedNonAsciiToolCall(message: AssistantMessage): boolean {
-	return message.content.some(
-		block =>
-			block.type === "toolCall" &&
-			(block.escapedNonAsciiArguments === true || block.escapedUnicodeArgumentEvidence !== undefined),
-	);
+	return message.content.some(block => block.type === "toolCall" && escapedToolCallMetadata(block).guarded);
 }
 
 const ESCAPED_NONASCII_DIAGNOSTIC_TOOL_CALL_COUNT_MAX = 8;
@@ -419,9 +465,7 @@ function escapedNonAsciiToolCallShape(message: AssistantMessage): {
 	escapedToolCallCountCapped: boolean;
 } {
 	const count = message.content.filter(
-		block =>
-			block.type === "toolCall" &&
-			(block.escapedNonAsciiArguments === true || block.escapedUnicodeArgumentEvidence !== undefined),
+		block => block.type === "toolCall" && escapedToolCallMetadata(block).guarded,
 	).length;
 	return {
 		escapedToolCallCount: Math.min(count, ESCAPED_NONASCII_DIAGNOSTIC_TOOL_CALL_COUNT_MAX),
@@ -430,9 +474,53 @@ function escapedNonAsciiToolCallShape(message: AssistantMessage): {
 }
 
 /** Remove transient raw-evidence metadata before any message can become durable. */
+function stripToolCallEvidence<T extends { escapedUnicodeArgumentEvidence?: unknown }>(toolCall: T): T {
+	try {
+		if (nodeUtilTypes.isProxy(toolCall)) {
+			const sanitized = Object.create(null) as T;
+			for (const key of [
+				"type",
+				"id",
+				"name",
+				"arguments",
+				"thoughtSignature",
+				"intent",
+				"customWireName",
+				"escapedNonAsciiArguments",
+				"incompleteArguments",
+				"incompleteArgumentsReason",
+			]) {
+				const read = managedPropertyRead(toolCall, key);
+				if (read.ok && read.value !== undefined)
+					Object.defineProperty(sanitized, key, { value: read.value, enumerable: true });
+			}
+			return sanitized;
+		}
+		const descriptor = Object.getOwnPropertyDescriptor(toolCall, "escapedUnicodeArgumentEvidence");
+		if (!descriptor) return toolCall;
+		if (descriptor.configurable && Reflect.deleteProperty(toolCall, "escapedUnicodeArgumentEvidence"))
+			return toolCall;
+		const sanitized = Object.create(null) as T;
+		for (const key of Reflect.ownKeys(toolCall)) {
+			if (key === "escapedUnicodeArgumentEvidence") continue;
+			const own = Object.getOwnPropertyDescriptor(toolCall, key);
+			if (!own?.enumerable || !("value" in own)) continue;
+			try {
+				Object.defineProperty(sanitized, key, own);
+			} catch {
+				// Skip hostile descriptors; required fields are already captured in the record.
+			}
+		}
+		return sanitized;
+	} catch {
+		return Object.create(null) as T;
+	}
+}
+
 function stripUnicodeEscapeEvidence(message: AssistantMessage): void {
-	for (const block of message.content) {
-		if (block.type === "toolCall") delete block.escapedUnicodeArgumentEvidence;
+	for (let index = 0; index < message.content.length; index += 1) {
+		const block = message.content[index];
+		if (block?.type === "toolCall") message.content[index] = stripToolCallEvidence(block);
 	}
 }
 
@@ -606,14 +694,13 @@ function allEscapedToolCallsDisplaySafe(
 	let sawEscapedCall = false;
 	for (const block of message.content) {
 		if (block.type !== "toolCall") continue;
-		if (block.escapedNonAsciiArguments !== true && block.escapedUnicodeArgumentEvidence === undefined) continue;
+		const metadata = escapedToolCallMetadata(block);
+		if (!metadata.guarded) continue;
+		if (metadata.malformed) return false;
 		sawEscapedCall = true;
 		const tool = tools?.find(candidate => candidate.name === block.name);
 		const args = block.arguments as Record<string, unknown>;
-		if (
-			!isDisplaySafeEscapedArguments(tool, args) ||
-			!isDisplaySafeRawEscapeEvidence(tool, args, block.escapedUnicodeArgumentEvidence)
-		)
+		if (!isDisplaySafeEscapedArguments(tool, args) || !isDisplaySafeRawEscapeEvidence(tool, args, metadata.evidence))
 			return false;
 	}
 	return sawEscapedCall;
@@ -656,6 +743,25 @@ function managedProperty(value: unknown, key: string): unknown {
 	return managedPropertyRead(value, key).value;
 }
 
+function managedOwnPropertyRead(value: unknown, key: string): { present: boolean; ok: boolean; value: unknown } {
+	if (!value || typeof value !== "object") return { present: false, ok: true, value: undefined };
+	try {
+		if (!Object.hasOwn(value, key)) return { present: false, ok: true, value: undefined };
+		return { present: true, ok: true, value: Reflect.get(value, key) };
+	} catch {
+		return { present: true, ok: false, value: undefined };
+	}
+}
+
+function managedInheritedProperty(value: unknown, key: string): boolean {
+	if (!value || typeof value !== "object") return false;
+	try {
+		return !Object.hasOwn(value, key) && key in value;
+	} catch {
+		return true;
+	}
+}
+
 function managedTransportFailure(failure: unknown) {
 	const facts = managedProperty(failure, "transportFailure");
 	return facts && typeof facts === "object" ? transportFailureFacts(facts) : undefined;
@@ -678,6 +784,19 @@ function isManagedProviderSafetyStopAuthenticated(value: unknown): boolean {
 function managedRetryableFailure(failure: unknown): boolean {
 	const facts = managedTransportFailure(failure);
 	if (!facts) return false;
+	// OpenAI's typed statusless capacity-overload code (issue #5018) never
+	// becomes managed transaction authority. Before the code survived as
+	// transport facts this failure produced none, so the staged attempt was
+	// always committed; the shared Responses parser and Codex events now carry
+	// it, and this check preserves that committed-failure behavior instead of
+	// discarding the transaction. It reads only typed facts, never error text.
+	if (
+		facts.status === undefined &&
+		facts.providerCode === SERVER_OVERLOADED_PROVIDER_CODE &&
+		(facts.openaiErrorCode === undefined || facts.openaiErrorCode === SERVER_OVERLOADED_PROVIDER_CODE)
+	) {
+		return false;
+	}
 	// A typed provider safety stop is terminal evidence ahead of any transport
 	// class, but only with adapter-minted provenance: unauthenticated labels
 	// are stripped at the stream exit (`sanitizeProviderSafetyStopProvenance`)
@@ -748,6 +867,12 @@ function sanitizeProviderSafetyStopProvenance(
 	if (isManagedPlainRecord(detached)) {
 		const rebuilt = { ...detached } as AssistantMessage;
 		delete rebuilt.errorKind;
+		if (!Array.isArray(rebuilt.content)) {
+			const repaired = managedAssistantShell(message, model);
+			delete repaired.errorKind;
+			return repaired;
+		}
+		restoreTransientUnicodeEscapeEvidence(rebuilt.content, message);
 		return rebuilt;
 	}
 	const rebuilt = managedAssistantShell(message, model);
@@ -1947,7 +2072,11 @@ function managedAssistantShell(
 	//   `message.role === "assistant"` check passes while the detached
 	//   snapshot retains none of the message identity.
 	const source =
-		snapshotRecord !== undefined && managedProperty(snapshotRecord, "role") === "assistant" ? snapshotRecord : value;
+		snapshotRecord !== undefined &&
+		managedProperty(snapshotRecord, "role") === "assistant" &&
+		(managedProperty(snapshotRecord, "content") !== undefined || managedProperty(value, "content") === undefined)
+			? snapshotRecord
+			: value;
 	if (managedProperty(source, "role") !== "assistant") throw new ManagedAttemptSnapshotError("shell.role");
 	const rawContent = managedAttemptSnapshot(managedProperty(source, "content"));
 	// Providers may deliver `content` as a string, missing value, or a primitive
@@ -2048,11 +2177,18 @@ function managedContentBlock(block: unknown): AssistantMessage["content"] {
 
 function managedUnicodeEscapeEvidence(value: unknown): UnicodeEscapeEvidence | undefined {
 	if (!isManagedPlainRecord(value)) return undefined;
-	const positionsValue = managedProperty(value, "positions");
-	const totalPositions = managedProperty(value, "totalPositions");
-	const truncated = managedProperty(value, "truncated");
-	const malformed = managedProperty(value, "malformed");
-	const integrity = managedProperty(value, "integrity");
+	const envelopeReads = Object.fromEntries(
+		["positions", "totalPositions", "truncated", "malformed", "integrity"].map(key => [
+			key,
+			managedOwnPropertyRead(value, key),
+		]),
+	) as Record<string, { present: boolean; ok: boolean; value: unknown }>;
+	if (Object.values(envelopeReads).some(read => !read.present || !read.ok)) return undefined;
+	const positionsValue = envelopeReads.positions!.value;
+	const totalPositions = envelopeReads.totalPositions!.value;
+	const truncated = envelopeReads.truncated!.value;
+	const malformed = envelopeReads.malformed!.value;
+	const integrity = envelopeReads.integrity!.value;
 	if (!Array.isArray(positionsValue) || positionsValue.length > 32) return undefined;
 	if (
 		typeof totalPositions !== "number" ||
@@ -2067,12 +2203,19 @@ function managedUnicodeEscapeEvidence(value: unknown): UnicodeEscapeEvidence | u
 	const positions: UnicodeEscapeEvidence["positions"][number][] = [];
 	for (const positionValue of positionsValue) {
 		if (!isManagedPlainRecord(positionValue)) return undefined;
-		const offset = managedProperty(positionValue, "offset");
-		const scalarTag = managedProperty(positionValue, "scalarTag");
-		const pathTag = managedProperty(positionValue, "pathTag");
-		const location = managedProperty(positionValue, "location");
-		const valueOrdinal = managedProperty(positionValue, "valueOrdinal");
-		const valueOffset = managedProperty(positionValue, "valueOffset");
+		const positionReads = Object.fromEntries(
+			["offset", "scalarTag", "pathTag", "location", "valueOrdinal", "valueOffset"].map(key => [
+				key,
+				managedOwnPropertyRead(positionValue, key),
+			]),
+		) as Record<string, { present: boolean; ok: boolean; value: unknown }>;
+		if (Object.values(positionReads).some(read => !read.present || !read.ok)) return undefined;
+		const offset = positionReads.offset!.value;
+		const scalarTag = positionReads.scalarTag!.value;
+		const pathTag = positionReads.pathTag!.value;
+		const location = positionReads.location!.value;
+		const valueOrdinal = positionReads.valueOrdinal!.value;
+		const valueOffset = positionReads.valueOffset!.value;
 		if (
 			typeof offset !== "number" ||
 			!Number.isSafeInteger(offset) ||
@@ -2093,14 +2236,15 @@ function managedUnicodeEscapeEvidence(value: unknown): UnicodeEscapeEvidence | u
 		}
 		positions.push({ offset, scalarTag, pathTag, location, valueOrdinal, valueOffset });
 	}
-	return { positions, totalPositions, truncated, malformed, integrity };
+	const evidence = { positions, totalPositions, truncated, malformed, integrity };
+	return verifyUnicodeEscapeEvidence(evidence) ? evidence : undefined;
 }
 
 function restoreTransientUnicodeEscapeEvidence(content: AssistantMessage["content"], liveMessage: unknown): void {
 	const liveContent = managedProperty(liveMessage, "content");
 	if (!Array.isArray(liveContent)) return;
 	for (const destination of content) {
-		if (destination.type !== "toolCall") continue;
+		if (!destination || typeof destination !== "object" || destination.type !== "toolCall") continue;
 		const matches = liveContent.filter(
 			candidate =>
 				isManagedPlainRecord(candidate) &&
@@ -2108,12 +2252,52 @@ function restoreTransientUnicodeEscapeEvidence(content: AssistantMessage["conten
 				managedProperty(candidate, "id") === destination.id &&
 				managedProperty(candidate, "name") === destination.name,
 		);
-		if (matches.length !== 1) continue;
-		const rawEvidence = managedProperty(matches[0], "escapedUnicodeArgumentEvidence");
-		if (rawEvidence === undefined) continue;
-		const evidence = managedUnicodeEscapeEvidence(rawEvidence);
-		if (evidence) attachUnicodeEscapeEvidence(destination, evidence);
-		else destination.escapedNonAsciiArguments = true;
+		const evidenceReads = matches.map(candidate =>
+			managedOwnPropertyRead(candidate, "escapedUnicodeArgumentEvidence"),
+		);
+		const inheritedEvidence = matches.map(candidate =>
+			managedInheritedProperty(candidate, "escapedUnicodeArgumentEvidence"),
+		);
+		const guardReads = matches.map(candidate => managedOwnPropertyRead(candidate, "escapedNonAsciiArguments"));
+		const inheritedGuards = matches.map(candidate => managedInheritedProperty(candidate, "escapedNonAsciiArguments"));
+		if (matches.length !== 1) {
+			if (
+				evidenceReads.some(read => read.present) ||
+				inheritedEvidence.some(Boolean) ||
+				guardReads.some(read => read.present) ||
+				inheritedGuards.some(Boolean)
+			) {
+				destination.incompleteArguments = true;
+				destination.incompleteArgumentsReason = "malformed";
+			}
+			continue;
+		}
+		const guardRead = guardReads[0]!;
+		if (!guardRead.ok || inheritedGuards[0]) {
+			destination.incompleteArguments = true;
+			destination.incompleteArgumentsReason = "malformed";
+		}
+		if (guardRead.ok && guardRead.present && guardRead.value === true) destination.escapedNonAsciiArguments = true;
+		const evidenceRead = evidenceReads[0]!;
+		if (!evidenceRead.present || !evidenceRead.ok || evidenceRead.value === undefined || inheritedEvidence[0]) {
+			if (evidenceRead.present || inheritedEvidence[0]) {
+				destination.incompleteArguments = true;
+				destination.incompleteArgumentsReason = "malformed";
+			}
+			continue;
+		}
+		const rawEvidence = evidenceRead.value;
+		let evidence: UnicodeEscapeEvidence | undefined;
+		try {
+			evidence = managedUnicodeEscapeEvidence(rawEvidence);
+		} catch {
+			evidence = undefined;
+		}
+		if (evidence && !evidence.malformed) attachUnicodeEscapeEvidence(destination, evidence);
+		else {
+			destination.incompleteArguments = true;
+			destination.incompleteArgumentsReason = "malformed";
+		}
 	}
 }
 
@@ -2140,12 +2324,47 @@ function managedAssistantContent(value: unknown): AssistantMessage["content"][nu
 	const thoughtSignature = managedProperty(value, "thoughtSignature");
 	const intent = managedProperty(value, "intent");
 	const customWireName = managedProperty(value, "customWireName");
-	const incompleteArguments = managedProperty(value, "incompleteArguments");
-	const incompleteArgumentsReason = managedProperty(value, "incompleteArgumentsReason");
-	const escapedNonAsciiArguments = managedProperty(value, "escapedNonAsciiArguments");
-	const rawEscapedUnicodeArgumentEvidence = managedProperty(value, "escapedUnicodeArgumentEvidence");
-	const escapedUnicodeArgumentEvidence = managedUnicodeEscapeEvidence(rawEscapedUnicodeArgumentEvidence);
-	const escapedArgumentsGuarded = escapedNonAsciiArguments === true || rawEscapedUnicodeArgumentEvidence !== undefined;
+	const incompleteArgumentsRead = managedPropertyRead(value, "incompleteArguments");
+	const incompleteArgumentsReasonRead = managedPropertyRead(value, "incompleteArgumentsReason");
+	const escapedGuardRead = managedOwnPropertyRead(value, "escapedNonAsciiArguments");
+	const evidenceRead = managedOwnPropertyRead(value, "escapedUnicodeArgumentEvidence");
+	const inheritedGuard = managedInheritedProperty(value, "escapedNonAsciiArguments");
+	const inheritedEvidence = managedInheritedProperty(value, "escapedUnicodeArgumentEvidence");
+	const inheritedIncompleteArguments = managedInheritedProperty(value, "incompleteArguments");
+	const inheritedIncompleteArgumentsReason = managedInheritedProperty(value, "incompleteArgumentsReason");
+	const incompleteArguments = incompleteArgumentsRead.value;
+	const incompleteArgumentsReason = incompleteArgumentsReasonRead.value;
+	const incompleteMetadataSentinel =
+		(typeof incompleteArguments === "string" && SANITIZER_SENTINELS.has(incompleteArguments)) ||
+		(typeof incompleteArgumentsReason === "string" && SANITIZER_SENTINELS.has(incompleteArgumentsReason));
+	const incompleteMetadataMalformed =
+		!incompleteArgumentsRead.ok ||
+		!incompleteArgumentsReasonRead.ok ||
+		inheritedIncompleteArguments ||
+		inheritedIncompleteArgumentsReason ||
+		incompleteMetadataSentinel;
+	const escapedNonAsciiArguments = escapedGuardRead.value;
+	const rawEscapedUnicodeArgumentEvidence = evidenceRead.value;
+	let escapedUnicodeArgumentEvidence: UnicodeEscapeEvidence | undefined;
+	try {
+		escapedUnicodeArgumentEvidence = managedUnicodeEscapeEvidence(rawEscapedUnicodeArgumentEvidence);
+	} catch {
+		escapedUnicodeArgumentEvidence = undefined;
+	}
+	const invalidEscapedUnicodeEvidence =
+		(evidenceRead.present &&
+			(!evidenceRead.ok ||
+				rawEscapedUnicodeArgumentEvidence === undefined ||
+				escapedUnicodeArgumentEvidence === undefined ||
+				escapedUnicodeArgumentEvidence.malformed)) ||
+		!escapedGuardRead.ok ||
+		inheritedGuard ||
+		inheritedEvidence ||
+		incompleteMetadataMalformed;
+	const escapedArgumentsGuarded =
+		invalidEscapedUnicodeEvidence ||
+		(escapedGuardRead.present && escapedGuardRead.ok && escapedNonAsciiArguments === true) ||
+		(evidenceRead.present && evidenceRead.ok && escapedUnicodeArgumentEvidence !== undefined);
 	return {
 		type,
 		id,
@@ -2154,16 +2373,22 @@ function managedAssistantContent(value: unknown): AssistantMessage["content"][nu
 		...(typeof thoughtSignature === "string" ? { thoughtSignature } : {}),
 		...(typeof intent === "string" ? { intent } : {}),
 		...(typeof customWireName === "string" ? { customWireName } : {}),
-		...(typeof incompleteArguments === "boolean" ? { incompleteArguments } : {}),
-		...(typeof incompleteArgumentsReason === "string"
-			? {
-					incompleteArgumentsReason: incompleteArgumentsReason as
-						| "truncated"
-						| "malformed"
-						| "conflicting"
-						| "ambiguous",
-				}
-			: {}),
+		...(invalidEscapedUnicodeEvidence
+			? { incompleteArguments: true }
+			: typeof incompleteArguments === "boolean"
+				? { incompleteArguments }
+				: {}),
+		...(invalidEscapedUnicodeEvidence
+			? { incompleteArgumentsReason: "malformed" as const }
+			: typeof incompleteArgumentsReason === "string"
+				? {
+						incompleteArgumentsReason: incompleteArgumentsReason as
+							| "truncated"
+							| "malformed"
+							| "conflicting"
+							| "ambiguous",
+					}
+				: {}),
 		...(escapedArgumentsGuarded
 			? { escapedNonAsciiArguments: true }
 			: typeof escapedNonAsciiArguments === "boolean"
@@ -2582,7 +2807,57 @@ class ManagedAttemptTransaction {
 	}
 
 	acceptedAssistantSnapshot(message: AssistantMessage): AssistantMessage {
-		return this.#assistantSnapshot(message);
+		const sourceContent = Array.isArray(message.content) ? message.content : [];
+		const sourceMetadata: Array<EscapedToolCallMetadata | undefined> = [];
+		for (let index = 0; index < sourceContent.length; index += 1) {
+			const block = sourceContent[index];
+			sourceMetadata[index] = block?.type === "toolCall" ? escapedToolCallMetadata(block) : undefined;
+		}
+		let snapshot = this.#assistantSnapshot(message);
+		if (snapshot.role !== "assistant") return snapshot;
+		if (!Array.isArray(snapshot.content)) {
+			snapshot = managedAssistantShell(message, this.model, this.#degradedFieldDiagnostics, true);
+		}
+		for (let index = 0; index < sourceContent.length; index += 1) {
+			const sourceBlock = sourceContent[index];
+			if (sourceBlock?.type !== "toolCall") continue;
+			const metadata = sourceMetadata[index];
+			let snapshotBlock = snapshot.content[index];
+			if (snapshotBlock?.type !== "toolCall") {
+				const normalized = managedAssistantContent(sourceBlock);
+				if (normalized?.type !== "toolCall") continue;
+				snapshotBlock = normalized;
+				snapshot.content[index] = snapshotBlock;
+			}
+			if (metadata) {
+				const detachedMetadata = escapedToolCallMetadata(snapshotBlock);
+				const evidencePresenceChanged = Boolean(metadata.evidence) !== Boolean(detachedMetadata.evidence);
+				const metadataChanged =
+					metadata.guarded !== detachedMetadata.guarded ||
+					metadata.incompleteArguments !== detachedMetadata.incompleteArguments ||
+					evidencePresenceChanged;
+				const combinedMetadata: EscapedToolCallMetadata = {
+					guarded: metadata.guarded || detachedMetadata.guarded || metadataChanged,
+					malformed: metadata.malformed || detachedMetadata.malformed || metadataChanged,
+					evidence: metadata.evidence ?? detachedMetadata.evidence,
+					incompleteArguments: metadata.incompleteArguments || detachedMetadata.incompleteArguments,
+					incompleteArgumentsReason:
+						metadata.incompleteArgumentsReason ?? detachedMetadata.incompleteArgumentsReason,
+				};
+				if (combinedMetadata.malformed) {
+					const marked = {
+						...snapshotBlock,
+						incompleteArguments: true,
+						incompleteArgumentsReason: "malformed" as const,
+					};
+					snapshot.content[index] = marked;
+					acceptedToolCallMetadata.set(marked, combinedMetadata);
+				} else {
+					acceptedToolCallMetadata.set(snapshotBlock, combinedMetadata);
+				}
+			}
+		}
+		return snapshot;
 	}
 
 	discard(): void {
@@ -4248,7 +4523,13 @@ async function streamAssistantResponse(
 	// reflects the credential actually used, not the snapshot from AgentLoopConfig construction.
 	const authCredentialType = config.getAuthCredentialType?.(config.model.provider);
 
-	const resolvedMetadata = config.metadataResolver ? config.metadataResolver(config.model.provider) : config.metadata;
+	const resolvedMetadata = config.metadataResolver
+		? config.metadataResolver({
+				provider: config.model.provider,
+				model: config.model,
+				transport: streamFunction === streamSimple ? "default" : "custom",
+			})
+		: config.metadata;
 
 	// Synthetic recovery requests choose their tool mode explicitly below and
 	// must never consume a queued dynamic choice intended for an ordinary turn.
@@ -4751,20 +5032,23 @@ async function executeToolCalls(
 	let steeringMessages: AgentMessage[] | undefined;
 	let steeringCheck: Promise<void> | null = null;
 
-	const records = toolCalls.map(toolCall => ({
-		toolCall,
-		tool: findActiveTool(tools, toolCall.name),
-		args: toolCall.arguments as Record<string, unknown>,
-		eventFields: undefined as { toolCallId: string; toolName: string; intent: string | undefined } | undefined,
-		started: false,
-		result: undefined as AgentToolResult<any> | undefined,
-		isError: false,
-		skipped: false,
-		toolResultMessage: undefined as ToolResultMessage | undefined,
-		resultEmitted: false,
-		argumentValidationFailed: false,
-	}));
-
+	const records = toolCalls.map(toolCall => {
+		const metadata = acceptedToolCallMetadata.get(toolCall) ?? escapedToolCallMetadata(toolCall);
+		return {
+			toolCall: stripToolCallEvidence(toolCall),
+			metadata,
+			tool: findActiveTool(tools, toolCall.name),
+			args: toolCall.arguments as Record<string, unknown>,
+			eventFields: undefined as { toolCallId: string; toolName: string; intent: string | undefined } | undefined,
+			started: false,
+			result: undefined as AgentToolResult<any> | undefined,
+			isError: false,
+			skipped: false,
+			toolResultMessage: undefined as ToolResultMessage | undefined,
+			resultEmitted: false,
+			argumentValidationFailed: false,
+		};
+	});
 	const checkSteering = async (): Promise<void> => {
 		// Never consume steering once the run's own signal is aborted: an aborted
 		// run cannot deliver it (the loop hands drained steering back and ends), and
@@ -4792,6 +5076,7 @@ async function executeToolCalls(
 
 	const emitToolResult = (record: (typeof records)[number], result: AgentToolResult<any>, isError: boolean): void => {
 		if (record.resultEmitted) return;
+		record.toolCall = stripToolCallEvidence(record.toolCall);
 		const { toolCall } = record;
 		const eventFields =
 			record.eventFields ?? ({ toolCallId: toolCall.id, toolName: toolCall.name, intent: toolCall.intent } as const);
@@ -4845,6 +5130,24 @@ async function executeToolCalls(
 		stream.push({ type: "message_start", message: toolResultMessage, scope });
 		stream.push({ type: "message_end", message: toolResultMessage, scope });
 	};
+	const isInvalidEscapedRecord = (record: (typeof records)[number]): boolean => {
+		const metadata = record.metadata;
+		if (metadata.malformed) return true;
+		if (!metadata.guarded) return false;
+		return !(
+			isDisplaySafeEscapedArguments(record.tool, record.args) &&
+			isDisplaySafeRawEscapeEvidence(record.tool, record.args, metadata.evidence)
+		);
+	};
+	const hasInvalidEscapedCall = records.some(isInvalidEscapedRecord);
+	if (hasInvalidEscapedCall) {
+		for (const record of records) {
+			if (isInvalidEscapedRecord(record)) continue;
+			record.skipped = true;
+			record.toolCall = stripToolCallEvidence(record.toolCall);
+			emitToolResult(record, createSkippedToolResult(), true);
+		}
+	}
 
 	/**
 	 * Prepare every value needed to publish and invoke one dispatch before claiming that it
@@ -4903,7 +5206,7 @@ async function executeToolCalls(
 	};
 
 	const runTool = async (record: (typeof records)[number], index: number): Promise<void> => {
-		if (interruptState.triggered) {
+		if (record.skipped || interruptState.triggered) {
 			// Skip both span emission and the collector orphan record here. The
 			// scheduler-task finalizer emits the skipped result and collector record;
 			// the tail sweep below remains a defensive fallback for unexpected throws.
@@ -4911,6 +5214,7 @@ async function executeToolCalls(
 			return;
 		}
 
+		record.toolCall = stripToolCallEvidence(record.toolCall);
 		const { toolCall, tool } = record;
 		let argsForExecution = toolCall.arguments as Record<string, unknown>;
 		if (intentTracing) {
@@ -4948,16 +5252,17 @@ async function executeToolCalls(
 
 		await runInActiveSpan(toolSpan, async () => {
 			try {
-				const escapedUnicodeArgumentEvidence = toolCall.escapedUnicodeArgumentEvidence;
-				const escapedArgumentsGuarded =
-					toolCall.escapedNonAsciiArguments || escapedUnicodeArgumentEvidence !== undefined;
-				if (escapedArgumentsGuarded) delete toolCall.escapedUnicodeArgumentEvidence;
-				if (toolCall.incompleteArguments) {
+				const metadata = record.metadata;
+				const escapedUnicodeArgumentEvidence = metadata.evidence;
+				const escapedArgumentsGuarded = metadata.guarded;
+				if (escapedArgumentsGuarded) record.toolCall = stripToolCallEvidence(record.toolCall);
+				const incompleteArguments = metadata.malformed || metadata.incompleteArguments;
+				if (incompleteArguments) {
 					record.argumentValidationFailed = true;
 					// The provider flagged this call's arguments as unsafe to execute.
 					// The typed reason selects accurate recovery guidance; callers that
 					// only read the boolean still get a safe, actionable rejection.
-					const reason = toolCall.incompleteArgumentsReason;
+					const reason = metadata.incompleteArgumentsReason;
 					const detail =
 						reason === "malformed"
 							? `The terminal arguments for tool call "${toolCall.name}" did not decode to a valid JSON object. The arguments cannot be executed. Re-issue the call with valid, complete arguments.`
@@ -5265,6 +5570,7 @@ function createAbortedToolResult(
 	reason: "aborted" | "error",
 	errorMessage?: string,
 ): ToolResultMessage {
+	toolCall = stripToolCallEvidence(toolCall);
 	const message = reason === "aborted" ? "Tool execution was aborted" : "Tool execution failed due to an error";
 	const result: AgentToolResult<any> = {
 		content: [{ type: "text", text: errorMessage ? `${message}: ${errorMessage}` : `${message}.` }],

package/src/agent.ts

@@ -38,6 +38,7 @@ import type {
 	AgentEvent,
 	AgentLoopConfig,
 	AgentMessage,
+	AgentMetadataResolverContext,
 	AgentState,
 	AgentTool,
 	AgentToolContext,
@@ -67,6 +68,9 @@ const RUNTIME_FAILURE_CODES = new Set([
 	"local_snapshot_failure",
 	"provider_down",
 	"provider_unavailable",
+	"provider_rejected",
+	"provider_http_402",
+	"provider_http_429",
 	"upstream_stream_interrupted",
 	"argument_validation",
 	"execution",
@@ -120,13 +124,21 @@ function safeErrorStatus(error: unknown): number | undefined {
 	try {
 		return (
 			extractHttpStatusFromError({ status: (error as { errorStatus?: unknown } | undefined)?.errorStatus }) ??
-			extractHttpStatusFromError(error)
+			extractHttpStatusFromError(error) ??
+			extractHttpStatusFromError((error as { transportFailure?: unknown } | undefined)?.transportFailure)
 		);
 	} catch {
 		return undefined;
 	}
 }
 
+function providerFailureCode(error: unknown): string | undefined {
+	const status = safeErrorStatus(error);
+	if (status === undefined) return undefined;
+	if (status === 402 || status === 429) return `provider_http_${status}`;
+	return "provider_rejected";
+}
+
 function assertUserImagePlaceholdersHavePayload(messages: readonly AgentMessage[]): void {
 	for (const message of messages) {
 		if (!("role" in message) || message.role !== "user") continue;
@@ -455,7 +467,7 @@ export class Agent {
 	#sessionId?: string;
 	#providerSessionId?: string;
 	#metadata?: Record<string, unknown>;
-	#metadataResolver?: (provider: string) => Record<string, unknown> | undefined;
+	#metadataResolver?: (context: AgentMetadataResolverContext) => Record<string, unknown> | undefined;
 	#providerSessionState?: Map<string, ProviderSessionState>;
 	#thinkingBudgets?: ThinkingBudgets;
 	#temperature?: number;
@@ -494,6 +506,8 @@ export class Agent {
 	#onHarmonyLeak?: (event: HarmonyAuditEvent) => void | Promise<void>;
 	#onBeforeYield?: () => Promise<void> | void;
 	#shouldPause?: AgentLoopConfig["shouldPause"];
+	/** While set and returning true, steering is neither admitted nor dequeued. */
+	#steeringAdmissionFence?: () => boolean;
 	#maintainContext?: AgentLoopConfig["maintainContext"];
 	#telemetry?: AgentLoopConfig["telemetry"];
 	#appendOnlyContext?: AppendOnlyContextManager;
@@ -658,8 +672,12 @@ export class Agent {
 	 * only included for `"anthropic"` requests). Falls back to the static
 	 * {@link metadata} value when no resolver is set.
 	 */
-	metadataForProvider(provider: string): Record<string, unknown> | undefined {
-		if (this.#metadataResolver) return this.#metadataResolver(provider);
+	metadataForProvider(
+		provider: string,
+		model?: Model,
+		transport?: AgentMetadataResolverContext["transport"],
+	): Record<string, unknown> | undefined {
+		if (this.#metadataResolver) return this.#metadataResolver({ provider, model, transport });
 		return this.#metadata;
 	}
 
@@ -671,7 +689,9 @@ export class Agent {
 	 * credential. Pass `undefined` to clear and revert to the static
 	 * {@link metadata} value.
 	 */
-	setMetadataResolver(resolver: ((provider: string) => Record<string, unknown> | undefined) | undefined): void {
+	setMetadataResolver(
+		resolver: ((context: AgentMetadataResolverContext) => Record<string, unknown> | undefined) | undefined,
+	): void {
 		this.#metadataResolver = resolver;
 	}
 
@@ -880,6 +900,24 @@ export class Agent {
 		this.#shouldPause = fn;
 	}
 
+	/** The currently installed cooperative pause checkpoint, if any. */
+	get shouldPause(): AgentLoopConfig["shouldPause"] | undefined {
+		return this.#shouldPause;
+	}
+
+	/**
+	 * Fence old-turn steering admission.
+	 *
+	 * The loop polls steering UPSTREAM of its pause checkpoint (and again on the
+	 * immediate-interrupt path), so a cooperative stop alone cannot prevent one
+	 * more old-turn model call once a steering message has already been dequeued.
+	 * While the fence returns true the poll yields no messages AND does not
+	 * dequeue, so the queue survives intact for the next turn.
+	 */
+	setSteeringAdmissionFence(fn: (() => boolean) | undefined): void {
+		this.#steeringAdmissionFence = fn;
+	}
+
 	setMaintainContext(fn: AgentLoopConfig["maintainContext"] | undefined): void {
 		this.#maintainContext = fn;
 	}
@@ -1900,6 +1938,12 @@ export class Agent {
 					skipInitialSteeringPoll = false;
 					return [];
 				}
+				// Fenced: yield nothing and dequeue nothing, so a steer submitted while a
+				// fold is being claimed is neither consumed by the run being wound down
+				// nor lost.
+				if (this.#steeringAdmissionFence?.() === true) {
+					return [];
+				}
 				const queued = this.#dequeueSteeringMessages();
 				if (this.#activeRunId !== runId) {
 					this.#steeringQueue = [...queued, ...this.#steeringQueue];
@@ -2080,6 +2124,10 @@ export class Agent {
 			if (this.#activeRunId !== runId) {
 				return;
 			}
+			const providerCode = providerFailureCode(err);
+			const runtimeFailureCode = abortController.signal.aborted
+				? "aborted"
+				: (managedLocalErrorDiagnostic(err)?.errorKind ?? providerCode);
 
 			const errorMsg: AgentMessage = {
 				role: "assistant",
@@ -2116,10 +2164,7 @@ export class Agent {
 				// signal, and a local staging failure comes from the identity-
 				// checked managedLocalErrorDiagnostic — a foreign error that
 				// self-declares a local kind still maps to agent_failed.
-				error: sanitizeAgentFailure(
-					err,
-					abortController.signal.aborted ? "aborted" : managedLocalErrorDiagnostic(err)?.errorKind,
-				),
+				error: sanitizeAgentFailure(err, runtimeFailureCode),
 				scope: handle.scope,
 			});
 			this.requestRunTerminal(managedLogicalRunOwner ?? runId, {

package/src/types.ts

@@ -28,6 +28,21 @@ export type StreamFn = (
 	...args: Parameters<typeof streamSimple>
 ) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>;
 
+/**
+ * Request context supplied to provider-aware metadata resolvers.
+ *
+ * The model is the exact model selected for the concrete request (including
+ * fallback and ephemeral requests), while `transport` distinguishes the
+ * built-in stream path from a caller-supplied stream function. Metadata that
+ * carries provider identity must use both values to fail closed when routing
+ * is not the canonical provider path.
+ */
+export interface AgentMetadataResolverContext {
+	provider: string;
+	model?: Model;
+	transport?: "default" | "custom";
+}
+
 /** Stable identifier for a managed logical run, shared by all of its retry attempts. */
 export type ManagedLogicalRunId = number;
 /** A resource owned by a prompt run until its promise settles. */
@@ -257,7 +272,7 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 * current when `AgentLoopConfig` was first constructed). Overrides the static
 	 * `metadata` field when present.
 	 */
-	metadataResolver?: (provider: string) => Record<string, unknown> | undefined;
+	metadataResolver?: (context: AgentMetadataResolverContext) => Record<string, unknown> | undefined;
 
 	/**
 	 * Converts AgentMessage[] to LLM-compatible Message[] before each LLM call.