@namzu/sdk 48.3.1 → 50.0.0

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

@@ -3,11 +3,14 @@ import {
 	extractFromAssistantMessage,
 	extractFromUserMessage,
 } from '../../../compaction/extractor.js'
+import { estimateMessageTokens } from '../../../compaction/token-estimate.js'
 import { AUTO_CONTINUATION_USER_MESSAGE } from '../../../constants/continuation.js'
+import { CHARS_PER_TOKEN } from '../../../constants/limits.js'
 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'
@@ -46,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'
@@ -63,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 {
@@ -160,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. */
@@ -182,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 = {
@@ -194,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))
@@ -207,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 (
@@ -291,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)
 		}
@@ -307,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
@@ -326,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
@@ -339,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)
@@ -548,13 +593,37 @@ export class IterationOrchestrator {
 					// Shape this step before calling the model. `stopWhen` decides
 					// whether to keep going; this decides HOW. No-op when the host
 					// supplied no hook.
+					// Render request-only contributions once before preparation. Their
+					// estimated cost reduces every stage's headroom, and the same text
+					// reaches the provider even if a stage changes external state.
+					const contextSections =
+						this.ctx.promptContributions?.render('context', { iteration: iterationNum }) ?? []
+					const deferredMcpHints =
+						this.ctx.showDeferredToolContext !== false
+							? this.ctx.tools.snapshotUntrustedDeferredContext()
+							: undefined
+					const pricedContextText = [
+						...contextSections,
+						...(deferredMcpHints?.all ? [deferredMcpHints.all] : []),
+					].join('\n\n')
+					const shaping: StepShaping = {
+						...this.stepShaping(),
+						requestContextTokens: pricedContextText
+							? estimateMessageTokens(stepContextMessage(pricedContextText)) +
+								Math.ceil(
+									((deferredMcpHints?.maxRenderedChars ?? 0) -
+										(deferredMcpHints?.all.length ?? 0)) /
+										CHARS_PER_TOKEN,
+								)
+							: 0,
+					}
 					const contextModelBeforePreparation = this.ctx.contextModel ?? model
-					const step = await prepareStep(this.stepShaping(), iterationNum)
+					const step = await prepareStep(shaping, iterationNum)
 					// Preparation inference belongs to the turn, not the main-model step.
 					usageBefore = { ...recorder.tokenUsage }
 					costBefore = { ...recorder.costInfo }
 					stepModel = step.model ?? model
-					await selectContextModel(this.stepShaping(), stepModel)
+					await selectContextModel(shaping, stepModel)
 					// Preserve post-compaction preparation/recall semantics. A changed
 					// model needs a second check against its own window; never replay
 					// host preparation effects merely to rebuild its request guidance.
@@ -563,6 +632,11 @@ export class IterationOrchestrator {
 					yield* this.ctx.drainPending()
 
 					const stepAllowedTools = step.allowedTools ?? this.ctx.allowedTools
+					const deferredMcpContext = deferredMcpHints?.forNames(stepAllowedTools) ?? ''
+					const contextText = [
+						...contextSections,
+						...(deferredMcpContext ? [deferredMcpContext] : []),
+					].join('\n\n')
 					const llmTools = this.ctx.tools
 						.toLLMTools(stepAllowedTools)
 						.filter(
@@ -643,11 +717,6 @@ export class IterationOrchestrator {
 					// (compaction preserves it there) and leaves the request's
 					// system run here.
 					const workingMemory = splitWorkingMemoryForRequest(baseMessages)
-					const contextSections =
-						this.ctx.promptContributions?.render('context', {
-							iteration: iterationNum,
-						}) ?? []
-
 					const stepPreamble = [step.system, stepSkills, policyNotice, ...turnSections]
 						.filter(Boolean)
 						.join('\n\n')
@@ -655,15 +724,14 @@ export class IterationOrchestrator {
 						? [...workingMemory.history, createSystemMessage(stepPreamble)]
 						: [...workingMemory.history]
 					if (workingMemory.context) requestHistory.push(workingMemory.context)
-					if (contextSections.length > 0)
-						requestHistory.push(stepContextMessage(contextSections.join('\n\n')))
+					if (contextText) requestHistory.push(stepContextMessage(contextText))
 					if (step.context) requestHistory.push(stepContextMessage(step.context))
 					const messages = projectRequestRichContent(
 						this.projectObservations(requestHistory),
 						this.ctx.turnConfig.maxRequestRichContentBytes ??
 							DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
 					)
-					appendWorkContext(this.stepShaping(), messages, iterationNum, step)
+					appendWorkContext(shaping, messages, iterationNum, step)
 					if (closingDirective) messages.push(closingDirective)
 					await this.reportUnsupportedToolResults(messages)
 					yield* this.ctx.drainPending()
@@ -962,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) {
@@ -1150,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) {
@@ -1171,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
 
@@ -1221,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
@@ -1346,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,
@@ -1431,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
@@ -1442,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
@@ -1491,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
@@ -1617,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,
@@ -1633,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())
 
@@ -1858,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)
@@ -1875,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: {
@@ -1933,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,
 					},
 				]
@@ -1977,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
@@ -1988,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
@@ -1999,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.
 	 */
@@ -2024,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
@@ -2040,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
@@ -2086,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
@@ -2100,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)
 	}
@@ -2386,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,