@namzu/sdk 38.2.1 → 39.0.0

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

@@ -14,6 +14,7 @@ import { renderSkillsSection } from '../../../persona/assembler.js'
 import { resolveProviderCapabilities } from '../../../provider/capabilities.js'
 import { collectChatCompletion } from '../../../provider/collect-chat-completion.js'
 import { renderToolSchema } from '../../../registry/tool/schema.js'
+import { PreparationContextError } from '../../../run/preparation-context-error.js'
 import { formatCompletionNotification } from '../../../scheduler/completion-inbox.js'
 import {
 	GENAI,
@@ -37,7 +38,7 @@ import {
 import type { ToolChoice } from '../../../types/provider/chat.js'
 import { classifyProviderError } from '../../../types/provider/errors.js'
 import type { ChatCompletionResponse } from '../../../types/provider/index.js'
-import type { AnswerReview } from '../../../types/run/answer-review.js'
+import type { AnswerReview, AnswerReviewContext } from '../../../types/run/answer-review.js'
 import type {
 	PrepareStepContext,
 	PrepareStepResult,
@@ -53,6 +54,7 @@ import type { LLMToolSchema, ToolRegistryContract } from '../../../types/tool/in
 import { toErrorMessage } from '../../../utils/error.js'
 import { stableDigest } from '../../../utils/hash.js'
 import { generateMessageId } from '../../../utils/id.js'
+import { createCallbackInference } from '../callback-inference.js'
 import type { ToolCallOutcome } from '../executor.js'
 import { projectObservationContext } from '../observation-context.js'
 import { applyLifecycleHookResults } from '../plugin-hooks.js'
@@ -84,6 +86,20 @@ import { refreshWorkingMemory } from './phases/working-memory.js'
 import { streamWithProviderRejectedImageRecovery } from './provider-rejected-image.js'
 import { streamProviderTurn } from './stream-turn.js'
 
+type ReviewRequest = Pick<AnswerReviewContext, 'requestMessages' | 'latestUserMessage'>
+
+/** A host reviewer is not the model transport, even when its cause is an HTTP failure. */
+class AnswerReviewFailure extends NamzuError {
+	constructor(cause: unknown) {
+		super({
+			code: 'unknown',
+			message: `Answer review failed: ${toErrorMessage(cause)}`,
+			retryable: false,
+			details: { phase: 'answer-review' },
+			cause,
+		})
+	}
+}
 export type { IterationContext } from './phases/index.js'
 export type { PhaseSignal } from './phases/index.js'
 export type { ToolReviewOutcome } from './phases/index.js'
@@ -98,6 +114,11 @@ export type { ToolReviewOutcome } from './phases/index.js'
  */
 const DEFAULT_ANSWER_REVIEW_LIMIT = 3
 
+// Ending a run changes the available actions, not the strength of its evidence.
+// Use the same standard for warning closure and empty-completion recovery.
+const CLOSING_RESPONSE_GUIDANCE =
+	'Give a concise response using only what the available evidence supports. Attribute unverified statements to their source instead of presenting them as observed facts. If evidence is missing or conflicting, state what cannot be established. Do not claim unfinished work is complete. Do not request any more tool calls.'
+
 /**
  * The share of a run's REMAINING time a settle-hold may take.
  *
@@ -162,6 +183,28 @@ export function settleGraceMs(remainingBeforeFinalizeMs: number): number {
 
 export class IterationOrchestrator {
 	private ctx: IterationContext
+	private advisoryTurn:
+		| {
+				readonly iteration: number
+				readonly requestMessages: readonly Message[]
+				readonly response: Message
+		  }
+		| undefined
+
+	/** Live only within its iteration; never joined by a guessed array offset. */
+	getAdvisoryTurnContext():
+		| import('../../../advisory/executor.js').AdvisoryTurnContext
+		| undefined {
+		const turn = this.advisoryTurn
+		if (!turn || turn.iteration !== this.ctx.runMgr.currentIteration) return undefined
+		const start = this.ctx.runMgr.messages.indexOf(turn.response)
+		if (start < 0) return undefined
+		return {
+			iteration: turn.iteration,
+			requestMessages: turn.requestMessages,
+			subsequentMessages: this.ctx.runMgr.messages.slice(start),
+		}
+	}
 	/** Rejections so far. See {@link DEFAULT_ANSWER_REVIEW_LIMIT}. */
 	private answerReviewAttempts = 0
 	/**
@@ -206,6 +249,7 @@ export class IterationOrchestrator {
 			},
 		}
 		ctx.checkpointMgr.setLatestUserMessageSource(() => this.latestUserMessage)
+		ctx.checkpointMgr.setAnswerReviewAttemptsSource?.(() => this.answerReviewAttempts)
 		ctx.checkpointMgr.setStructuredReviewAttemptsSource?.(() => this.structuredReviewAttempts)
 		ctx.checkpointMgr.setNativeStructuredAttemptsSource?.(() => this.nativeStructuredAttempts)
 		if (ctx.structuredOutput?.mode === 'native') {
@@ -223,6 +267,11 @@ export class IterationOrchestrator {
 		const maxReviews = ctx.structuredOutput?.maxReviews
 		if (maxReviews !== undefined && (!Number.isSafeInteger(maxReviews) || maxReviews < 0))
 			throw new RangeError('structuredOutput.maxReviews must be a nonnegative safe integer')
+		if (
+			ctx.maxAnswerReviews !== undefined &&
+			(!Number.isSafeInteger(ctx.maxAnswerReviews) || ctx.maxAnswerReviews < 0)
+		)
+			throw new RangeError('maxAnswerReviews must be a nonnegative safe integer')
 	}
 
 	/**
@@ -306,6 +355,7 @@ export class IterationOrchestrator {
 		const tracer = getTracer()
 		// 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
 		if (!this.latestUserMessage) {
@@ -353,6 +403,13 @@ export class IterationOrchestrator {
 					runMgr.setStopReason('structured_output_failed')
 					break
 				}
+				if (
+					this.ctx.reviewAnswer &&
+					this.answerReviewAttempts > (this.ctx.maxAnswerReviews ?? DEFAULT_ANSWER_REVIEW_LIMIT)
+				) {
+					runMgr.setStopReason('answer_rejected')
+					break
+				}
 				if (
 					this.ctx.structuredOutput?.review &&
 					this.structuredReviewAttempts >
@@ -533,14 +590,15 @@ export class IterationOrchestrator {
 					// Snapshot the cumulative counters so the step can report ITS
 					// own usage rather than the run total.
 					stepStartedAt = Date.now()
-					usageBefore = { ...runMgr.tokenUsage }
-					costBefore = { ...runMgr.costInfo }
 
 					// Shape this step before calling the model. `stopWhen` decides
 					// whether to keep going; this decides HOW. No-op when the host
 					// supplied no hook.
 					const contextModelBeforePreparation = this.ctx.contextModel ?? model
 					const step = await this.prepareStep(iterationNum)
+					// Preparation inference belongs to the run, not the main-model step.
+					usageBefore = { ...runMgr.tokenUsage }
+					costBefore = { ...runMgr.costInfo }
 					stepModel = step.model ?? model
 					await this.selectContextModel(stepModel)
 					// Preserve post-compaction preparation/recall semantics. A changed
@@ -570,7 +628,7 @@ export class IterationOrchestrator {
 						? [
 								...runMgr.messages,
 								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.',
+									`[SYSTEM] You are approaching your resource limits. ${CLOSING_RESPONSE_GUIDANCE}`,
 									'limit-finalization',
 								),
 							]
@@ -589,9 +647,9 @@ export class IterationOrchestrator {
 					// mutation, and per-iteration this is trivial next to the model
 					// call it precedes.
 					// A step's skills and its guidance ride the same ephemeral
-					// trailing system message. Appending leaves the cached prefix
-					// intact; rewriting the run's own prompt to carry a phase's
-					// skills would invalidate it on every iteration.
+					// system message. A driver may move it before history; changing
+					// system guidance can therefore affect prefix caching. Observations
+					// that need no system authority use step.context below.
 					// `renderSkillsSection` already answers null for an empty list, so
 					// there is no length check here — a second guard for the same
 					// case is one more thing to keep in agreement with the first.
@@ -612,10 +670,9 @@ export class IterationOrchestrator {
 						? `Approval policy changed from "${policyChange.from}" to "${policyChange.to}" (${policyChange.reason}). Tool calls from here on are reviewed under the new policy.`
 						: null
 					// State that changed during the run, reported once per turn.
-					// `turn` contributions land HERE and nowhere else: in the
-					// system prompt they would be cached for the run or read as
-					// a standing instruction, and either way the state they
-					// exist to report goes stale silently.
+					// `turn` contributions are recomputed here, not fixed when the
+					// run's prompt is assembled. They retain system authority and
+					// may affect caching just like the other system contributions.
 					const turnSections =
 						this.ctx.promptContributions?.render('turn', {
 							iteration: iterationNum,
@@ -627,10 +684,12 @@ export class IterationOrchestrator {
 					const requestHistory = stepPreamble
 						? [...baseMessages, createSystemMessage(stepPreamble)]
 						: [...baseMessages]
+					if (step.context) requestHistory.push(this.stepContextMessage(step.context))
 					const messages = projectRequestRichContent(
 						this.projectObservations(requestHistory),
 						this.ctx.runConfig.maxRequestRichContentBytes ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
 					)
+					this.appendWorkContext(messages, iterationNum, step)
 					await this.reportUnsupportedToolResults(messages)
 					yield* this.ctx.drainPending()
 
@@ -741,7 +800,12 @@ export class IterationOrchestrator {
 						model: requestedMember.model ?? stepModel,
 						chainIndex: requestedMember.index,
 					}
-					const { response, messageId } = yield* streamProviderTurn(
+					const operatorInputAtDispatch = this.latestUserMessage
+					const latestReviewUserMessage =
+						(this.ctx.reviewAnswer || this.ctx.structuredOutput?.review) && operatorInputAtDispatch
+							? structuredClone(operatorInputAtDispatch)
+							: undefined
+					const { response, messageId, requestMessages } = yield* streamProviderTurn(
 						this.ctx.provider,
 						{
 							model: stepModel,
@@ -794,8 +858,15 @@ export class IterationOrchestrator {
 						{
 							onAccepted: (identity) => this.acceptProviderRejectedImage(identity),
 						},
+						Boolean(
+							this.ctx.reviewAnswer || this.ctx.structuredOutput?.review || this.ctx.advisoryCtx,
+						),
 					)
 					stepResponse = response
+					const reviewRequest: ReviewRequest = {
+						...(requestMessages ? { requestMessages } : {}),
+						...(latestReviewUserMessage ? { latestUserMessage: latestReviewUserMessage } : {}),
+					}
 
 					// Who answered THIS turn.
 					//
@@ -804,18 +875,9 @@ export class IterationOrchestrator {
 					// request, so the member at the cursor when the stream ends is
 					// the one whose bytes are in `response`.
 					//
-					// It is taken here rather than at `recordStep` several hundred
-					// lines below, and the honest account of that is defence in
-					// depth, not a defect it currently prevents. Moving it down
-					// fails no test, because nothing between the two asks this
-					// provider for anything: compaction and working memory run
-					// BEFORE the turn, the advisory phase runs after the step is
-					// already recorded, and the only thing in between is tool
-					// execution. That is a fact about today's phase order, which a
-					// later phase inserted here would change silently — and the
-					// symptom would be a step attributed to a member that first
-					// served the turn after it, which is the class of wrongness
-					// this whole field exists to end.
+					// Capture before host review: its auxiliary inference can move
+					// the fallback cursor. Main-step usage and provenance must keep
+					// naming the provider that produced this candidate.
 					const servedBy: StepProvenance = ((): StepProvenance => {
 						const member = this.ctx.servingMember?.() ?? {
 							index: 0,
@@ -935,8 +997,12 @@ export class IterationOrchestrator {
 								? { replayState: response.message.replayState }
 								: {}),
 						},
+						response.message.textParts,
 					)
 					runMgr.pushMessage(assistantMsg)
+					if (this.ctx.advisoryCtx && requestMessages) {
+						this.advisoryTurn = { iteration: iterationNum, requestMessages, response: assistantMsg }
+					}
 
 					if (this.ctx.workingStateManager && this.ctx.compactionConfig && assistantMsg.content) {
 						extractFromAssistantMessage(
@@ -1061,7 +1127,12 @@ export class IterationOrchestrator {
 								this.ctx.abortController.signal,
 							)
 							let outcome: 'accepted' | 'retry' | 'exhausted' | 'cancelled'
-							if (candidate.success) outcome = await this.reviewStructuredOutput(candidate.value)
+							if (candidate.success)
+								outcome = await this.reviewStructuredOutput(
+									candidate.value,
+									reviewRequest,
+									stepModel,
+								)
 							else {
 								this.nativeStructuredAttempts++
 								runMgr.pushMessage(
@@ -1207,7 +1278,11 @@ export class IterationOrchestrator {
 						// judge: bounded attempts, feedback as a user message, and
 						// a loud stop rather than a loop.
 						if (!forceFinalize && this.ctx.reviewAnswer) {
-							const review = await this.reviewAnswer(response.message.content ?? '')
+							const review = await this.reviewAnswer(
+								response.message.content ?? '',
+								reviewRequest,
+								stepModel,
+							)
 							if (this.ctx.abortController.signal.aborted) {
 								runMgr.setStopReason('cancelled')
 								runMgr.markCancelled()
@@ -1215,6 +1290,21 @@ export class IterationOrchestrator {
 							}
 							if (review && !review.accept) {
 								const attempt = ++this.answerReviewAttempts
+								runMgr.pushMessage(createRuntimeContextMessage(review.feedback, 'answer-review'))
+								// Commit the consumed allowance with its feedback before another
+								// request, including exhaustion. Compaction cannot reset this quota.
+								const checkpoint = await this.ctx.checkpointMgr.create(runMgr, iterationNum)
+								await this.ctx.emitEvent({
+									type: 'checkpoint_created',
+									runId: runMgr.id,
+									checkpointId: checkpoint.id,
+									iteration: iterationNum,
+								})
+								if (this.ctx.abortController.signal.aborted) {
+									runMgr.setStopReason('cancelled')
+									runMgr.markCancelled()
+									break
+								}
 								const limit = this.ctx.maxAnswerReviews ?? DEFAULT_ANSWER_REVIEW_LIMIT
 								if (attempt > limit) {
 									this.ctx.log.warn('Answer rejected more times than the run allows', {
@@ -1230,7 +1320,6 @@ export class IterationOrchestrator {
 									'namzu.retry.attempt': attempt,
 									'namzu.runtime.limit': limit,
 								})
-								runMgr.pushMessage(createRuntimeContextMessage(review.feedback, 'answer-review'))
 								await this.ctx.emitEvent({
 									type: 'iteration_completed',
 									runId: runMgr.id,
@@ -1272,7 +1361,12 @@ export class IterationOrchestrator {
 							continue
 						}
 
-						let closingStopReason: StopReason | undefined
+						// A limit-requested summary bypasses prose review and further
+						// work. Preserve that limit on settlement, even if the provider
+						// reports a normal text completion and headroom still remains.
+						let closingStopReason: StopReason | undefined = forceFinalize
+							? guardResult.stopReason
+							: undefined
 						if (!hasContent && !forceFinalize) {
 							this.ctx.log.warn('Empty completion detected — requesting final summary', {
 								[NAMZU.ITERATION]: iterationNum,
@@ -1353,6 +1447,8 @@ export class IterationOrchestrator {
 					const structuredOutcome = await this.captureStructuredOutput(
 						reviewOutcome.results,
 						response,
+						reviewRequest,
+						stepModel,
 					)
 					if (
 						structuredOutcome === 'retry' ||
@@ -1379,10 +1475,6 @@ export class IterationOrchestrator {
 						break
 					}
 					if (structuredOutcome === 'accepted') {
-						this.ctx.log.info('Structured output produced — ending run', {
-							[NAMZU.RUN_ID]: runMgr.id,
-							[NAMZU.ITERATION]: iterationNum,
-						})
 						await this.ctx.emitEvent({
 							type: 'iteration_completed',
 							runId: runMgr.id,
@@ -1395,6 +1487,21 @@ export class IterationOrchestrator {
 							runMgr.markCancelled()
 							break
 						}
+						if (!forceFinalize) {
+							const inbound = 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
+						}
+						if (this.ctx.abortController.signal.aborted) {
+							runMgr.setStopReason('cancelled')
+							runMgr.markCancelled()
+							break
+						}
+						this.ctx.log.info('Structured output produced — ending run', {
+							[NAMZU.RUN_ID]: runMgr.id,
+							[NAMZU.ITERATION]: iterationNum,
+						})
 						this.publishStructuredOutput()
 						runMgr.setStopReason('end_turn')
 						break
@@ -1512,7 +1619,7 @@ export class IterationOrchestrator {
 					// in the history the next request is built from.
 					this.deliverInbound()
 
-					await runAdvisoryPhase(this.ctx, iterationNum, response)
+					await runAdvisoryPhase(this.ctx, iterationNum, response, this.getAdvisoryTurnContext())
 
 					if (this.ctx.pluginManager) {
 						const hookResults = await this.ctx.pluginManager.executeHooks(
@@ -1633,6 +1740,7 @@ export class IterationOrchestrator {
 					// would burn the budget to arrive at the same error.
 					if (
 						!overflowRelieved &&
+						!(err instanceof AnswerReviewFailure) &&
 						classifyProviderError(err, this.ctx.provider.id).code === 'context_length_exceeded'
 					) {
 						overflowRelieved = true
@@ -1660,6 +1768,7 @@ export class IterationOrchestrator {
 					iterSpan.recordException(err instanceof Error ? err : new Error(String(err)))
 					throw err
 				} finally {
+					this.advisoryTurn = undefined
 					// The only place the iteration span ends. It used to be ended at each of
 					// seventeen exits, which is a rule every future edit has to
 					// remember; a generator abandoned by its consumer never reached
@@ -1809,25 +1918,37 @@ export class IterationOrchestrator {
 		)
 	}
 
-	/**
-	 * Ask the host how to shape this step.
-	 *
-	 * Fails OPEN on a throw — same reasoning as `stopWhen` and deliberately
-	 * opposite to a guardrail: a broken step-shaping hook should not kill an
-	 * otherwise healthy run, and unlike a safety check, nothing unsafe gets
-	 * through when it is skipped.
-	 */
-	/**
-	 * A host's chance to refuse the next model call.
-	 *
-	 * Fails CLOSED, which is the opposite of `prepareStep` below and the
-	 * reason they are separate hooks rather than one with two return
-	 * shapes. A broken step-SHAPER skipped costs a run its per-step tuning;
-	 * a broken step-REFUSER skipped is a refusal that did not happen, which
-	 * is precisely what the hook exists to prevent. The thrown error's
-	 * message becomes the reason, so an operator is not left with a run
-	 * that stopped and no account of it.
-	 */
+	private stepContextMessage(content: string) {
+		return createRuntimeContextMessage(
+			`Current step context (runtime-generated; not a new user request):\n${content}`,
+			'step-context',
+		)
+	}
+
+	/** Derived after request projection; never accumulates in canonical history or replaces operator intent. */
+	private appendWorkContext(
+		messages: Message[],
+		stepNumber: number,
+		prepared: PrepareStepResult,
+	): void {
+		const contributions = [
+			this.ctx.completionInbox?.describeOwnedWork(),
+			this.ctx.toolExecutor.describeFileEvidence(messages),
+		].filter((content): content is string => Boolean(content))
+		if (contributions.length === 0) return
+		let room = this.stepContext(stepNumber, prepared).contextBudget?.remainingTokens ?? 0
+		// Leave room for the actual task; admit whole contributions, never dangling partial references.
+		if (room < 1_500) return
+		for (const content of contributions) {
+			if (!content || content.length > 8_000) continue
+			const message = this.stepContextMessage(content)
+			const tokens = estimateMessageTokens(message)
+			if (tokens > Math.min(2_000, room - 1_000)) continue
+			messages.push(message)
+			room -= tokens
+		}
+	}
+
 	private stepContext(stepNumber: number, prepared: PrepareStepResult): PrepareStepContext {
 		const model = prepared.model ?? this.ctx.runConfig.model
 		const window = resolveContextWindow(
@@ -1841,7 +1962,9 @@ export class IterationOrchestrator {
 		)
 		const skills = prepared.skills ? renderSkillsSection([...prepared.skills]) : null
 		const preamble = [prepared.system, skills].filter(Boolean).join('\n\n')
-		const preparedTokens = preamble ? estimateMessageTokens(createSystemMessage(preamble)) : 0
+		const preparedTokens =
+			(preamble ? estimateMessageTokens(createSystemMessage(preamble)) : 0) +
+			(prepared.context ? estimateMessageTokens(this.stepContextMessage(prepared.context)) : 0)
 		const responseReserve = Math.min(
 			prepared.maxResponseTokens ??
 				this.ctx.runConfig.maxResponseTokens ??
@@ -1852,6 +1975,7 @@ export class IterationOrchestrator {
 			runId: this.ctx.runMgr.id,
 			stepNumber,
 			messages: this.ctx.runMgr.messages,
+			...(this.ctx.captureRunEvidence ? { captureRunEvidence: this.ctx.captureRunEvidence } : {}),
 			...(this.latestUserMessage ? { latestUserMessage: this.latestUserMessage } : {}),
 			signal: this.ctx.abortController.signal,
 			contextBudget: {
@@ -1868,6 +1992,7 @@ export class IterationOrchestrator {
 		}
 	}
 
+	/** Refuse the next call on a veto or hook error; do not skip a failed admission check. */
 	private async beforeStep(stepNumber: number): Promise<StepVeto | undefined> {
 		const configured = this.ctx.beforeStep
 		if (!configured) return undefined
@@ -1878,11 +2003,13 @@ export class IterationOrchestrator {
 		}
 	}
 
+	/** Shape the next request. A failed tuning stage is skipped; admission belongs to beforeStep. */
 	private async prepareStep(stepNumber: number): Promise<{
 		allowedTools?: string[]
 		toolChoice?: ToolChoice
 		model?: string
 		system?: string
+		context?: string
 		skills?: readonly Skill[]
 		temperature?: number
 		maxResponseTokens?: number
@@ -1897,8 +2024,16 @@ export class IterationOrchestrator {
 		// rather than an accident of install history.
 		let result: PrepareStepResult = {}
 		for (const stage of stages) {
+			const inference = createCallbackInference(
+				this.ctx,
+				result.model ?? this.ctx.runConfig.model,
+				'preparation',
+			)
 			try {
-				const decided = await stage(this.stepContext(stepNumber, result))
+				const decided = await stage({
+					...this.stepContext(stepNumber, result),
+					generateText: inference.generateText,
+				})
 				if (decided) result = { ...result, ...decided }
 				await this.selectContextModel(result.model ?? this.ctx.runConfig.model)
 			} catch (err) {
@@ -1909,6 +2044,23 @@ export class IterationOrchestrator {
 					'namzu.runtime.step_number': stepNumber,
 					'exception.message': toErrorMessage(err),
 				})
+				// An SDK stage may report availability and validated fallback evidence
+				// without exposing its error. Preserve prior decisions and the context budget;
+				// ordinary exceptions still contribute nothing to the model request.
+				if (err instanceof PreparationContextError && !this.ctx.abortController.signal.aborted) {
+					const room = this.stepContext(stepNumber, result).contextBudget?.remainingTokens ?? 0
+					if (
+						typeof err.context === 'string' &&
+						err.context.length > 0 &&
+						err.context.length + (result.context ? 2 : 0) <= Math.min(12_000, Math.floor(room))
+					)
+						result = {
+							...result,
+							context: [result.context, err.context].filter(Boolean).join('\n\n'),
+						}
+				}
+			} finally {
+				inference.close()
 			}
 		}
 
@@ -1917,6 +2069,7 @@ export class IterationOrchestrator {
 			toolChoice?: ToolChoice
 			model?: string
 			system?: string
+			context?: string
 			skills?: readonly Skill[]
 			temperature?: number
 			maxResponseTokens?: number
@@ -1953,6 +2106,7 @@ export class IterationOrchestrator {
 		if (result.toolChoice !== undefined) prepared.toolChoice = result.toolChoice
 		if (result.model !== undefined) prepared.model = result.model
 		if (result.system !== undefined) prepared.system = result.system
+		if (result.context !== undefined) prepared.context = result.context
 		if (result.skills !== undefined) prepared.skills = result.skills
 		if (result.temperature !== undefined) prepared.temperature = result.temperature
 		if (result.maxResponseTokens !== undefined) {
@@ -2237,6 +2391,8 @@ export class IterationOrchestrator {
 	private async captureStructuredOutput(
 		results: readonly ToolCallOutcome[],
 		response: ChatCompletionResponse,
+		reviewRequest: ReviewRequest,
+		model: string,
 	): Promise<'absent' | 'accepted' | 'retry' | 'exhausted' | 'cancelled'> {
 		if (!this.needsStructuredOutput() || this.ctx.structuredOutput?.mode === 'native')
 			return 'absent'
@@ -2264,7 +2420,7 @@ export class IterationOrchestrator {
 				)
 			parsed = hit.output
 		}
-		return this.reviewStructuredOutput(parsed)
+		return this.reviewStructuredOutput(parsed, reviewRequest, model)
 	}
 
 	private publishStructuredOutput(): void {
@@ -2274,6 +2430,8 @@ export class IterationOrchestrator {
 
 	private async reviewStructuredOutput(
 		parsed: unknown,
+		reviewRequest: ReviewRequest,
+		model: string,
 	): Promise<'accepted' | 'retry' | 'exhausted' | 'cancelled'> {
 		if (this.ctx.abortController.signal.aborted) return 'cancelled'
 		const reviewer = this.ctx.structuredOutput?.review
@@ -2286,22 +2444,27 @@ export class IterationOrchestrator {
 				signal.addEventListener('abort', onAbort, { once: true })
 			})
 			let verdict: AnswerReview
+			const inference = createCallbackInference(this.ctx, model, 'review')
 			try {
 				verdict = await Promise.race([
-					Promise.resolve().then(() =>
-						reviewer(structuredClone(parsed), {
+					Promise.resolve().then(() => {
+						signal.throwIfAborted()
+						return reviewer(structuredClone(parsed), {
 							runId: this.ctx.runMgr.id,
 							iteration: this.ctx.runMgr.currentIteration,
 							signal,
 							messages: this.ctx.runMgr.messages,
-						}),
-					),
+							...reviewRequest,
+							generateText: inference.generateText,
+						})
+					}),
 					aborted,
 				])
 			} catch (error) {
 				if (signal.aborted) return 'cancelled'
 				throw error
 			} finally {
+				inference.close()
 				signal.removeEventListener('abort', onAbort)
 			}
 			if (signal.aborted) return 'cancelled'
@@ -2335,33 +2498,48 @@ export class IterationOrchestrator {
 		return 'accepted'
 	}
 
-	/**
-	 * Ask the host whether this answer is good enough.
-	 *
-	 * A hook that throws **accepts**, which is the opposite of what the
-	 * safety gates do, and deliberately so. Those are asked "is this
-	 * dangerous", where the cost of failing closed is one refused
-	 * operation. This is asked "is this good enough", where failing closed
-	 * means handing the answer back forever — so a broken judge would turn
-	 * every run into a loop that ends on a budget error naming nothing. One
-	 * unreviewed answer is the cheaper failure, and the throw is logged at
-	 * `error` so it is not mistaken for approval.
-	 */
-	private async reviewAnswer(answer: string): Promise<AnswerReview | undefined> {
-		if (!this.ctx.reviewAnswer) return undefined
+	/** A reviewer failure aborts settlement; only an explicit rejection requests correction. */
+	private async reviewAnswer(
+		answer: string,
+		reviewRequest: ReviewRequest,
+		model: string,
+	): Promise<AnswerReview | undefined> {
+		const reviewer = this.ctx.reviewAnswer
+		const signal = this.ctx.abortController.signal
+		if (!reviewer || signal.aborted) return undefined
+		let onAbort = () => {}
+		const aborted = new Promise<never>((_resolve, reject) => {
+			onAbort = () => reject(signal.reason ?? new Error('Answer review cancelled'))
+			signal.addEventListener('abort', onAbort, { once: true })
+		})
+		const inference = createCallbackInference(this.ctx, model, 'review')
 		try {
-			return await this.ctx.reviewAnswer(answer, {
-				runId: this.ctx.runMgr.id,
-				iteration: this.ctx.runMgr.currentIteration,
-				signal: this.ctx.abortController.signal,
-				messages: this.ctx.runMgr.messages,
-			})
-		} catch (err) {
-			this.ctx.log.error('Answer review threw — accepting the answer unreviewed', {
-				[NAMZU.RUN_ID]: this.ctx.runMgr.id,
-				'exception.message': toErrorMessage(err),
-			})
-			return { accept: true }
+			const verdict = await Promise.race([
+				Promise.resolve().then(() => {
+					signal.throwIfAborted()
+					return reviewer(answer, {
+						runId: this.ctx.runMgr.id,
+						iteration: this.ctx.runMgr.currentIteration,
+						signal,
+						messages: this.ctx.runMgr.messages,
+						...reviewRequest,
+						generateText: inference.generateText,
+					})
+				}),
+				aborted,
+			])
+			if (signal.aborted) return undefined
+			if (!verdict || typeof verdict.accept !== 'boolean')
+				throw new Error('Answer reviewer returned an invalid verdict')
+			if (!verdict.accept && (typeof verdict.feedback !== 'string' || !verdict.feedback.trim()))
+				throw new Error('Answer reviewer rejection requires feedback')
+			return verdict
+		} catch (error) {
+			if (signal.aborted) return undefined
+			throw new AnswerReviewFailure(error)
+		} finally {
+			inference.close()
+			signal.removeEventListener('abort', onAbort)
 		}
 	}
 
@@ -2445,7 +2623,7 @@ export class IterationOrchestrator {
 			const finalHistory = [
 				...this.ctx.runMgr.messages,
 				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.`,
+					`[SYSTEM] Run is ending due to ${reason}. ${CLOSING_RESPONSE_GUIDANCE}`,
 					'limit-finalization',
 				),
 			]
@@ -2453,6 +2631,7 @@ export class IterationOrchestrator {
 				this.projectObservations(finalHistory),
 				this.ctx.runConfig.maxRequestRichContentBytes ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
 			)
+			this.appendWorkContext(finalMessages, this.steps.length + 1, { model })
 			await this.reportUnsupportedToolResults(finalMessages)
 
 			// Same cache discipline as the forced-final iteration: keep the
@@ -2517,6 +2696,7 @@ export class IterationOrchestrator {
 						? { replayState: response.message.replayState }
 						: {}),
 				},
+				response.message.textParts,
 			)
 			this.ctx.runMgr.pushMessage(assistantMsg)
 
@@ -2535,6 +2715,7 @@ export class IterationOrchestrator {
 				stopReason: 'forced_finalize',
 				usage: response.usage,
 				content: response.message.content ?? undefined,
+				...(response.message.textParts ? { textParts: response.message.textParts } : {}),
 			})
 		} catch (err) {
 			this.ctx.log.error('Failed to get final response', {
@@ -2556,6 +2737,8 @@ export class IterationOrchestrator {
  * threw and is left saying so rather than dressed up as something specific.
  */
 function describeStepFailure(err: unknown, providerId: string): StepFailure {
+	if (err instanceof AnswerReviewFailure)
+		return { message: err.message, code: 'unknown', retryable: false }
 	const classified = classifyProviderError(err, providerId)
 	return {
 		message: toErrorMessage(err),