@namzu/sdk 32.0.0 → 33.1.0

package/src/runtime/query/index.ts

@@ -25,6 +25,7 @@ import { EmergencySaveManager } from '../../manager/run/emergency.js'
 import type { RunPersistence } from '../../manager/run/persistence.js'
 import { resolveModelPricing } from '../../pricing/index.js'
 import { resolveProviderCapabilities } from '../../provider/capabilities.js'
+import { isCallerAbortError } from '../../provider/errors.js'
 import {
 	type ProviderChainMember,
 	type ServingMember,
@@ -77,6 +78,7 @@ import type { AgentPersona } from '../../types/persona/index.js'
 import type { LLMProvider } from '../../types/provider/index.js'
 import type { TaskRouterConfig } from '../../types/router/index.js'
 import type { ReviewAnswer } from '../../types/run/answer-review.js'
+import { cancelCauseOf } from '../../types/run/cancel-cause.js'
 import type { CheckpointStore, FencingToken } from '../../types/run/checkpoint-store.js'
 import type { RunEventCursor, RunEventReplay } from '../../types/run/event-cursor.js'
 import { resolveRunEventReplay } from '../../types/run/event-cursor.js'
@@ -758,7 +760,9 @@ export interface QueryParams {
 	 * attachments against a `supportsVision: false` driver), the runtime
 	 * warns loudly, emits a `capability_warning` run event, and degrades
 	 * explicitly (tool surfaces stripped from prompt + request;
-	 * attachments left unmapped by the driver). `true`: throw instead of
+	 * attachments left unmapped by the driver). The same policy is checked
+	 * immediately before every request for image/document blocks produced by a
+	 * tool, because those do not exist at run setup. `true`: throw instead of
 	 * degrading.
 	 */
 	strictCapabilities?: boolean
@@ -1367,6 +1371,40 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 	eventTranslator.wireActivityStore(ctx.activityStore, ctx.runId)
 	eventTranslator.wirePlanManager(ctx.planManager, ctx.runId)
 	eventTranslator.setGeneration(params.claimFence)
+	let interruptHooksStarted = false
+	const executeUserInterruptHooks = async (terminalError: unknown): Promise<void> => {
+		if (
+			interruptHooksStarted ||
+			!params.pluginManager ||
+			!isCallerAbortError(terminalError, ctx.abortController.signal) ||
+			params.parentRunId !== undefined ||
+			(params.depth ?? 0) !== 0 ||
+			cancelCauseOf(ctx.abortController.signal.reason) !== 'user'
+		) {
+			return
+		}
+
+		interruptHooksStarted = true
+		try {
+			// Deliberately omit the already-aborted run signal. The lifecycle
+			// manager still supplies each handler its own deadline signal, while
+			// `run_interrupt`'s observational fan-out prevents one result from
+			// suppressing the cleanup hooks that follow it.
+			await params.pluginManager.executeHooks(
+				'run_interrupt',
+				{ runId: ctx.runId, cancelCause: 'user' },
+				eventTranslator.emitEvent,
+			)
+		} catch (error) {
+			// Cancellation is the terminal authority. A hook event sink or an
+			// unexpected manager failure is reported, but cannot turn Stop into a
+			// failed run or prevent the durable cancellation verdict.
+			ctx.log.error('Run interrupt hooks did not settle cleanly', {
+				[NAMZU.RUN_ID]: ctx.runId,
+				...errorAttributes(error),
+			})
+		}
+	}
 
 	if (attachmentResolutionCancelled) {
 		// Attachment materialization happens before RunContext exists. Once it
@@ -1375,6 +1413,9 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		// and settle through the ordinary cancellation classifier. Prompt
 		// contributions/cache, host callbacks, tools, plugins, sandbox, guardrails,
 		// advisors, and providers are all authority-bearing work and stay out.
+		// The dedicated root interrupt notification is the sole plugin exception:
+		// it runs after cancellation under its own deadline and cannot regain model
+		// or tool authority.
 		if (params.resumeFromCheckpoint && !selectedResumeState) {
 			// The canonical resume surface hands query the checkpoint state it
 			// already selected. A raw resume query has no such snapshot; after
@@ -1460,6 +1501,8 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			const terminalError = ctx.abortController.signal.aborted
 				? ctx.abortController.signal.reason
 				: error
+			await executeUserInterruptHooks(terminalError)
+			yield* eventTranslator.drainPending()
 			yield* cancelledAssembler.handleError(terminalError, rootSpan)
 		} finally {
 			rootSpan.end()
@@ -1620,6 +1663,14 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 	const questionParks = params.questionParks ?? new QuestionParkBinding()
 	const pendingAnswers = params.pendingAnswers ?? new PendingAnswers()
 
+	// One gate instance owns both model-issued calls and calls dispatched by
+	// another tool. Constructing it only inside the iteration review left the
+	// nested registry path outside the operator's policy entirely.
+	const gateConfig = params.authorizationGate
+	const verificationGate = gateConfig?.enabled
+		? new AuthorizationGate(gateConfig, ctx.log)
+		: undefined
+
 	//  is null only when the run has no disk layout (tests,
 	// in-memory hosts); the budget then degrades to middle-elision.
 	const runDirForTools = ctx.runMgr.getRunDir()
@@ -1660,6 +1711,8 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			// `read`/`grep` without a new affordance.
 			...(toolOutputDir ? { toolOutputDir } : {}),
 			...(params.repairToolCall ? { repairToolCall: params.repairToolCall } : {}),
+			...(verificationGate ? { authorizationGate: verificationGate } : {}),
+			recordAudit: (input) => ctx.runMgr.recordAudit(input),
 			// The durable pause, reachable from any tool rather than from the
 			// four kernel-owned points that used to own it. Built here from
 			// the machinery the run already holds; the recorder binds a few
@@ -1806,14 +1859,10 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		}
 	}
 
