@namzu/sdk 48.3.1 → 50.0.0

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

@@ -1,7 +1,10 @@
 import { SpanStatusCode } from '@opentelemetry/api';
 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';
@@ -16,14 +19,16 @@ 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 { parseStructuredResultJson } from '../../../utils/structured-result-json.js';
 import { createCallbackInference } from '../callback-inference.js';
+import { deliverDurableInbound } from '../durable-inbound.js';
 import { projectObservationContext } from '../observation-context.js';
 import { applyLifecycleHookResults } from '../plugin-hooks.js';
 import { diffRequestContext, snapshotRequestContext, } from '../request-context.js';
 import { DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES, markProviderRejectedImage, projectRequestRichContent, } 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 { activeContextWindow, measureContext, relieveOverflow, runCompactionCheck, } from './phases/compaction.js';
@@ -88,7 +93,7 @@ export class IterationOrchestrator {
     projectObservations(messages) {
         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. */
@@ -110,6 +115,9 @@ export class IterationOrchestrator {
     stopDeferredForOutstandingWork = false;
     /** One current input, independent of the compactable history array. */
     latestUserMessage;
+    initialDurableDelivered = false;
+    resumedToolResults = [];
+    toolStructuredCounterHydrated = false;
     constructor(ctx) {
         this.ctx = {
             ...ctx,
@@ -121,6 +129,9 @@ 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))
@@ -130,6 +141,11 @@ export class IterationOrchestrator {
             !['tool', 'native'].includes(ctx.structuredOutput.mode))
             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 (ctx.maxAnswerReviews !== undefined &&
@@ -206,15 +222,30 @@ export class IterationOrchestrator {
     setRootSpan(span) {
         this.ctx = { ...this.ctx, rootSpan: span };
     }
+    /** Fresh input is recorded before guards; restored tool batches must finish first. */
+    async deliverInitialDurable() {
+        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) {
+        this.resumedToolResults = results;
+    }
     async *runLoop() {
         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);
@@ -224,6 +255,9 @@ export class IterationOrchestrator {
         // 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
         // request failed the turn, while the same 429 one request later
@@ -240,9 +274,6 @@ export class IterationOrchestrator {
         // obvious moves left. It is cleared by a turn that actually
         // 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
@@ -253,17 +284,20 @@ 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');
+                if (this.stopForStructuredRetryExhaustion())
                     break;
-                }
                 if (this.ctx.reviewAnswer &&
                     this.answerReviewAttempts > (this.ctx.maxAnswerReviews ?? DEFAULT_ANSWER_REVIEW_LIMIT)) {
                     recorder.setStopReason('answer_rejected');
@@ -430,13 +464,33 @@ 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 = {
+                        ...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.
@@ -445,6 +499,11 @@ export class IterationOrchestrator {
                     // Publish context edits before entering a possibly slow provider.
                     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((tool) => this.ctx.structuredOutput?.mode !== 'native' ||
@@ -515,9 +574,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');
@@ -526,13 +582,13 @@ export class IterationOrchestrator {
                         : [...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);
@@ -790,7 +846,7 @@ 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, 
+                    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.
@@ -800,7 +856,7 @@ export class IterationOrchestrator {
                         ...(response.message.replayState !== undefined
                             ? { replayState: response.message.replayState }
                             : {}),
-                    }, response.message.textParts);
+                    }, response.message.textParts), messageId);
                     recorder.pushMessage(assistantMsg);
                     if (this.ctx.advisoryCtx && requestMessages) {
                         this.advisoryTurn = { iteration: iterationNum, requestMessages, response: assistantMsg };
@@ -941,7 +997,7 @@ export class IterationOrchestrator {
                             if (outcome === 'accepted') {
                                 if (!forceFinalize) {
                                     const changed = yield* holdForOutstandingWork(this.ctx, iterationNum, false, () => this.deliverInbound());
-                                    const inbound = this.deliverInbound();
+                                    const inbound = await this.deliverInbound();
                                     if (changed || inbound > 0)
                                         continue;
                                 }
@@ -960,6 +1016,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;
                         // Auto-continuation on `stop_reason: max_tokens`. The
                         // model hit its per-call output cap mid-text (NOT
@@ -1003,37 +1074,6 @@ export class IterationOrchestrator {
                             yield* this.ctx.drainPending();
                             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
@@ -1115,7 +1155,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,
@@ -1193,6 +1233,7 @@ 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
                     // something only the operator can do.
@@ -1202,6 +1243,18 @@ 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
                     // job would be to restate it — unless it shared its turn with
@@ -1243,7 +1296,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)
@@ -1361,7 +1414,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,
@@ -1374,7 +1427,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());
                     if (this.ctx.pluginManager) {
                         const hookResults = await this.ctx.pluginManager.executeHooks('iteration_end', {
@@ -1586,7 +1639,7 @@ export class IterationOrchestrator {
             extractFromUserMessage(manager, message.content, !manager.getState().task);
         }
     }
-    deliverInbound() {
+    async deliverInbound() {
         const queued = this.ctx.inboundMessages?.() ?? [];
         for (const message of queued) {
             this.ctx.recorder.pushMessage(message);
@@ -1601,7 +1654,8 @@ export class IterationOrchestrator {
             this.ctx.recorder.pushMessage(message);
             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;
     }
     recordStep(input) {
         const { recorder } = this.ctx;
@@ -1634,6 +1688,7 @@ export class IterationOrchestrator {
                         toolName: tc.function.name,
                         output: outcome?.output ?? '',
                         isError: outcome?.isError ?? false,
+                        ...(outcome?.skipped ? { skipped: true } : {}),
                         durationMs: 0,
                     },
                 ];
@@ -1675,8 +1730,8 @@ export class IterationOrchestrator {
             });
         }
     }
-    /** Turns spent asking the model again for a valid structured output. */
-    structuredOutputAttempts = 0;
+    /** Model responses needing a tool-mode schema correction, separate from host reviews. */
+    toolStructuredAttempts = 0;
     nativeStructuredAttempts = 0;
     structuredOutputDone = false;
     pendingStructuredOutput;
@@ -1684,6 +1739,47 @@ export class IterationOrchestrator {
     structuredOutputRetryLimit() {
         return this.ctx.structuredOutput?.maxRetries ?? DEFAULT_STRUCTURED_OUTPUT_RETRIES;
     }
+    stopForStructuredRetryExhaustion() {
+        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;
+    }
+    async recordToolStructuredFailure(results, iteration) {
+        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;
+    }
+    async recordToolStructuredCorrection(iteration) {
+        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. */
     needsStructuredOutput() {
         return this.ctx.structuredOutput !== undefined && !this.structuredOutputDone;
@@ -1694,9 +1790,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.
      */
@@ -1716,8 +1812,10 @@ export class IterationOrchestrator {
             return undefined;
         }
         const hit = terminal[0];
-        if (!hit || hit.isError) {
-            this.ctx.log.info('Terminal tool failed — returning the error to the model', {
+        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,
             });
@@ -1731,7 +1829,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
@@ -1772,7 +1871,7 @@ export class IterationOrchestrator {
     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);
+        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;
@@ -1785,14 +1884,16 @@ export class IterationOrchestrator {
         }
         let parsed;
         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);
     }
@@ -2041,15 +2142,15 @@ export class IterationOrchestrator {
                 providerId: servedBy.providerId,
                 model: servedBy.model,
             });
-            const assistantMsg = createAssistantMessage(response.message.content, undefined, response.message.reasoning, response.message.citations, {
+            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);
+            }, response.message.textParts), finalMessageId);
             this.ctx.recorder.pushMessage(assistantMsg);
-            const finalMessageId = generateMessageId();
             await this.ctx.emitEvent({
                 type: 'message_started',
                 turnId: this.ctx.recorder.turnId,