@namzu/sdk 0.6.0 → 1.1.0

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

@@ -3,15 +3,45 @@ import { extractFromAssistantMessage } from '../../../compaction/extractor.js';
 import { collect } from '../../../provider/collect.js';
 import { GENAI, NAMZU, agentIterationSpanName } from '../../../telemetry/attributes.js';
 import { getTracer } from '../../../telemetry/runtime-accessors.js';
+import { mergeTokenUsage } from '../../../types/common/index.js';
 import { createAssistantMessage, createUserMessage } from '../../../types/message/index.js';
 import { toErrorMessage } from '../../../utils/error.js';
 import { generateMessageId } from '../../../utils/id.js';
+import { AUTO_CONTINUATION_USER_MESSAGE } from '../continuation.js';
 import { applyLifecycleHookResults } from '../plugin-hooks.js';
 import { runAdvisoryPhase } from './phases/advisory.js';
 import { runIterationCheckpoint } from './phases/checkpoint.js';
 import { runCompactionCheck } from './phases/compaction.js';
 import { runPlanGate } from './phases/plan.js';
 import { runToolReview } from './phases/tool-review.js';
+import { refreshWorkingMemory } from './phases/working-memory.js';
+/**
+ * Escape the five XML metacharacters so an interpolated value cannot
+ * break out of a tag. Used for the simple identifier fields in the
+ * `<task-notification>` envelope (taskId, agentId, status) — values
+ * here are controlled enums / opaque ids in practice, but escaping
+ * keeps the envelope robust against any future producer that lets a
+ * `<` or `&` leak in.
+ */
+function xmlEscape(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+/**
+ * Wrap free-form worker output in a CDATA section. CDATA preserves
+ * the raw text — code, markdown angle brackets, ampersands — so the
+ * supervisor sees what the worker actually produced instead of an
+ * escape-encoded approximation. The only termination CDATA forbids
+ * is the literal `]]>` sequence; we split-and-rejoin around it to
+ * keep the section well-formed regardless of payload.
+ */
+function cdataWrap(value) {
+    return `<![CDATA[${value.replace(/]]>/g, ']]]]><![CDATA[>')}]]>`;
+}
 /**
  * Map a provider's coarse `finishReason` plus the orchestrator's
  * `forceFinalize` flag onto the per-message {@link MessageStopReason}
@@ -50,8 +80,11 @@ function synthesizeMessageStopReason(finishReason, forceFinalize) {
  *   finally-style fall-through path with `stopReason: 'refusal'`.
  * - `tool_input_delta` with no `toolUseId` registered yet: we drop
  *   the fragment and log a warning (proxies seen to misorder events).
- * - `chunk.error`: we surface as a thrown error after emitting the
- *   message_completed terminator so consumer cards still close.
+ * - `chunk.error`: when no tool input is recoverable, we surface as
+ *   a thrown error after emitting the message_completed terminator so
+ *   consumer cards still close. If a tool-use block was already open,
+ *   we instead synthesize a tool call with runtime truncation metadata
+ *   so the executor can return a model-readable retry hint.
  */
 async function* streamProviderTurn(provider, params, emitEvent, drainPending, runId, iteration, forceFinalize, log) {
     const messageId = generateMessageId();
@@ -71,8 +104,36 @@ async function* streamProviderTurn(provider, params, emitEvent, drainPending, ru
     const toolBuckets = new Map();
     let streamError;
     const stream = provider.chatStream({ ...params, stream: true });
+    // Drive the stream manually so each `.next()` can be RACED against the run
+    // abort: a Stop tears the in-flight model request down (the provider got
+    // `params.signal`), and we ALSO stop pulling within a tick even if a
+    // transport buffers or ignores the signal. The abort rejection propagates
+    // out of this generator so the run loop settles the turn as cancelled.
+    // `{ once: true }` keeps a multi-iteration run from leaking a listener/turn.
+    const it = stream[Symbol.asyncIterator]();
+    const signal = params.signal;
+    let onAbort;
+    const aborted = signal
+        ? new Promise((_resolve, reject) => {
+            if (signal.aborted) {
+                reject(signal.reason);
+                return;
+            }
+            onAbort = () => reject(signal.reason);
+            signal.addEventListener('abort', onAbort, { once: true });
+        })
+        : undefined;
     try {
-        for await (const chunk of stream) {
+        for (;;) {
+            const next = it.next();
+            // Neutralize the dangling loser so an eventual rejection of the
+            // un-awaited `next` is never an unhandled rejection.
+            if (aborted)
+                next.catch(() => { });
+            const res = await (aborted ? Promise.race([next, aborted]) : next);
+            if (res.done)
+                break;
+            const chunk = res.value;
             if (chunk.error) {
                 streamError = chunk.error;
                 break;
@@ -99,6 +160,8 @@ async function* streamProviderTurn(provider, params, emitEvent, drainPending, ru
                         argsBuf: '',
                         started: false,
                         completed: false,
+                        parsed: null,
+                        inputTruncated: false,
                     };
                     toolBuckets.set(tc.index, bucket);
                 }
@@ -149,54 +212,148 @@ async function* streamProviderTurn(provider, params, emitEvent, drainPending, ru
                         parsed = bucket.argsBuf ? JSON.parse(bucket.argsBuf) : {};
                     }
                     catch (err) {
+                        bucket.inputTruncated = true;
                         log.warn('tool input JSON parse failed at content_block_stop', {
                             runId,
                             toolUseId: endId,
                             error: err instanceof Error ? err.message : String(err),
                         });
                     }
+                    bucket.parsed = parsed;
                     await emitEvent({
                         type: 'tool_input_completed',
                         runId,
                         toolUseId: endId,
                         input: parsed,
+                        ...(bucket.inputTruncated ? { inputTruncated: true } : {}),
                     });
                     yield* drainPending();
                 }
             }
             if (chunk.finishReason)
                 finishReason = chunk.finishReason;
+            // Merge (per-field max), not last-write-wins: a late usage frame that
+            // omits input/cache tokens must not zero the counts seen earlier in the
+            // stream, which would under-report this turn's accumulated usage.
             if (chunk.usage)
-                usage = chunk.usage;
+                usage = mergeTokenUsage(usage, chunk.usage);
         }
     }
     catch (err) {
+        // An abort tears the turn down: propagate it so the run loop settles the
+        // run as cancelled rather than recording a normal (errored) turn. Any
+        // other stream error is captured into the synthesized response as before.
+        if (signal?.aborted)
+            throw err;
         streamError = err instanceof Error ? err.message : String(err);
     }
+    finally {
+        if (onAbort)
+            signal?.removeEventListener('abort', onAbort);
+        // Release the underlying connection on every exit (natural end, error,
+        // or abort). `for await` did this implicitly on natural completion; the
+        // manual drive must do it explicitly. `.return()` on an already-finished
+        // provider generator is a no-op.
+        await it.return?.().catch(() => { });
+    }
     // Flush any tool buckets the provider failed to close (no toolCallEnd
-    // arrived — defensive against providers that don't yet emit it).
+    // arrived — defensive against providers that don't yet emit it, and
+    // the load-bearing path when the provider stream ends with
+    // `stop_reason: "max_tokens"` mid-`input_json_delta`. In that case
+    // Anthropic's SSE never sends `content_block_stop` for the open
+    // tool_use block: the upstream model ran out of completion tokens
+    // before it could close the JSON literal, so the buffered
+    // `argsBuf` ends with something like `"content":"…some prefix` —
+    // not parseable.
+    //
+    // Two cases coalesce here:
+    //   1. The buffer parses cleanly (the provider just forgot to emit
+    //      `content_block_stop` but the args are intact) — keep parsed.
+    //   2. The buffer is truncated mid-literal — `parsed = {}` is the
+    //      safe fallback so the executor's `JSON.parse(arguments)`
+    //      succeeds and downstream consumers don't crash. The PRICE
+    //      we used to pay was the model getting back a generic
+    //      "<field> is required" Zod error and not realising its
+    //      previous tool call was truncated server-side, so it would
+    //      retry with the SAME long input and hit the same cutoff in
+    //      a loop. Detect the truncation case and mark the tool call
+    //      with runtime metadata; the executor surfaces a specific
+    //      "your tool call was cut off by max_tokens — retry with
+    //      shorter input or split into smaller calls" message that the
+    //      model can act on.
     for (const bucket of toolBuckets.values()) {
         if (bucket.started && !bucket.completed) {
             bucket.completed = true;
             let parsed = {};
-            try {
-                parsed = bucket.argsBuf ? JSON.parse(bucket.argsBuf) : {};
+            let truncated = false;
+            if (bucket.argsBuf) {
+                try {
+                    parsed = JSON.parse(bucket.argsBuf);
+                }
+                catch {
+                    // argsBuf had content but didn't parse — almost
+                    // certainly the max_tokens-mid-literal cutoff. Mark
+                    // the bucket so the executor can return a model-
+                    // readable hint instead of a generic Zod error.
+                    truncated = true;
+                    parsed = {};
+                }
             }
-            catch {
-                // leave parsed = {}
+            bucket.parsed = parsed;
+            bucket.inputTruncated = truncated;
+            if (truncated) {
+                log.warn('tool input truncated by upstream cutoff (no toolCallEnd, argsBuf unparsable)', {
+                    runId,
+                    toolUseId: bucket.id,
+                    toolName: bucket.name,
+                    bufferLength: bucket.argsBuf.length,
+                });
             }
             await emitEvent({
                 type: 'tool_input_completed',
                 runId,
                 toolUseId: bucket.id,
                 input: parsed,
+                ...(truncated ? { inputTruncated: true } : {}),
             });
             yield* drainPending();
         }
     }
+    // `arguments` MUST be valid JSON for the executor's `JSON.parse`
+    // (`runtime/query/executor.ts:executeSingle`) to succeed. We
+    // always serialise from the bucket's `parsed` object (filled by
+    // either the `toolCallEnd` branch above or the post-stream flush
+    // loop) instead of re-emitting `argsBuf`. When the provider
+    // stream truncated mid-input, `metadata.inputTruncated` carries that
+    // state; the executor parses cleanly and returns a specific
+    // model-readable retry hint instead of the generic "Invalid JSON in
+    // tool arguments" intercept.
+    const toolCalls = [...toolBuckets.entries()]
+        .sort(([a], [b]) => a - b)
+        .map(([, b]) => ({
+        id: b.id,
+        type: 'function',
+        function: {
+            name: b.name,
+            arguments: JSON.stringify(b.parsed ?? {}),
+        },
+        ...(b.inputTruncated ? { metadata: { inputTruncated: true } } : {}),
+    }));
+    const recoveredToolInputFromStreamError = streamError !== undefined && toolCalls.some((tc) => tc.id && tc.function.name);
+    const effectiveFinishReason = recoveredToolInputFromStreamError ? 'tool_calls' : finishReason;
+    if (recoveredToolInputFromStreamError) {
+        log.warn('provider stream failed after tool input; surfacing tool call to executor', {
+            runId,
+            iteration,
+            error: streamError,
+            toolCallCount: toolCalls.length,
+        });
+    }
     const stopReason = streamError
-        ? 'refusal'
-        : synthesizeMessageStopReason(finishReason, forceFinalize);
+        ? recoveredToolInputFromStreamError
+            ? 'tool_use'
+            : 'refusal'
+        : synthesizeMessageStopReason(effectiveFinishReason, forceFinalize);
     await emitEvent({
         type: 'message_completed',
         runId,
@@ -207,16 +364,9 @@ async function* streamProviderTurn(provider, params, emitEvent, drainPending, ru
         content: textBuf || undefined,
     });
     yield* drainPending();
-    if (streamError) {
+    if (streamError && !recoveredToolInputFromStreamError) {
         throw new Error(`Provider stream error: ${streamError}`);
     }
-    const toolCalls = [...toolBuckets.entries()]
-        .sort(([a], [b]) => a - b)
-        .map(([, b]) => ({
-        id: b.id,
-        type: 'function',
-        function: { name: b.name, arguments: b.argsBuf },
-    }));
     const response = {
         id: id || messageId,
         model: model || params.model,
@@ -225,7 +375,7 @@ async function* streamProviderTurn(provider, params, emitEvent, drainPending, ru
             content: textBuf.length > 0 ? textBuf : null,
             toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
         },
-        finishReason,
+        finishReason: effectiveFinishReason,
         usage,
     };
     return { response, messageId };
@@ -255,6 +405,7 @@ export class IterationOrchestrator {
             launchedTasks: config.launchedTasks ?? new Map(),
             compactionConfig: config.compactionConfig,
             workingStateManager: config.workingStateManager,
+            workingMemoryProvider: config.workingMemoryProvider,
             advisoryCtx: config.advisoryCtx,
             agentBus: config.agentBus,
             verificationGate: config.verificationGate,
@@ -265,17 +416,19 @@ export class IterationOrchestrator {
         const { runConfig, runMgr } = this.ctx;
         const { model } = runConfig;
         const tracer = getTracer();
+        // Worker-completion delivery used to fan out through a global
+        // onTaskCompleted listener that pushed handles onto
+        // `pendingNotifications`; the iteration loop then drained
+        // them as <task-notification> envelopes. Both `create_task`
+        // and the `Agent` tool are now blocking and return their
+        // worker output as the dispatching tool_use's canonical
+        // tool_result, so the listener path would only DUPLICATE
+        // every completion (once as tool_result, once as injected
+        // envelope user-message). Leaving the binding out closes
+        // the duplicate notification surface entirely; the dormant
+        // drain stays as a no-op until a follow-up tears it out.
         let unsubscribeTaskListener;
-        if (this.ctx.taskGateway) {
-            unsubscribeTaskListener = this.ctx.taskGateway.onTaskCompleted((handle) => {
-                this.ctx.pendingNotifications.push(handle);
-                this.ctx.log.debug('Task completion queued for notification', {
-                    taskId: handle.taskId,
-                    agentId: handle.agentId,
-                    state: handle.state,
-                });
-            });
-        }
+        void unsubscribeTaskListener;
         try {
             const planSignal = yield* runPlanGate(this.ctx);
             if (planSignal === 'stop')
@@ -339,10 +492,18 @@ export class IterationOrchestrator {
                     if (this.ctx.pendingNotifications.length > 0) {
                         await this.injectOneTaskNotification();
                     }
+                    // Re-pin the working-memory block from ground truth at the primacy
+                    // edge BEFORE compaction runs (so the refreshed slot is what
+                    // compaction preserves). No-op when no provider is configured.
+                    await refreshWorkingMemory(this.ctx);
                     await runCompactionCheck(this.ctx);
-                    const openAITools = forceFinalize
-                        ? undefined
-                        : this.ctx.tools.toLLMTools(this.ctx.allowedTools);
+                    // Cache discipline: keep the tools param byte-stable even on the
+                    // forced-final iteration and forbid tool use via tool_choice
+                    // 'none' instead. Dropping the tools array would invalidate the
+                    // entire prompt-cache prefix (tools render at position 0) and
+                    // risks a 400 because the history still carries
+                    // tool_use/tool_result blocks.
+                    const openAITools = this.ctx.tools.toLLMTools(this.ctx.allowedTools);
                     const messages = forceFinalize
                         ? [
                             ...runMgr.messages,
@@ -365,10 +526,15 @@ export class IterationOrchestrator {
                     const { response } = yield* streamProviderTurn(this.ctx.provider, {
                         model,
                         messages,
-                        tools: openAITools && openAITools.length > 0 ? openAITools : undefined,
+                        tools: openAITools.length > 0 ? openAITools : undefined,
+                        toolChoice: forceFinalize && openAITools.length > 0 ? 'none' : undefined,
                         temperature: runConfig.temperature,
                         maxTokens: runConfig.maxResponseTokens,
                         cacheControl: { type: 'auto' },
+                        // Thread the run abort into the model call so a Stop tears the
+                        // in-flight turn down (provider passes it to fetch; the consumer
+                        // also races it). Inert when never aborted.
+                        signal: this.ctx.abortController.signal,
                     }, this.ctx.emitEvent, this.ctx.drainPending, runMgr.id, iterationNum, forceFinalize, this.ctx.log);
                     runMgr.accumulateUsage(response.usage);
                     if (this.ctx.pluginManager) {
@@ -434,6 +600,42 @@ export class IterationOrchestrator {
                             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
+                        // mid-tool-use — that path is handled separately
+                        // below via `inputTruncated`). Push a synthetic
+                        // "continue" user message and let the loop fire
+                        // another turn. The provider receives the partial
+                        // assistant content + the continue prompt and
+                        // resumes from where it left off, mirroring the
+                        // Claude.ai "Continue" affordance.
+                        //
+                        // Guards:
+                        //   - `hasContent` so we don't loop forever on an
+                        //     empty cutoff (Anthropic occasionally emits
+                        //     `stop_reason: max_tokens` with no content
+                        //     when an injected pre-fill blocks the model).
+                        //   - `!forceFinalize` so the forced-finalize path
+                        //     never auto-continues — that path is invoked
+                        //     specifically to extract a closing summary.
+                        //   - max_iterations bounds the loop in any case.
+                        if (!forceFinalize && response.finishReason === 'length' && hasContent) {
+                            this.ctx.log.info('LLM hit max_tokens mid-text — auto-continuing', {
+                                runId: runMgr.id,
+                                iteration: iterationNum,
+                                completionTokens: response.usage.completionTokens,
+                            });
+                            runMgr.pushMessage(createUserMessage(AUTO_CONTINUATION_USER_MESSAGE));
+                            await this.ctx.emitEvent({
+                                type: 'iteration_completed',
+                                runId: runMgr.id,
+                                iteration: iterationNum,
+                                hasToolCalls: false,
+                            });
+                            yield* this.ctx.drainPending();
+                            iterSpan.end();
+                            continue;
+                        }
                         if (!hasContent && !forceFinalize) {
                             this.ctx.log.warn('Empty completion detected — requesting final summary', {
                                 iteration: iterationNum,
@@ -449,6 +651,16 @@ export class IterationOrchestrator {
                             hasToolCalls: false,
                         });
                         yield* this.ctx.drainPending();
+                        // A Stop that lands AFTER the final turn streamed but before
+                        // this break must settle the run as cancelled, not end_turn —
+                        // otherwise the just-produced answer is recorded as a clean
+                        // completion. Mirrors the between-iteration cancel at :511.
+                        if (this.ctx.abortController.signal.aborted) {
+                            runMgr.setStopReason('cancelled');
+                            runMgr.markCancelled();
+                            iterSpan.end();
+                            break;
+                        }
                         runMgr.setStopReason('end_turn');
                         iterSpan.end();
                         break;
@@ -483,6 +695,19 @@ export class IterationOrchestrator {
                     iterSpan.end();
                 }
                 catch (err) {
+                    // A Stop that aborted the in-flight turn surfaces here as a
+                    // thrown abort (the provider stream was raced against the run
+                    // signal). Settle it as a CANCELLATION — mirroring the
+                    // between-iteration cancel at the top of the loop — rather than
+                    // recording it as an SDK failure (error span + failed activity)
+                    // and re-throwing. The run then returns cleanly with a
+                    // 'cancelled' stop reason instead of propagating an error.
+                    if (this.ctx.abortController.signal.aborted) {
+                        runMgr.setStopReason('cancelled');
+                        runMgr.markCancelled();
+                        iterSpan.end();
+                        break;
+                    }
                     if (iterationActivity) {
                         this.ctx.activityStore.fail(iterationActivity.id, toErrorMessage(err));
                     }
@@ -516,42 +741,68 @@ export class IterationOrchestrator {
         }
         await this.injectOneTaskNotification();
     }
+    /**
+     * Canonical async completion delivery (ses_009-task-notification-envelope).
+     *
+     * Drains every pending task completion in one pass and emits each as
+     * a plain USER text message wrapped in the `<task-notification>`
+     * envelope the supervisor prompt expects.
+     *
+     * Why not a `tool_result` block bound to the dispatching tool_use_id:
+     * `create_task` is documented as NON-BLOCKING and returns
+     * "Task launched: …" immediately. That immediate return is already
+     * recorded as the canonical tool_result for that tool_use, so a
+     * second tool_result for the SAME tool_use_id — emitted later, after
+     * intervening assistant turns — is rejected by Anthropic with
+     * `messages.<n>.content.0: unexpected tool_use_id found in
+     * tool_result blocks` because the immediately-prior assistant
+     * message no longer carries the matching tool_use. Wrapping as a
+     * user text envelope sidesteps the pairing rule entirely.
+     *
+     * Coalescing N drops into one drain replaces the previous
+     * one-at-a-time pattern which forced a separate orchestrator
+     * iteration per completed task on wide fan-outs.
+     */
     async injectOneTaskNotification() {
-        const handle = this.ctx.pendingNotifications.shift();
-        if (!handle)
+        if (this.ctx.pendingNotifications.length === 0)
             return;
-        const meta = this.ctx.launchedTasks.get(handle.taskId);
-        const resultText = handle.result?.result ??
-            handle.result?.lastError ??
-            `Task finished with state: ${handle.state}`;
-        if (meta?.planTaskId && this.ctx.taskStore) {
-            const success = handle.state === 'completed';
-            await this.ctx.taskStore.update(meta.planTaskId, {
-                status: 'completed',
-                description: success ? undefined : `Failed: ${resultText.substring(0, 200)}`,
+        const handles = this.ctx.pendingNotifications.splice(0);
+        for (const handle of handles) {
+            const meta = this.ctx.launchedTasks.get(handle.taskId);
+            const resultText = handle.result?.result ??
+                handle.result?.lastError ??
+                `Task finished with state: ${handle.state}`;
+            if (meta?.planTaskId && this.ctx.taskStore) {
+                const success = handle.state === 'completed';
+                await this.ctx.taskStore.update(meta.planTaskId, {
+                    status: 'completed',
+                    description: success ? undefined : `Failed: ${resultText.substring(0, 200)}`,
+                });
+            }
+            this.ctx.launchedTasks.delete(handle.taskId);
+            // `remaining-tasks` = inflight workers still pending after this
+            // one drains. `launchedTasks` is the single source of truth:
+            // it holds every dispatched worker that has NOT yet been
+            // drained + delete()'d. The drain batch entries are still
+            // inside launchedTasks until each iteration's delete() above
+            // removes them, so reading the size right after that delete
+            // gives the honest count. Adding `handles.length - 1 - i`
+            // here used to double-count this same queue.
+            const remainingTasks = this.ctx.launchedTasks.size;
+            const envelope = `<task-notification>\n<task-id>${xmlEscape(handle.taskId)}</task-id>\n` +
+                `<agent-id>${xmlEscape(handle.agentId)}</agent-id>\n` +
+                `<status>${xmlEscape(handle.state)}</status>\n` +
+                `<result>${cdataWrap(resultText)}</result>\n` +
+                `<remaining-tasks>${remainingTasks}</remaining-tasks>\n</task-notification>`;
+            this.ctx.runMgr.pushMessage(createUserMessage(envelope));
+            this.ctx.log.info('Task notification injected', {
+                taskId: handle.taskId,
+                agentId: handle.agentId,
+                state: handle.state,
+                planTaskId: meta?.planTaskId,
+                remainingNotifications: remainingTasks,
             });
         }
-        this.ctx.launchedTasks.delete(handle.taskId);
-        const remainingTasks = this.ctx.launchedTasks.size;
-        const notification = [
-            '<task-notification>',
-            `  <task-id>${handle.taskId}</task-id>`,
-            `  <agent-id>${handle.agentId}</agent-id>`,
-            `  <status>${handle.state}</status>`,
-            `  <description>${meta?.description ?? 'agent task'}</description>`,
-            `  <result>${resultText}</result>`,
-            `  <remaining-tasks>${remainingTasks}</remaining-tasks>`,
-            '</task-notification>',
-        ].join('\n');
-        this.ctx.runMgr.pushMessage(createUserMessage(notification));
-        this.ctx.log.info('Task notification injected', {
-            taskId: handle.taskId,
-            agentId: handle.agentId,
-            state: handle.state,
-            planTaskId: meta?.planTaskId,
-            remainingTasks,
-            remainingNotifications: this.ctx.pendingNotifications.length,
-        });
     }
     async requestFinalResponse(model, reason) {
         const lastAssistant = [...this.ctx.runMgr.messages]
@@ -570,12 +821,21 @@ export class IterationOrchestrator {
                 ...this.ctx.runMgr.messages,
                 createUserMessage(`[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.`),
             ];
+            // Same cache discipline as the forced-final iteration: keep the
+            // tools param identical to prior iterations (cache prefix intact,
+            // no 400 on tool blocks in history) and forbid use via tool_choice.
+            const finalTools = this.ctx.tools.toLLMTools(this.ctx.allowedTools);
             const response = await collect(this.ctx.provider.chatStream({
                 model,
                 messages: finalMessages,
+                tools: finalTools.length > 0 ? finalTools : undefined,
+                toolChoice: finalTools.length > 0 ? 'none' : undefined,
                 temperature: this.ctx.runConfig.temperature,
                 maxTokens: this.ctx.runConfig.maxResponseTokens,
                 cacheControl: { type: 'auto' },
+                // Cancellable too: a Stop during the closing summary must not
+                // stream to completion.
+                signal: this.ctx.abortController.signal,
             }));
             this.ctx.runMgr.accumulateUsage(response.usage);
             const assistantMsg = createAssistantMessage(response.message.content);