@namzu/sdk 31.1.0 → 33.0.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'
@@ -302,6 +304,11 @@ export interface QueryParams {
 	 * store REFUSES rather than dropping the attachment.
 	 */
 	attachmentStore?: import('../../store/attachment/index.js').AttachmentStore
+	/**
+	 * Maximum wall-clock time for resolving the run's stored attachments.
+	 * Defaults to one minute; `0` retains the prior unbounded wait.
+	 */
+	attachmentResolveTimeoutMs?: number
 
 	/**
 	 * How this run reaches the web.
@@ -1192,6 +1199,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		resolvedInitialMessages = [
 			...(await resolveAttachments(seeded, params.attachmentStore, {
 				signal: params.signal,
+				timeoutMs: params.attachmentResolveTimeoutMs,
 			})),
 		]
 		params.signal?.throwIfAborted()
@@ -1361,6 +1369,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
@@ -1369,6 +1411,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
@@ -1454,6 +1499,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()
@@ -1614,6 +1661,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()
@@ -1654,6 +1709,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
@@ -1800,12 +1857,6 @@ 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,
 		servingMember: () => serving.current,
@@ -2575,6 +2626,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

@@ -22,8 +22,8 @@ import type { CostInfo, TokenUsage } from '../../../types/common/index.js'
 import type { MessageId } from '../../../types/ids/index.js'
 import {
 	createAssistantMessage,
+	createRuntimeContextMessage,
 	createSystemMessage,
-	createUserMessage,
 } from '../../../types/message/index.js'
 import type { ToolChoice } from '../../../types/provider/chat.js'
 import { classifyProviderError } from '../../../types/provider/errors.js'
@@ -47,6 +47,8 @@ import type { ToolCallOutcome } from '../executor.js'
 import { applyLifecycleHookResults } from '../plugin-hooks.js'
 import {
 	DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
+	type RequestImageIdentity,
+	markProviderRejectedImage,
 	projectRequestRichContent,
 } from '../request-rich-content.js'
 import { formatSteeringNote } from '../steering.js'
@@ -57,6 +59,7 @@ import type { IterationContext } from './phases/index.js'
 import { runPlanGate } from './phases/plan.js'
 import { runToolReview } from './phases/tool-review.js'
 import { refreshWorkingMemory } from './phases/working-memory.js'
+import { streamWithProviderRejectedImageRecovery } from './provider-rejected-image.js'
 import { streamProviderTurn } from './stream-turn.js'
 
 export type { IterationContext } from './phases/index.js'
@@ -394,8 +397,9 @@ export class IterationOrchestrator {
 					const baseMessages = forceFinalize
 						? [
 								...runMgr.messages,
-								createUserMessage(
+								createRuntimeContextMessage(
 									'[SYSTEM] You are approaching your resource limits. Provide your final, comprehensive response now based on everything you have gathered so far. Do not request any more tool calls.',
+									'limit-finalization',
 								),
 							]
 						: runMgr.messages
@@ -589,6 +593,9 @@ export class IterationOrchestrator {
 						this.ctx.log,
 						iterSpan,
 						stepMessageId,
+						{
+							onAccepted: (identity) => this.acceptProviderRejectedImage(identity),
+						},
 					)
 					stepResponse = response
 
@@ -880,7 +887,9 @@ export class IterationOrchestrator {
 								[NAMZU.ITERATION]: iterationNum,
 								[GENAI.USAGE_OUTPUT_TOKENS]: response.usage.completionTokens,
 							})
-							runMgr.pushMessage(createUserMessage(AUTO_CONTINUATION_USER_MESSAGE))
+							runMgr.pushMessage(
+								createRuntimeContextMessage(AUTO_CONTINUATION_USER_MESSAGE, 'auto-continuation'),
+							)
 							await this.ctx.emitEvent({
 								type: 'iteration_completed',
 								runId: runMgr.id,
@@ -912,7 +921,9 @@ export class IterationOrchestrator {
 								'namzu.retry.attempt': attempt,
 								'namzu.runtime.limit': limit,
 							})
-							runMgr.pushMessage(createUserMessage(STRUCTURED_OUTPUT_REPROMPT))
+							runMgr.pushMessage(
+								createRuntimeContextMessage(STRUCTURED_OUTPUT_REPROMPT, 'structured-output'),
+							)
 							await this.ctx.emitEvent({
 								type: 'iteration_completed',
 								runId: runMgr.id,
@@ -955,7 +966,7 @@ export class IterationOrchestrator {
 									'namzu.retry.attempt': attempt,
 									'namzu.runtime.limit': limit,
 								})
-								runMgr.pushMessage(createUserMessage(review.feedback))
+								runMgr.pushMessage(createRuntimeContextMessage(review.feedback, 'answer-review'))
 								await this.ctx.emitEvent({
 									type: 'iteration_completed',
 									runId: runMgr.id,
@@ -1188,7 +1199,9 @@ export class IterationOrchestrator {
 							[NAMZU.ITERATION]: iterationNum,
 							'namzu.runtime.tasks': unheard.map((h) => h.taskId),
 						})
-						runMgr.pushMessage(createUserMessage(formatCompletionNotification(unheard)))
+						runMgr.pushMessage(
+							createRuntimeContextMessage(formatCompletionNotification(unheard), 'task-completion'),
+						)
 					}
 
 					// The same seam, for the two channels that could accept text
@@ -1388,7 +1401,9 @@ export class IterationOrchestrator {
 		const arrived = this.ctx.completionInbox.drain()
 		if (arrived.length === 0) return false
 
-		this.ctx.runMgr.pushMessage(createUserMessage(formatCompletionNotification(arrived)))
+		this.ctx.runMgr.pushMessage(
+			createRuntimeContextMessage(formatCompletionNotification(arrived), 'task-completion'),
+		)
 		await this.ctx.emitEvent({
 			type: 'iteration_completed',
 			runId: this.ctx.runMgr.id,
@@ -1467,7 +1482,9 @@ export class IterationOrchestrator {
 			[NAMZU.RUN_ID]: this.ctx.runMgr.id,
 			'namzu.runtime.tasks': unheard.map((h) => h.taskId),
 		})
-		this.ctx.runMgr.pushMessage(createUserMessage(formatCompletionNotification(unheard)))
+		this.ctx.runMgr.pushMessage(
+			createRuntimeContextMessage(formatCompletionNotification(unheard), 'task-completion'),
+		)
 	}
 
 	/**
@@ -1633,7 +1650,9 @@ export class IterationOrchestrator {
 		// guidance from a turn that had no result to attach it to.
 		const stranded = this.ctx.steering?.drain()
 		if (stranded) {
-			this.ctx.runMgr.pushMessage(createUserMessage(formatSteeringNote(stranded)))
+			this.ctx.runMgr.pushMessage(
+				createRuntimeContextMessage(formatSteeringNote(stranded), 'steering'),
+			)
 		}
 
 		return queued.length + (stranded ? 1 : 0)
@@ -1922,6 +1941,23 @@ export class IterationOrchestrator {
 			.some((t) => t.state !== 'completed' && t.state !== 'failed' && t.state !== 'canceled')
 	}
 
+	private async acceptProviderRejectedImage(identity: RequestImageIdentity): Promise<void> {
+		const repaired = markProviderRejectedImage(this.ctx.runMgr.messages, identity)
+		if (repaired.count === 0) {
+			throw new Error('Provider-rejected image recovery could not find its durable source image')
+		}
+		this.ctx.runMgr.replaceMessages(repaired.messages)
+		await this.ctx.emitEvent?.({
+			type: 'message_history_repaired',
+			runId: this.ctx.runMgr.id,
+			source: 'provider-rejected-image',
+			duplicateToolResultsRemoved: 0,
+			orphanedToolResultsRemoved: 0,
+			syntheticToolResultsInserted: 0,
+			providerRejectedImagesSuppressed: repaired.count,
+		})
+	}
+
 	private async requestFinalResponse(model: string, reason: StopReason): Promise<void> {
 		const lastAssistant = [...this.ctx.runMgr.messages]
 			.reverse()
@@ -1941,8 +1977,9 @@ export class IterationOrchestrator {
 		try {
 			const finalHistory = [
 				...this.ctx.runMgr.messages,
-				createUserMessage(
+				createRuntimeContextMessage(
 					`[SYSTEM] Run is ending due to ${reason}. You MUST provide a final response now summarizing all your findings and work so far. Do not use any tools.`,
+					'limit-finalization',
 				),
 			]
 			const finalMessages = projectRequestRichContent(
@@ -1964,26 +2001,29 @@ export class IterationOrchestrator {
 				model: requestedMember.model ?? model,
 				chainIndex: requestedMember.index,
 			}
+			const finalParams = {
+				model,
+				providerRoute: requestedRoute,
+				messages: finalMessages,
+				tools: finalTools.length > 0 ? finalTools : undefined,
+				...(finalEnforced ? { enforceToolInputSchema: finalEnforced } : {}),
+				toolChoice: finalTools.length > 0 ? 'none' : undefined,
+				temperature: this.ctx.runConfig.temperature,
+				maxTokens: this.ctx.runConfig.maxResponseTokens,
+				cacheControl: { type: 'auto' },
+				...(this.ctx.runConfig.thinking ? { thinking: this.ctx.runConfig.thinking } : {}),
+				// This turn is a hand-maintained duplicate of the one above, which
+				// is exactly the shape a field goes missing from — so it is tested
+				// separately rather than assumed to have been kept in step.
+				...(this.ctx.runConfig.effort ? { effort: this.ctx.runConfig.effort } : {}),
+				// Cancellable too: a Stop during the closing summary must not
+				// stream to completion.
+				signal: this.ctx.abortController.signal,
+			} satisfies import('../../../types/provider/index.js').ChatCompletionParams
 			const response = await collectChatCompletion(
-				this.ctx.provider.chatStream({
-					model,
-					providerRoute: requestedRoute,
-					messages: finalMessages,
-					tools: finalTools.length > 0 ? finalTools : undefined,
-					...(finalEnforced ? { enforceToolInputSchema: finalEnforced } : {}),
-					toolChoice: finalTools.length > 0 ? 'none' : undefined,
-					temperature: this.ctx.runConfig.temperature,
-					maxTokens: this.ctx.runConfig.maxResponseTokens,
-					cacheControl: { type: 'auto' },
-					...(this.ctx.runConfig.thinking ? { thinking: this.ctx.runConfig.thinking } : {}),
-					// This turn is a hand-maintained duplicate of the one above, which
-					// is exactly the shape a field goes missing from — so it is tested
-					// separately rather than assumed to have been kept in step.
-					...(this.ctx.runConfig.effort ? { effort: this.ctx.runConfig.effort } : {}),
-					// Cancellable too: a Stop during the closing summary must not
-					// stream to completion.
-					signal: this.ctx.abortController.signal,
-				}),
+				streamWithProviderRejectedImageRecovery(this.ctx.provider, finalParams, (identity) =>
+					this.acceptProviderRejectedImage(identity),
+				),
 			)
 
 			const servingMember = this.ctx.servingMember?.() ?? requestedMember

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

@@ -2,7 +2,7 @@ import { serializeState } from '../../../../compaction/serializer.js'
 import { NAMZU } from '../../../../constants/telemetry/index.js'
 import type { AdvisoryRequest, TriggerEvaluationState } from '../../../../types/advisory/index.js'
 import { toolResultToText } from '../../../../types/message/content.js'
-import { createUserMessage } from '../../../../types/message/index.js'
+import { createRuntimeContextMessage } from '../../../../types/message/index.js'
 import type { ChatCompletionResponse } from '../../../../types/provider/index.js'
 import { toErrorMessage } from '../../../../utils/error.js'
 import type { IterationContext } from './context.js'
@@ -169,7 +169,7 @@ export async function runAdvisoryPhase(
 
 		sections.push('</advisory-result>')
 
-		ctx.runMgr.pushMessage(createUserMessage(sections.join('\n')))
+		ctx.runMgr.pushMessage(createRuntimeContextMessage(sections.join('\n'), 'advisory'))
 
 		ctx.log.info('Advisory phase completed', {
 			[NAMZU.RUN_ID]: ctx.runMgr.id,

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/iteration/provider-rejected-image.ts

@@ -0,0 +1,106 @@
+import { isProviderRequestError } from '../../../provider/errors.js'
+import type {
+	ChatCompletionParams,
+	LLMProvider,
+	StreamChunk,
+} from '../../../types/provider/index.js'
+import {
+	type RequestImageIdentity,
+	findSingleRequestImage,
+	projectRequestWithoutImage,
+} from '../request-rich-content.js'
+
+const IMAGE_REJECTION_PATTERNS: readonly RegExp[] = [
+	/\binvalid[_ -]?image\b/i,
+	/\bimage\b.{0,100}\b(?:cannot|could not|failed to)\s+(?:be\s+)?(?:decoded|processed|loaded|parsed|read)\b/i,
+	/\b(?:cannot|could not|failed to)\s+(?:decode|process|load|parse|read)\b.{0,100}\bimage\b/i,
+	/\bimage\b.{0,100}\b(?:malformed|corrupt|unsupported format)\b/i,
+]
+
+type ImageRejectionConfidence = 'server-confirmed' | 'heuristic'
+
+function classifyProviderRejectedImageError(error: unknown): ImageRejectionConfidence | null {
+	if (!isProviderRequestError(error) || error.kind !== 'bad_request') return null
+	if (error.status === 400 && error.providerCode === 'invalid_image') return 'server-confirmed'
+	const detail = error.detail ?? error.message
+	return IMAGE_REJECTION_PATTERNS.some((pattern) => pattern.test(detail)) ? 'heuristic' : null
+}
+
+export function isProviderRejectedImageError(error: unknown): boolean {
+	return classifyProviderRejectedImageError(error) !== null
+}
+
+function isAcceptedChunk(chunk: StreamChunk): boolean {
+	if (chunk.retry !== undefined || chunk.fallback !== undefined || chunk.error !== undefined) {
+		return false
+	}
+	return Boolean(
+		chunk.delta.content ||
+			chunk.delta.toolCalls?.length ||
+			chunk.delta.toolCallEnd ||
+			chunk.delta.reasoning ||
+			chunk.delta.citation ||
+			chunk.finishReason !== undefined ||
+			chunk.usage !== undefined ||
+			chunk.replayState !== undefined,
+	)
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+	if (signal?.aborted) throw signal.reason
+}
+
+/**
+ * Retry one provider-invalid request without its only distinct image.
+ *
+ * The callback is the durable commit point for an HTTP 400 carrying the exact
+ * provider code `invalid_image`. It runs only after the retry has produced an
+ * accepted chunk or reached a clean EOF. A legacy phrase can still recover the
+ * current request, but cannot assert durable server proof.
+ */
+export async function* streamWithProviderRejectedImageRecovery(
+	provider: LLMProvider,
+	params: ChatCompletionParams,
+	onAccepted: (identity: RequestImageIdentity) => Promise<void>,
+): AsyncIterable<StreamChunk> {
+	const candidate = findSingleRequestImage(params.messages)
+	if (candidate === null) {
+		yield* provider.chatStream(params)
+		return
+	}
+
+	let produced = false
+	let confidence: ImageRejectionConfidence | null = null
+	try {
+		for await (const chunk of provider.chatStream(params)) {
+			if (isAcceptedChunk(chunk)) produced = true
+			yield chunk
+		}
+		return
+	} catch (error) {
+		throwIfAborted(params.signal)
+		confidence = classifyProviderRejectedImageError(error)
+		if (produced || confidence === null) throw error
+	}
+
+	throwIfAborted(params.signal)
+	const retryParams: ChatCompletionParams = {
+		...params,
+		messages: projectRequestWithoutImage(params.messages, candidate),
+	}
+	let accepted = false
+	let retryReportedError = false
+	for await (const chunk of provider.chatStream(retryParams)) {
+		if (chunk.error !== undefined) retryReportedError = true
+		if (!accepted && isAcceptedChunk(chunk)) {
+			throwIfAborted(params.signal)
+			if (confidence === 'server-confirmed') await onAccepted(candidate)
+			accepted = true
+		}
+		yield chunk
+	}
+	if (!accepted && !retryReportedError) {
+		throwIfAborted(params.signal)
+		if (confidence === 'server-confirmed') await onAccepted(candidate)
+	}
+}