@namzu/sdk 38.1.0 → 39.0.0

package/dist/runtime/query/iteration/index.js

@@ -8,6 +8,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, NAMZU, agentIterationSpanName, parentContext, } from '../../../telemetry/attributes.js';
 import { getTracer } from '../../../telemetry/runtime-accessors.js';
@@ -19,6 +20,7 @@ import { classifyProviderError } from '../../../types/provider/errors.js';
 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 { projectObservationContext } from '../observation-context.js';
 import { applyLifecycleHookResults } from '../plugin-hooks.js';
 import { diffRequestContext, snapshotRequestContext, } from '../request-context.js';
@@ -33,6 +35,18 @@ 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';
+/** A host reviewer is not the model transport, even when its cause is an HTTP failure. */
+class AnswerReviewFailure extends NamzuError {
+    constructor(cause) {
+        super({
+            code: 'unknown',
+            message: `Answer review failed: ${toErrorMessage(cause)}`,
+            retryable: false,
+            details: { phase: 'answer-review' },
+            cause,
+        });
+    }
+}
 /**
  * How many times an answer may be handed back before the run stops.
  *
@@ -42,6 +56,9 @@ import { streamProviderTurn } from './stream-turn.js';
  * on the thing that actually went wrong.
  */
 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.
  *
@@ -101,6 +118,21 @@ export function settleGraceMs(remainingBeforeFinalizeMs) {
 }
 export class IterationOrchestrator {
     ctx;
+    advisoryTurn;
+    /** Live only within its iteration; never joined by a guessed array offset. */
+    getAdvisoryTurnContext() {
+        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}. */
     answerReviewAttempts = 0;
     /**
@@ -143,6 +175,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') {
@@ -156,6 +189,9 @@ 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');
     }
     /**
      * Check the exact post-budget request for tool-result shapes the active driver
@@ -233,6 +269,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) {
@@ -278,6 +315,11 @@ 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 >
                         (this.ctx.structuredOutput.maxReviews ?? DEFAULT_ANSWER_REVIEW_LIMIT)) {
@@ -434,13 +476,14 @@ 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
@@ -465,7 +508,7 @@ export class IterationOrchestrator {
                     const baseMessages = forceFinalize
                         ? [
                             ...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.', 'limit-finalization'),
+                            createRuntimeContextMessage(`[SYSTEM] You are approaching your resource limits. ${CLOSING_RESPONSE_GUIDANCE}`, 'limit-finalization'),
                         ]
                         : runMgr.messages;
                     // Step guidance is appended to the REQUEST, never pushed onto
@@ -481,9 +524,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.
@@ -504,10 +547,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,
                     }) ?? [];
@@ -517,7 +559,10 @@ 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();
                     // What the model is about to be ASKED, recorded when it
@@ -619,7 +664,11 @@ export class IterationOrchestrator {
                         model: requestedMember.model ?? stepModel,
                         chainIndex: requestedMember.index,
                     };
-                    const { response, messageId } = yield* streamProviderTurn(this.ctx.provider, {
+                    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,
                         ...(this.ctx.structuredOutput?.mode === 'native'
                             ? {
@@ -659,8 +708,12 @@ export class IterationOrchestrator {
                         signal: this.ctx.abortController.signal,
                     }, this.ctx.emitEvent, this.ctx.drainPending, runMgr.id, iterationNum, forceFinalize, this.ctx.log, iterSpan, stepMessageId, {
                         onAccepted: (identity) => this.acceptProviderRejectedImage(identity),
-                    });
+                    }, Boolean(this.ctx.reviewAnswer || this.ctx.structuredOutput?.review || this.ctx.advisoryCtx));
                     stepResponse = response;
+                    const reviewRequest = {
+                        ...(requestMessages ? { requestMessages } : {}),
+                        ...(latestReviewUserMessage ? { latestUserMessage: latestReviewUserMessage } : {}),
+                    };
                     // Who answered THIS turn.
                     //
                     // The read is exact at this point and stays exact: a chain that
@@ -668,18 +721,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 = (() => {
                         const member = this.ctx.servingMember?.() ?? {
                             index: 0,
@@ -780,8 +824,11 @@ export class IterationOrchestrator {
                         ...(response.message.replayState !== undefined
                             ? { 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(this.ctx.workingStateManager, assistantMsg.content, this.ctx.compactionConfig);
                     }
@@ -887,7 +934,7 @@ export class IterationOrchestrator {
                             const candidate = await parseNativeCandidate(this.ctx.structuredOutput.schema, response, this.ctx.abortController.signal);
                             let outcome;
                             if (candidate.success)
-                                outcome = await this.reviewStructuredOutput(candidate.value);
+                                outcome = await this.reviewStructuredOutput(candidate.value, reviewRequest, stepModel);
                             else {
                                 this.nativeStructuredAttempts++;
                                 runMgr.pushMessage(createRuntimeContextMessage('Return a complete JSON value matching the supplied response schema. Do not continue a partial JSON fragment.', 'structured-output'));
@@ -1018,7 +1065,7 @@ 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();
@@ -1026,6 +1073,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', {
@@ -1041,7 +1103,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,
@@ -1080,7 +1141,12 @@ export class IterationOrchestrator {
                             yield* this.ctx.drainPending();
                             continue;
                         }
-                        let closingStopReason;
+                        // 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 = forceFinalize
+                            ? guardResult.stopReason
+                            : undefined;
                         if (!hasContent && !forceFinalize) {
                             this.ctx.log.warn('Empty completion detected — requesting final summary', {
                                 [NAMZU.ITERATION]: iterationNum,
@@ -1150,7 +1216,7 @@ export class IterationOrchestrator {
                     // run ends here rather than paying for another turn whose only
                     // job would be to restate it — unless it shared its turn with
                     // other calls, which relays instead. See the method.
-                    const structuredOutcome = await this.captureStructuredOutput(reviewOutcome.results, response);
+                    const structuredOutcome = await this.captureStructuredOutput(reviewOutcome.results, response, reviewRequest, stepModel);
                     if (structuredOutcome === 'retry' ||
                         structuredOutcome === 'exhausted' ||
                         structuredOutcome === 'cancelled') {
@@ -1174,10 +1240,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,
@@ -1190,6 +1252,22 @@ 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;
@@ -1298,7 +1376,7 @@ export class IterationOrchestrator {
                     // the next iteration so a message queued during THIS turn is
                     // 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('iteration_end', {
                             runId: runMgr.id,
@@ -1411,6 +1489,7 @@ export class IterationOrchestrator {
                     // compaction means the prompt is irreducible, and looping on it
                     // 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;
                         const shed = await relieveOverflow(this.ctx);
@@ -1436,6 +1515,7 @@ export class IterationOrchestrator {
                     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
@@ -1578,25 +1658,32 @@ export class IterationOrchestrator {
         });
         this.ctx.runMgr.pushMessage(createRuntimeContextMessage(formatCompletionNotification(unheard), 'task-completion'));
     }
-    /**
-     * 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.
-     */
+    stepContextMessage(content) {
+        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. */
+    appendWorkContext(messages, stepNumber, prepared) {
+        const contributions = [
+            this.ctx.completionInbox?.describeOwnedWork(),
+            this.ctx.toolExecutor.describeFileEvidence(messages),
+        ].filter((content) => 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;
+        }
+    }
     stepContext(stepNumber, prepared) {
         const model = prepared.model ?? this.ctx.runConfig.model;
         const window = resolveContextWindow(this.ctx.compactionConfig?.contextWindowTokens, model, model === this.ctx.runConfig.model
@@ -1606,7 +1693,8 @@ export class IterationOrchestrator {
                 : undefined);
         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 ??
             Math.floor(window.tokens / 4), Math.floor(window.tokens / 4));
@@ -1614,6 +1702,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: {
@@ -1624,6 +1713,7 @@ export class IterationOrchestrator {
             prepared,
         };
     }
+    /** Refuse the next call on a veto or hook error; do not skip a failed admission check. */
     async beforeStep(stepNumber) {
         const configured = this.ctx.beforeStep;
         if (!configured)
@@ -1635,6 +1725,7 @@ export class IterationOrchestrator {
             return { reason: `beforeStep threw: ${toErrorMessage(err)}` };
         }
     }
+    /** Shape the next request. A failed tuning stage is skipped; admission belongs to beforeStep. */
     async prepareStep(stepNumber) {
         const configured = this.ctx.prepareStep;
         if (!configured)
@@ -1646,8 +1737,12 @@ export class IterationOrchestrator {
         // rather than an accident of install history.
         let result = {};
         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);
@@ -1660,6 +1755,22 @@ 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();
             }
         }
         const prepared = {};
@@ -1696,6 +1807,8 @@ export class IterationOrchestrator {
             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)
@@ -1937,7 +2050,7 @@ export class IterationOrchestrator {
      * doing work, and it is the bound the neighbour relies on for the
      * identical pathology.
      */
-    async captureStructuredOutput(results, response) {
+    async captureStructuredOutput(results, response, reviewRequest, model) {
         if (!this.needsStructuredOutput() || this.ctx.structuredOutput?.mode === 'native')
             return 'absent';
         const hit = results.find((r) => r.toolName === STRUCTURED_OUTPUT_TOOL_NAME && !r.isError);
@@ -1962,13 +2075,13 @@ export class IterationOrchestrator {
                 throw new Error('Structured review requires an intact JSON tool result; check tool-output limits and result transformations');
             parsed = hit.output;
         }
-        return this.reviewStructuredOutput(parsed);
+        return this.reviewStructuredOutput(parsed, reviewRequest, model);
     }
     publishStructuredOutput() {
         this.ctx.runMgr.setStructuredOutput(this.pendingStructuredOutput);
         this.structuredOutputDone = true;
     }
-    async reviewStructuredOutput(parsed) {
+    async reviewStructuredOutput(parsed, reviewRequest, model) {
         if (this.ctx.abortController.signal.aborted)
             return 'cancelled';
         const reviewer = this.ctx.structuredOutput?.review;
@@ -1982,14 +2095,20 @@ export class IterationOrchestrator {
                 signal.addEventListener('abort', onAbort, { once: true });
             });
             let verdict;
+            const inference = createCallbackInference(this.ctx, model, 'review');
             try {
                 verdict = await Promise.race([
-                    Promise.resolve().then(() => reviewer(structuredClone(parsed), {
-                        runId: this.ctx.runMgr.id,
-                        iteration: this.ctx.runMgr.currentIteration,
-                        signal,
-                        messages: this.ctx.runMgr.messages,
-                    })),
+                    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,
                 ]);
             }
@@ -1999,6 +2118,7 @@ export class IterationOrchestrator {
                 throw error;
             }
             finally {
+                inference.close();
                 signal.removeEventListener('abort', onAbort);
             }
             if (signal.aborted)
@@ -2030,35 +2150,49 @@ export class IterationOrchestrator {
         this.pendingStructuredOutput = parsed;
         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.
-     */
-    async reviewAnswer(answer) {
-        if (!this.ctx.reviewAnswer)
+    /** A reviewer failure aborts settlement; only an explicit rejection requests correction. */
+    async reviewAnswer(answer, reviewRequest, model) {
+        const reviewer = this.ctx.reviewAnswer;
+        const signal = this.ctx.abortController.signal;
+        if (!reviewer || signal.aborted)
             return undefined;
+        let onAbort = () => { };
+        const aborted = new Promise((_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,
-            });
+            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 (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 };
+        catch (error) {
+            if (signal.aborted)
+                return undefined;
+            throw new AnswerReviewFailure(error);
+        }
+        finally {
+            inference.close();
+            signal.removeEventListener('abort', onAbort);
         }
     }
     /** Evaluate the caller's halt predicate, if there is one. */
@@ -2131,9 +2265,10 @@ export class IterationOrchestrator {
         try {
             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.`, 'limit-finalization'),
+                createRuntimeContextMessage(`[SYSTEM] Run is ending due to ${reason}. ${CLOSING_RESPONSE_GUIDANCE}`, 'limit-finalization'),
             ];
             const finalMessages = projectRequestRichContent(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
             // tools param identical to prior iterations (cache prefix intact,
@@ -2185,7 +2320,7 @@ export class IterationOrchestrator {
                 ...(response.message.replayState !== undefined
                     ? { replayState: response.message.replayState }
                     : {}),
-            });
+            }, response.message.textParts);
             this.ctx.runMgr.pushMessage(assistantMsg);
             const finalMessageId = generateMessageId();
             await this.ctx.emitEvent({
@@ -2202,6 +2337,7 @@ export class IterationOrchestrator {
                 stopReason: 'forced_finalize',
                 usage: response.usage,
                 content: response.message.content ?? undefined,
+                ...(response.message.textParts ? { textParts: response.message.textParts } : {}),
             });
         }
         catch (err) {
@@ -2223,6 +2359,8 @@ export class IterationOrchestrator {
  * threw and is left saying so rather than dressed up as something specific.
  */
 function describeStepFailure(err, providerId) {
+    if (err instanceof AnswerReviewFailure)
+        return { message: err.message, code: 'unknown', retryable: false };
     const classified = classifyProviderError(err, providerId);
     return {
         message: toErrorMessage(err),