@namzu/sdk 49.0.0 → 50.1.0

package/src/runtime/query/index.ts

@@ -59,6 +59,7 @@ import {
 import type { CheckpointId, MessageId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { InvocationState } from '../../types/invocation/index.js'
 import type { MemoryStore } from '../../types/memory/index.js'
+import type { DurableInboundSource } from '../../types/message/inbound-delivery.js'
 import {
 	type AssistantMessage,
 	type Message,
@@ -733,6 +734,9 @@ export interface QueryParams {
 	 */
 	waitForInbound?: (signal: AbortSignal) => Promise<void>
 
+	/** Durable host input: normal append, flush and exact acknowledgement before inference. Requires sessionLog. */
+	durableInbound?: DurableInboundSource
+
 	/**
 	 * Live project policy for this turn. Unlike `inboundMessages`, snapshot
 	 * replacement is durable state and never implies another model turn.
@@ -956,6 +960,9 @@ function withOwnedResumeOutcomes(
 }
 
 export async function* query(params: QueryParams): AsyncGenerator<SessionEvent, Turn> {
+	if (params.durableInbound && !params.sessionLog) {
+		throw new Error('durableInbound requires an explicit sessionLog and its active writer.')
+	}
 	const prepared = await prepareTurn(params)
 	const {
 		turnConfig,
@@ -1144,9 +1151,11 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 		// invalidate the whole prompt cache for the rest of the turn — the same
 		// reason the forced-final turn keeps its tools array and uses
 		// `toolChoice: 'none'` instead of dropping it.
-		if (params.structuredOutput && params.structuredOutput.mode !== 'native') {
-			addRuntimeTool(createStructuredOutputTool(params.structuredOutput.schema), 'active')
-		}
+		const structuredOutputTool =
+			params.structuredOutput && params.structuredOutput.mode !== 'native'
+				? createStructuredOutputTool(params.structuredOutput.schema)
+				: undefined
+		if (structuredOutputTool) addRuntimeTool(structuredOutputTool, 'active')
 
 		for (const tool of advisoryToolDefs) addRuntimeTool(tool, 'active')
 
@@ -1356,6 +1365,9 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			{
 				skillGrants,
 				tools: toolManager,
+				...(params.structuredOutput?.toolResultRetention === 'durable' && structuredOutputTool
+					? { durableStructuredOutputTool: structuredOutputTool }
+					: {}),
 				sessionId: ctx.sessionId,
 				turnId: ctx.turnId,
 				workingDirectory: ctx.cwd,
@@ -1484,6 +1496,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			basePrompt: params.basePrompt,
 			tools: toolManager,
 			allowedTools: effectiveAllowedTools,
+			sandboxed: params.sandboxProvider !== undefined,
 			runtimeContext: params.runtimeContext,
 			contributions: promptContributions,
 		})
@@ -1595,6 +1608,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			activityStore: ctx.activityStore,
 			emitEvent: eventTranslator.emitEvent,
 			drainPending: () => eventTranslator.drainPending(),
+			onPendingEvents: (listener) => eventTranslator.onPendingEvents(listener),
 			abortController: ctx.abortController,
 			log: ctx.log,
 			// Read through the box on every call, so a swap lands on the next
@@ -1622,6 +1636,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			...(params.repeatCallAdvisory === false ? {} : { repeatCalls: new RepeatCallTracker() }),
 			compactionConfig,
 			...(params.inboundMessages ? { inboundMessages: params.inboundMessages } : {}),
+			...(params.durableInbound ? { durableInbound: params.durableInbound } : {}),
 			...(params.resumeFromCheckpoint ? { resumedInput: queuedForThisRun } : {}),
 			...(params.waitForInbound ? { waitForInbound: params.waitForInbound } : {}),
 			...(params.projectInstructionContext
@@ -1845,6 +1860,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 					basePrompt: contextLevel === 'full' ? params.basePrompt : undefined,
 					tools: toolManager,
 					allowedTools: effectiveAllowedTools,
+					sandboxed: params.sandboxProvider !== undefined,
 					runtimeContext: params.runtimeContext,
 					contributions: promptContributions,
 				}
@@ -2148,6 +2164,9 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 				// boundaries are not all cooperative and must not regain withdrawn
 				// authority merely because the turn record still had to be created.
 				ctx.abortController.signal.throwIfAborted()
+				// A restored assistant/tool pair cannot be split by a user-role arrival.
+				// Its pending results are applied below, before the loop drains input.
+				if (!pendingResume) await iterationOrchestrator.deliverInitialDurable()
 
 				// Handed over here, and the position is load-bearing in three
 				// directions. It has to follow `wirePlanManager`, or a host that
@@ -2410,13 +2429,14 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 						}
 					}
 
-					await applyPendingResume(
+					const resumedBatch = await applyPendingResume(
 						pendingResume,
 						ctx.recorder,
 						toolExecutor,
 						recoveredResults,
 						pendingResumeAssistantId,
 					)
+					iterationOrchestrator.setResumedToolResults(resumedBatch.results)
 					yield* eventTranslator.drainPending()
 				}
 

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

@@ -10,6 +10,7 @@ import {
 	DEFAULT_STRUCTURED_OUTPUT_RETRIES,
 	STRUCTURED_OUTPUT_REPROMPT,
 } from '../../../constants/tools/index.js'
+import { withStreamedMessageIdentity } from '../../../manager/session/streamed-message-identity.js'
 import { renderSkillsSection } from '../../../persona/assembler.js'
 import { resolveProviderCapabilities } from '../../../provider/capabilities.js'
 import { collectChatCompletion } from '../../../provider/collect-chat-completion.js'
@@ -48,7 +49,9 @@ import type { LLMToolSchema } from '../../../types/tool/index.js'
 import { toErrorMessage } from '../../../utils/error.js'
 import { stableDigest } from '../../../utils/hash.js'
 import { generateMessageId } from '../../../utils/id.js'
+import { parseStructuredResultJson } from '../../../utils/structured-result-json.js'
 import { createCallbackInference } from '../callback-inference.js'
+import { deliverDurableInbound } from '../durable-inbound.js'
 import type { ToolCallOutcome } from '../executor.js'
 import { projectObservationContext } from '../observation-context.js'
 import { applyLifecycleHookResults } from '../plugin-hooks.js'
@@ -65,7 +68,11 @@ import {
 } from '../request-rich-content.js'
 import { formatSteeringNote, isOperatorUserMessage } from '../steering.js'
 import { parseNativeCandidate } from './native-output.js'
-import { holdForOutstandingWork, settleOutstandingWork } from './outstanding-work.js'
+import {
+	drainArrivedTaskCompletions,
+	holdForOutstandingWork,
+	settleOutstandingWork,
+} from './outstanding-work.js'
 import { runAdvisoryPhase } from './phases/advisory.js'
 import { runIterationCheckpoint } from './phases/checkpoint.js'
 import {
@@ -162,7 +169,12 @@ export class IterationOrchestrator {
 	private projectObservations(messages: Message[]): Message[] {
 		const config = this.ctx.compactionConfig
 		return config && config.strategy !== 'disabled' && config.deduplicateObservations !== false
-			? projectObservationContext(messages, this.ctx.tools, config.preserveToolResultsFrom)
+			? projectObservationContext(
+					messages,
+					this.ctx.tools,
+					config.preserveToolResultsFrom,
+					(call, message) => this.ctx.toolExecutor.recordedObservationKey(call, message),
+				)
 			: messages
 	}
 	/** Rich tool blocks already reported; durable history is scanned every turn. */
@@ -184,6 +196,9 @@ export class IterationOrchestrator {
 	private stopDeferredForOutstandingWork = false
 	/** One current input, independent of the compactable history array. */
 	private latestUserMessage: UserMessage | undefined
+	private initialDurableDelivered = false
+	private resumedToolResults: readonly ToolCallOutcome[] = []
+	private toolStructuredCounterHydrated = false
 
 	constructor(ctx: IterationContext) {
 		this.ctx = {
@@ -196,6 +211,11 @@ export class IterationOrchestrator {
 		ctx.checkpointMgr.setAnswerReviewAttemptsSource?.(() => this.answerReviewAttempts)
 		ctx.checkpointMgr.setStructuredReviewAttemptsSource?.(() => this.structuredReviewAttempts)
 		ctx.checkpointMgr.setNativeStructuredAttemptsSource?.(() => this.nativeStructuredAttempts)
+		ctx.checkpointMgr.setToolStructuredAttemptsSource?.(() =>
+			this.toolStructuredCounterHydrated
+				? this.toolStructuredAttempts
+				: (ctx.checkpointMgr.restoredToolStructuredAttempts ?? 0),
+		)
 		if (ctx.structuredOutput?.mode === 'native') {
 			const limit = ctx.structuredOutput.maxRetries
 			if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 0))
@@ -209,6 +229,11 @@ export class IterationOrchestrator {
 		)
 			throw new RangeError('Unknown structuredOutput.mode')
 		const maxReviews = ctx.structuredOutput?.maxReviews
+		const retention = ctx.structuredOutput?.toolResultRetention
+		if (retention !== undefined && !['receipt', 'durable'].includes(retention))
+			throw new RangeError('Unknown structuredOutput.toolResultRetention')
+		if (retention === 'durable' && ctx.structuredOutput?.mode === 'native')
+			throw new RangeError('structuredOutput.toolResultRetention: durable requires tool mode')
 		if (maxReviews !== undefined && (!Number.isSafeInteger(maxReviews) || maxReviews < 0))
 			throw new RangeError('structuredOutput.maxReviews must be a nonnegative safe integer')
 		if (
@@ -293,15 +318,35 @@ export class IterationOrchestrator {
 		this.ctx = { ...this.ctx, rootSpan: span }
 	}
 
+	/** Fresh input is recorded before guards; restored tool batches must finish first. */
+	async deliverInitialDurable(): Promise<void> {
+		if (this.initialDurableDelivered) return
+		await deliverDurableInbound(
+			this.ctx.recorder,
+			this.ctx.durableInbound,
+			this.ctx.abortController.signal,
+		)
+		this.initialDurableDelivered = true
+	}
+
+	/** A restored pending batch must answer every owned call before consuming its correction. */
+	setResumedToolResults(results: readonly ToolCallOutcome[]): void {
+		this.resumedToolResults = results
+	}
+
 	async *runLoop(): AsyncGenerator<SessionEvent> {
 		const { turnConfig, recorder } = this.ctx
 		const { model } = turnConfig
 		const tracer = getTracer()
+		// Initial durable input arrives before checkpoints, plan gates or inference.
+		await this.deliverInitialDurable()
 		// Resume hydration happens after construction, before the loop starts.
 		this.latestUserMessage = this.ctx.checkpointMgr.restoredLatestUserMessage
 		this.answerReviewAttempts = this.ctx.checkpointMgr.restoredAnswerReviewAttempts ?? 0
 		this.structuredReviewAttempts = this.ctx.checkpointMgr.restoredStructuredReviewAttempts ?? 0
 		this.nativeStructuredAttempts = this.ctx.checkpointMgr.restoredNativeStructuredAttempts ?? 0
+		this.toolStructuredAttempts = this.ctx.checkpointMgr.restoredToolStructuredAttempts ?? 0
+		this.toolStructuredCounterHydrated = true
 		if (!this.latestUserMessage) {
 			for (const message of recorder.messages) this.rememberUserMessage(message, false)
 		}
@@ -309,6 +354,9 @@ export class IterationOrchestrator {
 		// Only known post-checkpoint arrivals may supersede it, never an old
 		// retained user turn encountered while scanning restored history.
 		for (const message of this.ctx.resumedInput ?? []) this.rememberUserMessage(message)
+		const resumedToolResults = this.resumedToolResults
+		this.resumedToolResults = []
+		await this.recordToolStructuredFailure(resumedToolResults, recorder.currentIteration)
 
 		// What a recoverable failure pauses on when it lands before this
 		// loop wrote a checkpoint of its own: without it a 429 on the first
@@ -328,9 +376,6 @@ export class IterationOrchestrator {
 		// succeeded, which is the evidence that the turn is no longer stuck.
 		let overflowRelieved = false
 
-		const planSignal = yield* runPlanGate(this.ctx)
-		if (planSignal === 'stop') return
-
 		// A `finally` rather than a line at each exit, for the reason written
 		// beside `iterSpan.end()` below: this loop leaves by eight `break`s,
 		// two `return`s and a `throw`, and a rule every future edit has to
@@ -341,19 +386,17 @@ export class IterationOrchestrator {
 		// A `finally` also covers a generator abandoned by its consumer, which
 		// no post-loop block reaches.
 		try {
+			// Restored exhaustion precedes plan gates and any auxiliary inference.
+			if (this.stopForStructuredRetryExhaustion()) return
+			const planSignal = yield* runPlanGate(this.ctx)
+			if (planSignal === 'stop') return
 			while (true) {
 				if (this.ctx.abortController.signal.aborted) {
 					recorder.setStopReason('cancelled')
 					recorder.markCancelled()
 					break
 				}
-				if (
-					this.ctx.structuredOutput?.mode === 'native' &&
-					this.nativeStructuredAttempts > this.structuredOutputRetryLimit()
-				) {
-					recorder.setStopReason('structured_output_failed')
-					break
-				}
+				if (this.stopForStructuredRetryExhaustion()) break
 				if (
 					this.ctx.reviewAnswer &&
 					this.answerReviewAttempts > (this.ctx.maxAnswerReviews ?? DEFAULT_ANSWER_REVIEW_LIMIT)
@@ -987,22 +1030,25 @@ export class IterationOrchestrator {
 					// with the turn they belong to. Trimming therefore removes both;
 					// retaining them gives the target adapter enough evidence to
 					// validate native replay against the exact serving route.
-					const assistantMsg = createAssistantMessage(
-						response.message.content,
-						forceFinalize ? undefined : response.message.toolCalls,
-						response.message.reasoning,
-						// Rides with the turn it belongs to, like reasoning does, so
-						// trimming or compacting the turn takes its evidence with it
-						// rather than leaving citations pointing at prose that is gone.
-						response.message.citations,
-						{
-							type: 'model',
-							...servedBy,
-							...(response.message.replayState !== undefined
-								? { replayState: response.message.replayState }
-								: {}),
-						},
-						response.message.textParts,
+					const assistantMsg = withStreamedMessageIdentity(
+						createAssistantMessage(
+							response.message.content,
+							forceFinalize ? undefined : response.message.toolCalls,
+							response.message.reasoning,
+							// Rides with the turn it belongs to, like reasoning does, so
+							// trimming or compacting the turn takes its evidence with it
+							// rather than leaving citations pointing at prose that is gone.
+							response.message.citations,
+							{
+								type: 'model',
+								...servedBy,
+								...(response.message.replayState !== undefined
+									? { replayState: response.message.replayState }
+									: {}),
+							},
+							response.message.textParts,
+						),
+						messageId,
 					)
 					recorder.pushMessage(assistantMsg)
 					if (this.ctx.advisoryCtx && requestMessages) {
@@ -1175,7 +1221,7 @@ export class IterationOrchestrator {
 									const changed = yield* holdForOutstandingWork(this.ctx, iterationNum, false, () =>
 										this.deliverInbound(),
 									)
-									const inbound = this.deliverInbound()
+									const inbound = await this.deliverInbound()
 									if (changed || inbound > 0) continue
 								}
 								if (this.ctx.abortController.signal.aborted) {
@@ -1196,6 +1242,21 @@ export class IterationOrchestrator {
 							continue
 						}
 
+						// Missing output and rejected model arguments share one durable
+						// correction allowance, including prose cut off by the output cap.
+						if (!forceFinalize && this.needsStructuredOutput()) {
+							await this.recordToolStructuredCorrection(iterationNum)
+							await this.ctx.emitEvent({
+								type: 'iteration_completed',
+								turnId: recorder.turnId,
+								iteration: iterationNum,
+								hasToolCalls: false,
+							})
+							yield* this.ctx.drainPending()
+							if (this.stopForStructuredRetryExhaustion()) break
+							continue
+						}
+
 						const hasContent =
 							response.message.content !== null && response.message.content.length > 0
 
@@ -1246,40 +1307,6 @@ export class IterationOrchestrator {
 							continue
 						}
 
-						// The model tried to finish in prose while a structured
-						// output was demanded. Send it back with the schema error
-						// rather than returning an unusable result — this is the
-						// re-prompt half, and it is bounded so a model that cannot
-						// satisfy the schema fails loudly instead of looping.
-						if (!forceFinalize && this.needsStructuredOutput()) {
-							const attempt = ++this.structuredOutputAttempts
-							const limit = this.structuredOutputRetryLimit()
-							if (attempt > limit) {
-								this.ctx.log.warn('Structured output not produced within its retries', {
-									[NAMZU.TURN_ID]: recorder.turnId,
-									'namzu.runtime.attempts': attempt - 1,
-								})
-								recorder.setStopReason('structured_output_failed')
-								break
-							}
-							this.ctx.log.info('Re-prompting for structured output', {
-								[NAMZU.TURN_ID]: recorder.turnId,
-								'namzu.retry.attempt': attempt,
-								'namzu.runtime.limit': limit,
-							})
-							recorder.pushMessage(
-								createRuntimeContextMessage(STRUCTURED_OUTPUT_REPROMPT, 'structured-output'),
-							)
-							await this.ctx.emitEvent({
-								type: 'iteration_completed',
-								turnId: recorder.turnId,
-								iteration: iterationNum,
-								hasToolCalls: false,
-							})
-							yield* this.ctx.drainPending()
-							continue
-						}
-
 						// Let the host judge the ANSWER and hand back work.
 						//
 						// The stop predicate is only consulted after tools ran, so
@@ -1371,7 +1398,7 @@ export class IterationOrchestrator {
 						// After the outstanding-work hold above, so a delivery
 						// does not race a worker still finishing, and before the
 						// settle below, which is the last moment it can matter.
-						if (!forceFinalize && this.deliverInbound() > 0) {
+						if (!forceFinalize && (await this.deliverInbound()) > 0) {
 							await this.ctx.emitEvent({
 								type: 'iteration_completed',
 								turnId: recorder.turnId,
@@ -1456,6 +1483,10 @@ export class IterationOrchestrator {
 					if (reviewOutcome.decision === 'stop') {
 						return
 					}
+					const needsCorrection = await this.recordToolStructuredFailure(
+						reviewOutcome.results,
+						iterationNum,
+					)
 
 					// A tool asked for a person. The whole batch is committed; the
 					// turn parks here rather than asking the model what to do about
@@ -1467,6 +1498,17 @@ export class IterationOrchestrator {
 					if (reviewOutcome.decision === 'rejected') {
 						continue
 					}
+					if (needsCorrection) {
+						await this.ctx.emitEvent({
+							type: 'iteration_completed',
+							turnId: recorder.turnId,
+							iteration: iterationNum,
+							hasToolCalls: true,
+						})
+						yield* this.ctx.drainPending()
+						if (this.stopForStructuredRetryExhaustion()) break
+						continue
+					}
 
 					// A successful `structured_output` call IS the answer, so the
 					// run ends here rather than paying for another turn whose only
@@ -1516,7 +1558,7 @@ export class IterationOrchestrator {
 							break
 						}
 						if (!forceFinalize) {
-							const inbound = this.deliverInbound()
+							const inbound = await this.deliverInbound()
 							// Tool-result steering may already have been delivered by
 							// runToolReview. Its candidate still answers the older input.
 							if (inbound > 0 || this.latestUserMessage !== operatorInputAtDispatch) continue
@@ -1642,7 +1684,7 @@ export class IterationOrchestrator {
 					// Placed beside the advisory phase deliberately: that is the
 					// established seam for putting a user message in after tool
 					// results and before the next turn.
-					const unheard = this.ctx.completionInbox?.drain() ?? []
+					const unheard = await drainArrivedTaskCompletions(this.ctx)
 					if (unheard.length > 0) {
 						this.ctx.log.info('Delivering unawaited task completions', {
 							[NAMZU.TURN_ID]: recorder.turnId,
@@ -1658,7 +1700,7 @@ export class IterationOrchestrator {
 					// and never deliver it. Placed here rather than at the top of
 					// the next iteration so a message queued during THIS turn is
 					// in the history the next request is built from.
-					this.deliverInbound()
+					await this.deliverInbound()
 
 					await runAdvisoryPhase(this.ctx, iterationNum, response, this.getAdvisoryTurnContext())
 
@@ -1883,7 +1925,7 @@ export class IterationOrchestrator {
 		}
 	}
 
-	private deliverInbound(): number {
+	private async deliverInbound(): Promise<number> {
 		const queued = this.ctx.inboundMessages?.() ?? []
 		for (const message of queued) {
 			this.ctx.recorder.pushMessage(message)
@@ -1900,7 +1942,12 @@ export class IterationOrchestrator {
 			this.rememberUserMessage(createRuntimeContextMessage(stranded, 'steering'))
 		}
 
-		return queued.length + (stranded ? 1 : 0)
+		const durable = await deliverDurableInbound(
+			this.ctx.recorder,
+			this.ctx.durableInbound,
+			this.ctx.abortController.signal,
+		)
+		return queued.length + (stranded ? 1 : 0) + durable
 	}
 
 	private recordStep(input: {
@@ -1958,6 +2005,7 @@ export class IterationOrchestrator {
 						toolName: tc.function.name,
 						output: outcome?.output ?? '',
 						isError: outcome?.isError ?? false,
+						...(outcome?.skipped ? { skipped: true as const } : {}),
 						durationMs: 0,
 					},
 				]
@@ -2002,8 +2050,8 @@ export class IterationOrchestrator {
 		}
 	}
 
-	/** Turns spent asking the model again for a valid structured output. */
-	private structuredOutputAttempts = 0
+	/** Model responses needing a tool-mode schema correction, separate from host reviews. */
+	private toolStructuredAttempts = 0
 	private nativeStructuredAttempts = 0
 	private structuredOutputDone = false
 	private pendingStructuredOutput: unknown
@@ -2013,6 +2061,58 @@ export class IterationOrchestrator {
 		return this.ctx.structuredOutput?.maxRetries ?? DEFAULT_STRUCTURED_OUTPUT_RETRIES
 	}
 
+	private stopForStructuredRetryExhaustion(): boolean {
+		const { recorder, abortController } = this.ctx
+		if (abortController.signal.aborted) {
+			recorder.setStopReason('cancelled')
+			recorder.markCancelled()
+			return true
+		}
+		if (!this.needsStructuredOutput()) return false
+		const attempts =
+			this.ctx.structuredOutput?.mode === 'native'
+				? this.nativeStructuredAttempts
+				: this.toolStructuredAttempts
+		if (attempts === 0 || !(attempts > this.structuredOutputRetryLimit())) return false
+		recorder.setStopReason('structured_output_failed')
+		return true
+	}
+
+	private async recordToolStructuredFailure(
+		results: readonly ToolCallOutcome[],
+		iteration: number,
+	): Promise<boolean> {
+		if (
+			!this.needsStructuredOutput() ||
+			this.ctx.structuredOutput?.mode === 'native' ||
+			this.ctx.abortController.signal.aborted ||
+			!results.some(
+				(result) => result.toolName === STRUCTURED_OUTPUT_TOOL_NAME && result.inputFailure,
+			)
+		)
+			return false
+		// One model response consumes one correction, even with several invalid calls.
+		await this.recordToolStructuredCorrection(iteration)
+		return true
+	}
+
+	private async recordToolStructuredCorrection(iteration: number): Promise<void> {
+		this.toolStructuredAttempts++
+		const { recorder } = this.ctx
+		recorder.pushMessage(
+			createRuntimeContextMessage(STRUCTURED_OUTPUT_REPROMPT, 'structured-output'),
+		)
+		// Commit the full answered batch, feedback and allowance before another request
+		// or handoff. A failed checkpoint must not buy another correction opportunity.
+		const checkpoint = await this.ctx.checkpointMgr.create(recorder, iteration)
+		await this.ctx.emitEvent({
+			type: 'checkpoint_created',
+			turnId: recorder.turnId,
+			checkpointId: checkpoint.id,
+			iteration,
+		})
+	}
+
 	/** True while a structured output was demanded and has not arrived. */
 	private needsStructuredOutput(): boolean {
 		return this.ctx.structuredOutput !== undefined && !this.structuredOutputDone
@@ -2024,9 +2124,9 @@ export class IterationOrchestrator {
 	 * Deliberately narrow. A terminal call decides the turn only when it is
 	 * the ONLY call the model made in that turn: a model that asked for
 	 * other work meant to see those results, and settling here would throw
-	 * away answers it requested. Same for a failed terminal call — an
-	 * error is not an answer, and the model is the one that should read
-	 * it. Both cases fall through to the ordinary path, and both say so in
+	 * away answers it requested. A failed or skipped terminal call also
+	 * needs another model turn: its receipt is not an executed answer.
+	 * These cases fall through to the ordinary path, and each says so in
 	 * the log rather than quietly costing the relay the flag was set to
 	 * avoid.
 	 */
@@ -2049,11 +2149,16 @@ export class IterationOrchestrator {
 		}
 
 		const hit = terminal[0]
-		if (!hit || hit.isError) {
-			this.ctx.log.info('Terminal tool failed — returning the error to the model', {
-				[NAMZU.TURN_ID]: this.ctx.recorder.turnId,
-				[GENAI.TOOL_NAME]: hit?.toolName,
-			})
+		if (!hit || hit.isError || hit.skipped) {
+			this.ctx.log.info(
+				hit?.skipped
+					? 'Terminal tool was skipped — returning its receipt to the model'
+					: 'Terminal tool failed — returning the error to the model',
+				{
+					[NAMZU.TURN_ID]: this.ctx.recorder.turnId,
+					[GENAI.TOOL_NAME]: hit?.toolName,
+				},
+			)
 			return undefined
 		}
 		return hit
@@ -2065,7 +2170,8 @@ export class IterationOrchestrator {
 	 * The tool validates against the Zod schema before its `execute` runs,
 	 * so reaching here successfully means the value is already valid — a
 	 * failed parse comes back as an error result and simply does not
-	 * satisfy the demand, which sends the loop round again.
+	 * satisfy the demand, which sends the loop round again. A hook-skipped
+	 * receipt did not execute the tool and is not a candidate either.
 	 *
 	 * Narrow in the same way {@link terminalToolOutput} is, for its stated
 	 * reason and one that is sharper here. The neighbour refuses a shared
@@ -2111,7 +2217,9 @@ export class IterationOrchestrator {
 	): Promise<'absent' | 'accepted' | 'retry' | 'exhausted' | 'cancelled'> {
 		if (!this.needsStructuredOutput() || this.ctx.structuredOutput?.mode === 'native')
 			return 'absent'
-		const hit = results.find((r) => r.toolName === STRUCTURED_OUTPUT_TOOL_NAME && !r.isError)
+		const hit = results.find(
+			(r) => r.toolName === STRUCTURED_OUTPUT_TOOL_NAME && !r.isError && !r.skipped,
+		)
 		if (!hit) return 'absent'
 
 		const callCount = response.message.toolCalls?.length ?? 0
@@ -2125,15 +2233,19 @@ export class IterationOrchestrator {
 
 		let parsed: unknown
 		try {
-			parsed = JSON.parse(hit.output)
+			parsed =
+				this.ctx.structuredOutput?.toolResultRetention === 'durable'
+					? parseStructuredResultJson(
+							hit.structuredResultJson === undefined ? hit.output : hit.structuredResultJson,
+						)
+					: JSON.parse(hit.output)
 		} catch {
-			// The tool serializes its own validated input, so this is
-			// unreachable in practice; keep the raw text rather than losing it.
-			if (this.ctx.structuredOutput?.review)
-				throw new Error(
-					'Structured review requires an intact JSON tool result; check tool-output limits and result transformations',
-				)
-			parsed = hit.output
+			// Screening, hooks or output budgeting can change the validated
+			// tool's receipt. A raw-text fallback is not a structured result;
+			// do not recover input/data that bypasses those boundaries either.
+			throw new Error(
+				'Structured output requires an intact JSON tool result; check result transformations, increase maxToolOutputChars to fit the result, or use native mode with a capable provider',
+			)
 		}
 		return this.reviewStructuredOutput(parsed, reviewRequest, model)
 	}
@@ -2411,23 +2523,25 @@ export class IterationOrchestrator {
 				model: servedBy.model,
 			})
 
-			const assistantMsg = createAssistantMessage(
-				response.message.content,
-				undefined,
-				response.message.reasoning,
-				response.message.citations,
-				{
-					type: 'model',
-					...servedBy,
-					...(response.message.replayState !== undefined
-						? { replayState: response.message.replayState }
-						: {}),
-				},
-				response.message.textParts,
+			const finalMessageId = generateMessageId()
+			const assistantMsg = withStreamedMessageIdentity(
+				createAssistantMessage(
+					response.message.content,
+					undefined,
+					response.message.reasoning,
+					response.message.citations,
+					{
+						type: 'model',
+						...servedBy,
+						...(response.message.replayState !== undefined
+							? { replayState: response.message.replayState }
+							: {}),
+					},
+					response.message.textParts,
+				),
+				finalMessageId,
 			)
 			this.ctx.recorder.pushMessage(assistantMsg)
-
-			const finalMessageId = generateMessageId()
 			await this.ctx.emitEvent({
 				type: 'message_started',
 				turnId: this.ctx.recorder.turnId,