fix(ai): bind terminal safety-stop authority to adapter provenance (#4777 P1)

packages/agent/CHANGELOG.md

@@ -1,10 +1,18 @@
 # Changelog
 
 ## [Unreleased]
+- Managed fallback now transfers safety-stop authority only to the adjudicated final assistant shell; intermediate partial snapshots and hostile accessor-backed final messages cannot retain or bypass the provenance boundary (#4777 review).
+
+- Managed assistant reconstruction now copies provider metadata through guarded property reads instead of an unguarded spread, so accessor-trapped metadata degrades without aborting the attempt or creating managed retry authority (#4777 review).
+- Hostile Proxy-wrapped final messages no longer reintroduce a forged `provider_safety_stop` label through the sanitizer fallback shell; discarded failure outcomes are now label-free before session policy can suppress provider fallback (#4777 review).
+
 
 ### Fixed
 - Staged-payload sizing no longer materializes what it is bounding (#4602 fix-forward of the exact-head 078e22c0 review). All staging measurements now walk the JSON surface directly: exact byte counts come from a code-point walk (quotes, escapes, separators, delimiters, nulls, array holes, and keys all charged) instead of building the full `JSON.stringify` string plus its UTF-8 encoding, and lone surrogates are charged as the six-byte `\udXXX` escape JSON emits rather than their three-byte UTF-8 form, closing a ~2x undercount on surrogate-heavy strings. `structuredClone` is additionally preflighted by a clone-surface walk that never dispatches `toJSON`, accessors, or proxy traps: a live payload class whose compact `toJSON` hides an oversized own payload is rejected as the typed `local_buffer_overflow` at `overflow.preMeasure` — before the duplicate is allocated — instead of being cloned first and rejected at `overflow.staged`. Accessors are no longer invoked at all while sizing (a staged witness getter is read zero times), `undefined`-valued record properties are skipped exactly as `JSON.stringify` omits them, an unmeasurable assistant pair now fails closed like its `#stage` twin instead of being retained with a zero-byte charge, the `overflow.preMeasure` diagnostic reports the incoming event's real bounded size instead of a constant fabricated after `discard()`, and above-ceiling clamp warnings are logged once per distinct knob value with a bounded digest. |
 - Provider safety-stop messages now retain their explicitly allowlisted `errorKind: "provider_safety_stop"` through managed assistant snapshots and remain terminal even when transport facts are present on a multi-model fallback chain, while provider payloads still cannot forge the runtime-owned local diagnostic kinds (#4777).
+- Terminal safety-stop authority is now provenance-bound instead of data-bound: a provider or custom stream payload that self-labels `errorKind: "provider_safety_stop"` without the adapter-minted mark is stripped at the stream exit before any retry/discard gate or the managed snapshot shell reads it, so a compromised provider can no longer force refusal by naming the field (#4777 review). Authenticated first-party envelopes (structured refusal signals parsed by the anthropic, openai-completions, and google adapters) keep terminal treatment, and only the agent loop's module-private rebuild set carries that authority onto its own destination — clones, JSON/persistence round-trips, and re-emitted payloads are all unauthenticated.
+- Safety-stop minting is now limited to the package-private adapter capability, and public AI consumers cannot transfer authority from a genuine marked source to an arbitrary destination. The trailing stream-completion path also sanitizes provenance before rebuilding managed assistant messages, covering streams that end without a `done` or `error` event and keeping forged labels fallback-eligible (#4777 review).
+- Safety-stop authority now expires at every stream dispatch entry: committed assistant messages (including a previously adjudicated stop) are handed to the next — possibly custom — stream through `convertToLlm`, and the dispatch-entry expiry guarantees no live authority mark is ever exposed to a stream, so re-use of a committed stop object cannot forge a terminal failure (#4777 review). The provenance strip is also stopReason-independent and rebuilds frozen or Proxy-trapped final messages as plain mutable copies, so a forged label on a nominally successful response cannot survive into the committed message (where it could skip session compaction checks) and cannot abort the run through a rejection trap.
 - A foreign error that self-declares a local failure kind no longer gets one either (#4618). `errorKind` and the structured `bufferOverflow` shape now come from a single identity-checked extractor (`managedLocalErrorDiagnostic`) used by both terminal-message producers — `managedFailureMessage` and the `Agent` run catch. Previously the shape was identity-gated but the label was not, so a provider or custom-stream failure carrying `errorKind: "local_buffer_overflow"` reached the parent receipt preview as `Local staging-buffer overflow; structured diagnostic unavailable.` and pointed whoever read it at the wrong subsystem.
 - Local diagnostic authority fields are no longer foreign-settable through the managed snapshot shell (#4618). `managedAssistantShell` spreads the provider/stream message snapshot into the rebuilt assistant message; a payload that smuggled a local `errorKind` or `bufferOverflow` through that spread could masquerade as the runtime's own identity-checked diagnostic at the parent boundary. Local kinds and `bufferOverflow` remain stripped from the snapshot spread, while the provider-owned safety-stop kind is copied only through its explicit closed-literal guard.
 

packages/agent/src/agent-loop.ts

@@ -12,6 +12,7 @@ import {
 	classifyFallbackTrigger,
 	EMPTY_RESPONSE_PROVIDER_CODE,
 	EventStream,
+	isProviderSafetyStopAuthenticated,
 	isZodSchema,
 	streamSimple,
 	type ToolChoice,
@@ -34,6 +35,7 @@ import {
 } from "@gajae-code/ai/utils";
 import { isCursorExecResolved } from "@gajae-code/ai/utils/block-symbols";
 import { $credentialEnv, logger, sanitizeText } from "@gajae-code/utils";
+import { revokeProviderSafetyStop } from "../../ai/src/adapter-internals/provider-safety-stop";
 import type { AttemptScope } from "./attempt-scope";
 import {
 	createHarmonyAuditEvent,
@@ -491,23 +493,53 @@ function managedContextOverflow(message: AssistantMessage, config: AgentLoopConf
 }
 
 /** Managed fallback owns retry policy; only attached typed transport facts may discard an attempt. */
-function managedProperty(value: unknown, key: string): unknown {
-	if (!value || typeof value !== "object") return undefined;
+function managedPropertyRead(value: unknown, key: string): { ok: boolean; value: unknown } {
+	if (!value || typeof value !== "object") return { ok: true, value: undefined };
 	try {
-		return Reflect.get(value, key);
+		return { ok: true, value: Reflect.get(value, key) };
 	} catch {
-		return undefined;
+		return { ok: false, value: undefined };
 	}
 }
 
+function managedProperty(value: unknown, key: string): unknown {
+	return managedPropertyRead(value, key).value;
+}
+
 function managedTransportFailure(failure: unknown) {
 	const facts = managedProperty(failure, "transportFailure");
 	return facts && typeof facts === "object" ? transportFailureFacts(facts) : undefined;
 }
 
+// AI owns provider-originated authority. The agent loop owns authority for
+// the rebuilt message objects it creates; this second WeakSet is deliberately
+// module-private so a public AI consumer cannot transfer authority to an
+// arbitrary destination. A destination is marked only while this managed
+// runtime is rebuilding a source that AI authenticated.
+const managedProviderSafetyStops = new WeakSet<object>();
+
+function isManagedProviderSafetyStopAuthenticated(value: unknown): boolean {
+	return (
+		isProviderSafetyStopAuthenticated(value) ||
+		(typeof value === "object" && value !== null && managedProviderSafetyStops.has(value))
+	);
+}
+
 function managedRetryableFailure(failure: unknown): boolean {
 	const facts = managedTransportFailure(failure);
 	if (!facts) 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`)
+	// and must fall through to ordinary transport classification so the chain
+	// can still advance (#4777).
+	if (
+		managedProperty(failure, "stopReason") === "error" &&
+		managedProperty(failure, "errorKind") === "provider_safety_stop" &&
+		isManagedProviderSafetyStopAuthenticated(failure)
+	) {
+		return false;
+	}
 	const trigger = classifyFallbackTrigger(facts);
 	// A plain `forbidden` is terminal: retrying it just re-sends a request the
 	// caller is not authorized to make, and the credential-mutating consumers
@@ -532,6 +564,62 @@ function promoteTypedEmptyResponseStop(message: AssistantMessage): void {
 	message.stopReason = "error";
 	message.errorMessage = "Provider returned an empty response with zero token usage";
 }
+/**
+ * Terminal safety-stop authority is provenance-bound, not data-bound: a
+ * provider or custom stream payload that self-labels
+ * `errorKind: "provider_safety_stop"` without the adapter-minted mark must not
+ * terminalize the failure, because terminal treatment suppresses the user's
+ * configured fallback chain (#4777 review follow-up). Strip the unauthenticated
+ * field from the live final message at the single stream-exit point, before
+ * the managed snapshot shell clones it and before any retry/discard policy
+ * reads it, so a forged label degrades to an ordinary (fallback-eligible)
+ * error everywhere downstream — loop gates, session policy, and persistence.
+ *
+ * The label is stripped regardless of stopReason: the field is reserved for
+ * adapter-minted terminal stops, and downstream consumers (session compaction
+ * checks among them) read it without re-checking the error state, so a forged
+ * label on a nominally successful response must not survive either. A frozen
+ * or Proxy-trapped final message is rebuilt as a plain mutable copy instead of
+ * letting the strip abort the run.
+ */
+
+function sanitizeProviderSafetyStopProvenance(
+	message: AssistantMessage,
+	model: AgentLoopConfig["model"],
+): AssistantMessage {
+	const errorKindRead = managedPropertyRead(message, "errorKind");
+	if (
+		errorKindRead.ok &&
+		(errorKindRead.value !== "provider_safety_stop" || isManagedProviderSafetyStopAuthenticated(message))
+	) {
+		return message;
+	}
+	const detached = managedAttemptSnapshotDetailed(message).snapshot;
+	if (isManagedPlainRecord(detached)) {
+		const rebuilt = { ...detached } as AssistantMessage;
+		delete rebuilt.errorKind;
+		return rebuilt;
+	}
+	const rebuilt = managedAssistantShell(message, model);
+	delete rebuilt.errorKind;
+	return rebuilt;
+}
+
+/**
+ * Expire residual terminal safety-stop authority before a dispatch exposes
+ * committed history to a stream. Once a stop has been adjudicated, its
+ * committed assistant message may be handed unchanged to a later — possibly
+ * custom — stream through `convertToLlm`; a live mark would let that stream
+ * re-use the authenticated object (or a mutation of it) to forge a terminal
+ * failure and suppress the fallback chain (#4777 review follow-up).
+ */
+function expireProviderSafetyStopAuthority(messages: AgentMessage[]): void {
+	for (const message of messages) {
+		if (message.role !== "assistant") continue;
+		revokeProviderSafetyStop(message);
+		managedProviderSafetyStops.delete(message);
+	}
+}
 
 /**
  * Neutralize leaked reserved control tokens in-place across the outgoing
@@ -1693,6 +1781,7 @@ function managedAssistantShell(
 	value: unknown,
 	model: AgentLoopConfig["model"],
 	degradedFieldDiagnostics: Set<string> = new Set<string>(),
+	transferSafetyStopAuthority = false,
 ): AssistantMessage {
 	const detailed = managedAttemptSnapshotDetailed(value);
 	const snapshotRecord = isManagedPlainRecord(detailed.snapshot) ? detailed.snapshot : undefined;
@@ -1758,9 +1847,13 @@ function managedAssistantShell(
 		stopReason === "error" && managedProperty(source, "errorKind") === "provider_safety_stop"
 			? ("provider_safety_stop" as const)
 			: undefined;
-	const safeMetadata: Record<string, unknown> = isManagedPlainRecord(detailed.snapshot)
-		? { ...detailed.snapshot }
-		: {};
+	const safeMetadata: Record<string, unknown> = {};
+	if (isManagedPlainRecord(detailed.snapshot)) {
+		for (const key of Object.keys(detailed.snapshot)) {
+			const metadata = managedProperty(detailed.snapshot, key);
+			if (metadata !== undefined) safeMetadata[key] = metadata;
+		}
+	}
 	delete safeMetadata.errorMessage;
 	delete safeMetadata.errorStatus;
 	delete safeMetadata.transportFailure;
@@ -1770,7 +1863,7 @@ function managedAssistantShell(
 	// runtime failure in the executor's parent-facing summary (#4618).
 	delete safeMetadata.errorKind;
 	delete safeMetadata.bufferOverflow;
-	return {
+	const rebuilt: AssistantMessage = {
 		...safeMetadata,
 		role: "assistant",
 		content,
@@ -1785,6 +1878,16 @@ function managedAssistantShell(
 		...(errorKind ? { errorKind } : {}),
 		...(typeof errorStatus === "number" && Number.isFinite(errorStatus) ? { errorStatus } : {}),
 	};
+	// The closed-literal copy above is fed by the stream-exit provenance
+	// sanitize, so an unauthenticated label never reaches here. Mark the
+	// runtime-owned destination only when this source is already authenticated;
+	// no public AI API can perform this transfer (#4777 review).
+	if (transferSafetyStopAuthority && errorKind && isManagedProviderSafetyStopAuthenticated(value)) {
+		managedProviderSafetyStops.add(rebuilt);
+		revokeProviderSafetyStop(value);
+		if (typeof value === "object" && value !== null) managedProviderSafetyStops.delete(value);
+	}
+	return rebuilt;
 }
 
 function managedContentBlock(block: unknown): AssistantMessage["content"] {
@@ -3479,7 +3582,7 @@ async function runLoopBody(
 				return;
 			}
 			if (attemptTransaction) {
-				message = managedAssistantShell(message, config.model);
+				message = managedAssistantShell(message, config.model, new Set<string>(), true);
 				const index = currentContext.messages.length - 1;
 				if (index >= 0 && currentContext.messages[index]?.role === "assistant") {
 					currentContext.messages[index] = message;
@@ -3785,10 +3888,22 @@ async function streamAssistantResponse(
 	const managedDegradedFieldDiagnostics = new Set<string>();
 	// Apply context transform if configured (AgentMessage[] → AgentMessage[])
 	let messages = context.messages;
+	// Revoke before invoking any caller-controlled transform so it cannot retain
+	// a live authenticated object and restore its role for a later custom stream.
+	expireProviderSafetyStopAuthority(messages);
+	if (messages !== context.messages) expireProviderSafetyStopAuthority(context.messages);
 	if (config.transformContext) {
 		messages = await config.transformContext(messages, signal, scope);
 	}
 
+	// Expire residual terminal safety-stop authority again after the transform:
+	// committed history (including a previously adjudicated stop) is handed
+	// to the stream through convertToLlm below, and a live mark would let a
+	// custom stream re-use the authenticated object to forge a terminal
+	// failure (#4777 review follow-up).
+	expireProviderSafetyStopAuthority(messages);
+	if (messages !== context.messages) expireProviderSafetyStopAuthority(context.messages);
+
 	// Convert to LLM-compatible messages (AgentMessage[] → Message[]) and normalize at the LLM boundary.
 	// Cache hits are keyed by provider-visible content hashes, never message object identity.
 	const normalizedMessages = await convertAndNormalizeMessages(messages, context, config);
@@ -4176,9 +4291,10 @@ async function streamAssistantResponse(
 
 						case "done":
 						case "error": {
+							const finished = sanitizeProviderSafetyStopProvenance(await finishResponse(), config.model);
 							const finalMessage = config.fallbackManaged
-								? managedAssistantShell(await finishResponse(), config.model, managedDegradedFieldDiagnostics)
-								: await finishResponse();
+								? managedAssistantShell(finished, config.model, managedDegradedFieldDiagnostics, true)
+								: finished;
 							promoteTypedEmptyResponseStop(finalMessage);
 							if (addedPartial) {
 								context.messages[context.messages.length - 1] = finalMessage;
@@ -4199,9 +4315,10 @@ async function streamAssistantResponse(
 				closeIterator();
 			}
 
+			const finished = sanitizeProviderSafetyStopProvenance(await finishResponse(), config.model);
 			const trailing = config.fallbackManaged
-				? managedAssistantShell(await finishResponse(), config.model, managedDegradedFieldDiagnostics)
-				: await finishResponse();
+				? managedAssistantShell(finished, config.model, managedDegradedFieldDiagnostics, true)
+				: finished;
 			await finishChat(trailing);
 			return trailing;
 		});