-	const gateConfig = params.authorizationGate
-
-	const verificationGate = gateConfig?.enabled
-		? new AuthorizationGate(gateConfig, ctx.log)
-		: undefined
-
 	const iterationOrchestrator = new IterationOrchestrator({
 		provider: resilientProvider,
+		providerCapabilities: capabilities,
+		strictCapabilities: params.strictCapabilities === true,
 		servingMember: () => serving.current,
 		runConfig,
 		...(params.stopWhen ? { stopWhen: params.stopWhen } : {}),
@@ -2581,6 +2630,8 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		} catch (err) {
 			// A failed run still spent its steps; report them.
 			ctx.runMgr.setSteps(iterationOrchestrator.getSteps())
+			await executeUserInterruptHooks(err)
+			yield* eventTranslator.drainPending()
 			yield* resultAssembler.handleError(err, rootSpan)
 		} finally {
 			// Release the process's termination path as soon as this run is

package/src/runtime/query/iteration/index.ts

@@ -7,6 +7,7 @@ import {
 	STRUCTURED_OUTPUT_REPROMPT,
 } from '../../../constants/tools/index.js'
 import { renderSkillsSection } from '../../../persona/assembler.js'
+import { resolveProviderCapabilities } from '../../../provider/capabilities.js'
 import { collectChatCompletion } from '../../../provider/collect-chat-completion.js'
 import { formatCompletionNotification } from '../../../scheduler/completion-inbox.js'
 import {
@@ -19,8 +20,10 @@ import { getTracer } from '../../../telemetry/runtime-accessors.js'
 import { STRUCTURED_OUTPUT_TOOL_NAME } from '../../../tools/builtins/structuredOutput.js'
 import { DELEGATION_TIMEOUT_MS } from '../../../tools/coordinator/index.js'
 import type { CostInfo, TokenUsage } from '../../../types/common/index.js'
+import { NamzuError } from '../../../types/errors/index.js'
 import type { MessageId } from '../../../types/ids/index.js'
 import {
+	type Message,
 	createAssistantMessage,
 	createRuntimeContextMessage,
 	createSystemMessage,
@@ -148,6 +151,8 @@ export class IterationOrchestrator {
 	 * one process must not suppress each other's first envelope.
 	 */
 	private lastEnvelopeKey: string | undefined
+	/** Rich tool blocks already reported; durable history is scanned every turn. */
+	private readonly warnedRichToolResults = new Set<string>()
 	/**
 	 * The previous iteration held a `stopWhen` decision open for a worker.
 	 *
@@ -168,6 +173,70 @@ export class IterationOrchestrator {
 		this.ctx = ctx
 	}
 
+	/**
+	 * Check the exact post-budget request for tool-result shapes the active driver
+	 * cannot carry. Initial capability negotiation cannot see results produced by
+	 * a later tool turn, so this boundary runs immediately before every provider
+	 * call. Keys are durable call/block coordinates, which prevents old history
+	 * from warning again on every subsequent iteration.
+	 */
+	private async reportUnsupportedToolResults(messages: readonly Message[]): Promise<void> {
+		const capabilities =
+			this.ctx.providerCapabilities ?? resolveProviderCapabilities(this.ctx.provider)
+		const images: string[] = []
+		const documents: string[] = []
+		for (const message of messages) {
+			if (message.role !== 'tool' || !Array.isArray(message.content)) continue
+			for (const [index, block] of message.content.entries()) {
+				const key = `${message.toolCallId}:${index}:${block.type}`
+				if (this.warnedRichToolResults.has(key)) continue
+				if (block.type === 'image' && !capabilities.supportsToolResultImages) {
+					images.push(key)
+				}
+				if (block.type === 'document' && !capabilities.supportsToolResultDocuments) {
+					documents.push(key)
+				}
+			}
+		}
+
+		const report = async (
+			keys: readonly string[],
+			capability: 'vision' | 'documents',
+			label: 'image' | 'document',
+		): Promise<void> => {
+			if (keys.length === 0) return
+			const message = `Provider '${this.ctx.provider.id}' declares it cannot map ${label} tool results, but this request carries ${keys.length} new ${label} block(s). The model will receive the driver's explicit text fallback instead of that content.`
+			if (this.ctx.strictCapabilities) {
+				throw new NamzuError({
+					code: 'capability_unavailable',
+					message,
+					details: {
+						providerId: this.ctx.provider.id,
+						capability,
+						blockCount: keys.length,
+					},
+				})
+			}
+			for (const key of keys) this.warnedRichToolResults.add(key)
+			this.ctx.log.warn('Capability mismatch: the provider cannot map rich tool results', {
+				'namzu.capability.detail': message,
+				[GENAI.SYSTEM]: this.ctx.provider.id,
+				'namzu.runtime.rich_tool_result_count': keys.length,
+			})
+			await this.ctx.emitEvent({
+				type: 'capability_warning',
+				runId: this.ctx.runMgr.id,
+				capability,
+				contentSource: 'tool-result',
+				providerId: this.ctx.provider.id,
+				message,
+			})
+		}
+
+		await report(images, 'vision', 'image')
+		await report(documents, 'documents', 'document')
+	}
+
 	/**
 	 * Adopt the run's span after construction.
 	 *
@@ -459,6 +528,8 @@ export class IterationOrchestrator {
 						requestHistory,
 						this.ctx.runConfig.maxRequestRichContentBytes ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
 					)
+					await this.reportUnsupportedToolResults(messages)
+					yield* this.ctx.drainPending()
 
 					// What the model is about to be ASKED, recorded when it
 					// changed. `run_started` carries one system prompt and tool
@@ -1986,6 +2057,7 @@ export class IterationOrchestrator {
 				finalHistory,
 				this.ctx.runConfig.maxRequestRichContentBytes ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
 			)
+			await this.reportUnsupportedToolResults(finalMessages)
 
 			// Same cache discipline as the forced-final iteration: keep the
 			// tools param identical to prior iterations (cache prefix intact,

package/src/runtime/query/iteration/phases/context.ts

@@ -7,6 +7,7 @@ import { NAMZU } from '../../../../constants/telemetry/index.js'
 import type { PlanManager } from '../../../../manager/plan/lifecycle.js'
 import type { RunPersistence } from '../../../../manager/run/persistence.js'
 import type { PromptContributionRegistry } from '../../../../prompt/contributions.js'
+import type { ResolvedProviderCapabilities } from '../../../../provider/capabilities.js'
 import type { ServingMember } from '../../../../provider/fallback.js'
 import type { CompletionInbox } from '../../../../scheduler/completion-inbox.js'
 import type { ActivityStore } from '../../../../store/activity/memory.js'
@@ -44,6 +45,10 @@ import type { ToolGrantSet } from '../../tool-grants.js'
 
 export interface IterationContext {
 	readonly provider: LLMProvider
+	/** Driver-level request shapes negotiated for this run. */
+	readonly providerCapabilities?: ResolvedProviderCapabilities
+	/** Refuse a capability mismatch instead of emitting a warning and degrading. */
+	readonly strictCapabilities?: boolean
 	/**
 	 * Which chain member `provider` will route the NEXT request to.
 	 *

package/src/runtime/query/iteration/phases/tool-review.ts

@@ -1,7 +1,8 @@
 import type { AuthorizationGate } from '../../../../authorization/index.js'
+import type { ToolCallSummary } from '../../../../types/hitl/index.js'
 import type { ChatCompletionResponse } from '../../../../types/provider/index.js'
 import type { RunEvent } from '../../../../types/run/index.js'
-import type { ToolCallDenials } from '../../executor.js'
+import type { PreparedToolBatch, ToolCallDenials } from '../../executor.js'
 import {
 	awaitProjectInstructionCallback,
 	replaceProjectInstructionSnapshot,
@@ -64,28 +65,42 @@ export async function* runToolReview(
 		return finish('executed')
 	}
 
-	const toolCallSummaries = toolCalls.map((tc) => {
-		let input: unknown
-		try {
-			input = JSON.parse(tc.function.arguments)
-		} catch {
-			input = tc.function.arguments
-		}
-		const tool = ctx.tools.get(tc.function.name)
-		const isDestructive = tool?.isDestructive ? tool.isDestructive(input) : false
-
-		return {
-			id: tc.id,
-			name: tc.function.name,
-			input,
-			isDestructive,
-		}
-	})
+	const prepareForReview = async (): Promise<PreparedToolBatch | undefined> => {
+		const prepare = ctx.toolExecutor.prepareBatchForReview
+		return typeof prepare === 'function' ? prepare.call(ctx.toolExecutor, response) : undefined
+	}
+	let preparedBatch = await prepareForReview()
+	const summariesFor = (prepared: PreparedToolBatch | undefined): ToolCallSummary[] => {
+		const calls =
+			prepared?.reviewCalls ??
+			toolCalls.map((tc) => {
+				let input: unknown
+				try {
+					input = JSON.parse(tc.function.arguments)
+				} catch {
+					input = tc.function.arguments
+				}
+				return { id: tc.id, name: tc.function.name, input }
+			})
+		return calls.map((tc) => {
+			const tool = ctx.tools.get(tc.name)
+			const isDestructive = tool?.isDestructive ? tool.isDestructive(tc.input) : false
+
+			return {
+				id: tc.id,
+				name: tc.name,
+				input: tc.input,
+				isDestructive,
+				authorization: { decision: 'review' },
+			}
+		})
+	}
+	let toolCallSummaries = summariesFor(preparedBatch)
 
 	/** Executes the batch, answering every call, and appends the results. */
 	const settle = async (denials?: ToolCallDenials): Promise<void> => {
 		const startedAt = Date.now()
-		const batch = await ctx.toolExecutor.executeBatch(response, denials)
+		const batch = await ctx.toolExecutor.executeBatch(response, denials, undefined, preparedBatch)
 		toolMs += Date.now() - startedAt
 		executed = batch.results
 		// Recorded AFTER execution and never before it: this advises, it does
@@ -130,6 +145,12 @@ export async function* runToolReview(
 		}
 	}
 
+	if (toolCallSummaries.length === 0) {
+		await settle()
+		yield* ctx.drainPending()
+		return finish('executed')
+	}
+
 	/** Every call denied for the same reason (human rejection, gate stop). */
 	const denyAll = (reason: string): ToolCallDenials =>
 		new Map(toolCalls.map((tc) => [tc.id, reason]))
@@ -159,10 +180,16 @@ export async function* runToolReview(
 				toolDef: ctx.tools.get(tc.name),
 			}),
 		}))
+		for (const { toolCall, gateResult } of gateResults) {
+			toolCall.authorization = {
+				decision: gateResult.decision,
+				...(gateResult.reason ? { reason: gateResult.reason } : {}),
+			}
+		}
 
 		for (const gr of gateResults) {
 			if (gr.gateResult.decision === 'deny') {
-				const reason = `Blocked by the verification gate: ${gr.gateResult.reason}`
+				const reason = `Blocked by the authorization gate: ${gr.gateResult.reason}`
 				gateDenied.set(gr.toolCall.id, reason)
 				// A gate denial is a refusal — first-class in the audit trail, never
 				// an absent record (LOG-14, design §5). Written here, once per
@@ -180,7 +207,7 @@ export async function* runToolReview(
 		const allDenied = gateResults.every((gr) => gr.gateResult.decision === 'deny')
 
 		if (allAllowed) {
-			ctx.log.debug('Verification gate: all tool calls pre-approved', {
+			ctx.log.debug('Authorization gate: all tool calls pre-approved', {
 				'namzu.tool.names': gateResults.map((gr) => gr.toolCall.name),
 			})
 			await settle()
@@ -189,7 +216,7 @@ export async function* runToolReview(
 		}
 
 		if (allDenied) {
-			ctx.log.debug('Verification gate: all tool calls denied', {
+			ctx.log.debug('Authorization gate: all tool calls denied', {
 				'namzu.tool.names': gateResults.map((gr) => gr.toolCall.name),
 			})
 			await settle(gateDenied)
@@ -197,7 +224,7 @@ export async function* runToolReview(
 			return finish('rejected')
 		}
 
-		ctx.log.debug('Verification gate: mixed decisions, proceeding to review', {
+		ctx.log.debug('Authorization gate: mixed decisions, proceeding to review', {
 			'namzu.runtime.decisions': gateResults.map((gr) => ({
 				tool: gr.toolCall.name,
 				decision: gr.gateResult.decision,
@@ -267,6 +294,7 @@ export async function* runToolReview(
 
 			// Gate denials are the floor; per-call human denials add to them.
 			const denials = new Map(gateDenied)
+			const modifiedCallIds = new Set<string>()
 
 			for (const mod of reviewDecision.modifications) {
 				if (mod.action === 'modify' && mod.modifiedInput !== undefined) {
@@ -274,6 +302,7 @@ export async function* runToolReview(
 					// A modification cannot resurrect a gate-denied call.
 					if (tc && !denials.has(tc.id)) {
 						tc.function.arguments = JSON.stringify(mod.modifiedInput)
+						modifiedCallIds.add(tc.id)
 					}
 				}
 				if (mod.action === 'deny' && !denials.has(mod.toolCallId)) {
@@ -281,6 +310,41 @@ export async function* runToolReview(
 				}
 			}
 
+			// A human modification changes the raw call after the first preparation.
+			// Decode it once again, then require policy to explicitly allow the new
+			// executable value. A second nested review would be ambiguous: the human
+			// edited raw JSON, not an unseen schema transform of it.
+			if (modifiedCallIds.size > 0) {
+				const reprepare = ctx.toolExecutor.reprepareBatchForReview
+				preparedBatch =
+					preparedBatch && typeof reprepare === 'function'
+						? await reprepare.call(ctx.toolExecutor, response, preparedBatch, modifiedCallIds)
+						: await prepareForReview()
+				toolCallSummaries = summariesFor(preparedBatch)
+			}
+			if (ctx.verificationGate && modifiedCallIds.size > 0) {
+				for (const summary of toolCallSummaries) {
+					if (!modifiedCallIds.has(summary.id)) continue
+					if (denials.has(summary.id)) continue
+					const gateResult = ctx.verificationGate.evaluate({
+						toolName: summary.name,
+						toolInput: summary.input,
+						toolDef: ctx.tools.get(summary.name),
+					})
+					if (gateResult.decision === 'allow') continue
+					const reason =
+						gateResult.decision === 'deny'
+							? `Blocked by the authorization gate after the tool input was modified: ${gateResult.reason}`
+							: `Blocked by the authorization gate after the tool input was modified: the prepared value requires a new explicit approval. ${gateResult.reason}`
+					denials.set(summary.id, reason)
+					await ctx.runMgr.recordAudit({
+						what: { action: 'tool_call', tool: summary.name },
+						outcome: 'refused',
+						reason,
+					})
+				}
+			}
+
 			const everythingDenied = denials.size === toolCalls.length
 			await settle(denials)
 			yield* ctx.drainPending()

package/src/runtime/query/request-rich-content.ts

@@ -34,7 +34,7 @@ interface RichOccurrence {
 	readonly source: 'user' | 'tool'
 	readonly kind: RichKind
 	readonly bytes: number
-	readonly reason: 'budget' | 'provider-rejected'
+	readonly reason: 'budget' | 'provider-rejected' | 'invalid-image'
 }
 
 export interface RequestImageIdentity {
@@ -54,6 +54,12 @@ const rejectedUserImageMarker = (): string =>
 const rejectedToolImageMarker = (): string =>
 	'[image omitted from this model request because the provider rejected this image; call the producing tool again after correcting its image source if it is still needed.]'
 
+const invalidUserImageMarker = (): string =>
+	'[image omitted from this model request because its encoded bytes are not a complete supported raster matching the declared media type; attach a corrected image in a new message if it is still needed.]'
+
+const invalidToolImageMarker = (): string =>
+	'[image omitted from this model request because the producing tool returned encoded bytes that are not a complete supported raster matching the declared media type; call the tool again after correcting its image source if it is still needed.]'
+
 function assertInlineAttachment(
 	attachment: MessageAttachment,
 ): asserts attachment is Exclude<MessageAttachment, { readonly type: 'stored' }> {
@@ -78,10 +84,12 @@ function collectRichOccurrences(messages: readonly Message[]): RichOccurrence[]
 					kind: attachment.type === 'document' ? 'document' : 'image',
 					bytes: attachment.data.length,
 					reason:
-						attachment.type !== 'document' &&
-						attachment.modelOmission?.reason === 'provider-rejected'
-							? 'provider-rejected'
-							: 'budget',
+						attachment.type !== 'document' && attachment.modelOmission?.reason === 'invalid-image'
+							? 'invalid-image'
+							: attachment.type !== 'document' &&
+									attachment.modelOmission?.reason === 'provider-rejected'
+								? 'provider-rejected'
+								: 'budget',
 				})
 			}
 			continue
@@ -97,9 +105,11 @@ function collectRichOccurrences(messages: readonly Message[]): RichOccurrence[]
 				kind: block.type,
 				bytes: block.data.length,
 				reason:
-					block.type === 'image' && block.modelOmission?.reason === 'provider-rejected'
-						? 'provider-rejected'
-						: 'budget',
+					block.type === 'image' && block.modelOmission?.reason === 'invalid-image'
+						? 'invalid-image'
+						: block.type === 'image' && block.modelOmission?.reason === 'provider-rejected'
+							? 'provider-rejected'
+							: 'budget',
 			})
 		}
 	}
@@ -117,7 +127,9 @@ function appendMarkers(content: string, occurrences: readonly RichOccurrence[]):
 	const markers = occurrences.map((occurrence) =>
 		occurrence.reason === 'provider-rejected'
 			? rejectedUserImageMarker()
-			: userMarker(occurrence.kind),
+			: occurrence.reason === 'invalid-image'
+				? invalidUserImageMarker()
+				: userMarker(occurrence.kind),
 	)
 	return appendTextMarkers(content, markers)
 }
@@ -146,7 +158,9 @@ export function projectRequestRichContent(messages: Message[], maxBytes: number)
 	}
 
 	for (const occurrence of occurrences) {
-		if (occurrence.reason === 'provider-rejected') omit(occurrence)
+		if (occurrence.reason === 'provider-rejected' || occurrence.reason === 'invalid-image') {
+			omit(occurrence)
+		}
 	}
 
 	let total = occurrences.reduce(
@@ -189,7 +203,9 @@ export function projectRequestRichContent(messages: Message[], maxBytes: number)
 							text:
 								occurrence.reason === 'provider-rejected'
 									? rejectedToolImageMarker()
-									: toolMarker(occurrence.kind),
+									: occurrence.reason === 'invalid-image'
+										? invalidToolImageMarker()
+										: toolMarker(occurrence.kind),
 						}
 					: block
 			})
@@ -220,7 +236,10 @@ export function findSingleRequestImage(messages: readonly Message[]): RequestIma
 				}
 				if (attachment.type === 'document') continue
 				if (candidate === null) {
-					candidate = { data: attachment.data, mediaType: attachment.mediaType }
+					candidate = {
+						data: attachment.data,
+						mediaType: attachment.mediaType,
+					}
 				} else if (!sameImage(attachment, candidate)) {
 					return null
 				}
@@ -302,7 +321,10 @@ export function markProviderRejectedImage(
 				}
 				changed = true
 				count += 1
-				return { ...attachment, modelOmission: { reason: 'provider-rejected' as const } }
+				return {
+					...attachment,
+					modelOmission: { reason: 'provider-rejected' as const },
+				}
 			})
 			return changed ? { ...message, attachments } : message
 		}
@@ -318,7 +340,10 @@ export function markProviderRejectedImage(
 			}
 			changed = true
 			count += 1
-			return { ...block, modelOmission: { reason: 'provider-rejected' as const } }
+			return {
+				...block,
+				modelOmission: { reason: 'provider-rejected' as const },
+			}
 		})
 		return changed ? { ...message, content } : message
 	})

package/src/runtime/query/result.ts

@@ -140,6 +140,28 @@ export class ResultAssembler {
 		// later, discarding every field of it. `toPlatformError` is the
 		// projection that was written for exactly this and had no callers.
 		const failure = toPlatformError(err)
+		// The driver's classification and the operator explanation describe the
+		// throwable, not the terminal verdict. Compute them before choosing paused
+		// versus failed so a recoverable run does not become the one path that
+		// discards the reason and remedy a host needs in order to recover it.
+		const providerError = isProviderRequestError(err)
+			? {
+					kind: err.kind,
+					providerId: err.providerId,
+					...(err.providerCode !== undefined ? { providerCode: err.providerCode } : {}),
+					...(err.status !== undefined ? { status: err.status } : {}),
+					...(err.retryAfterMs !== undefined ? { retryAfterMs: err.retryAfterMs } : {}),
+					// The provider's own sentence, already truncated and scrubbed
+					// by the driver. Without it a host rendering this metadata
+					// knows a request was rejected but not which field, and has to
+					// re-parse prose to find out.
+					...(err.detail !== undefined ? { detail: err.detail } : {}),
+				}
+			: undefined
+		// Classification is structural; remediation is editorial. The catalog is
+		// optional because inventing advice for an uncharacterised failure is worse
+		// than presenting the reason alone.
+		const explanation = explainError(err) ?? undefined
 
 		// A transient failure that survived every in-turn recovery is not the
 		// same thing as a bad API key, and settling both as `failed` gave the
@@ -157,6 +179,9 @@ export class ResultAssembler {
 				runId: runMgr.id,
 				checkpointId: resumeFrom,
 				reason: errorMessage,
+				failure,
+				...(providerError ? { providerError } : {}),
+				...(explanation ? { explanation } : {}),
 			})
 			yield* drainPending()
 
@@ -177,35 +202,12 @@ export class ResultAssembler {
 			return
 		}
 
-		// The driver's classification, carried onto the run so a host can
-		// branch on WHAT failed without re-parsing a sentence.
-		const providerError = isProviderRequestError(err)
-			? {
-					kind: err.kind,
-					providerId: err.providerId,
-					...(err.providerCode !== undefined ? { providerCode: err.providerCode } : {}),
-					...(err.status !== undefined ? { status: err.status } : {}),
-					...(err.retryAfterMs !== undefined ? { retryAfterMs: err.retryAfterMs } : {}),
-					// The provider's own sentence, already truncated and scrubbed
-					// by the driver. Without it a host rendering this metadata
-					// knows a request was rejected but not which field, and has to
-					// go re-parse `error` to find out — which is exactly the
-					// re-parsing the line above says this exists to avoid.
-					...(err.detail !== undefined ? { detail: err.detail } : {}),
-				}
-			: undefined
 		runMgr.markFailed(errorMessage, providerError)
 
 		if (planManager.isActive) {
 			planManager.failPlan(errorMessage)
 		}
 
-		// The classification says what kind of failure it is; the catalog
-		// says what a person should do about it. Keeping them separate is the
-		// point — classification is structural and belongs at the boundary,
-		// remediation is editorial and belongs in a list a human appends to.
-		const explanation = explainError(err) ?? undefined
-
 		// Same terminal-verdict recording as the success path in completeRun —
 		// see LOG-14, design §5. Placed AFTER the early `resumeFrom !== undefined`
 		// return above, so a paused/resumable run is never audited as 'failure'.