@openrouter/agent 0.9.0 → 0.11.0

package/esm/lib/model-result.js

@@ -1,7 +1,8 @@
 import { betaResponsesSend } from '@openrouter/sdk/funcs/betaResponsesSend';
-import { hasAsyncFunctions, resolveAsyncFunctions } from './async-params.js';
+import * as z4 from 'zod/v4';
+import { hasAsyncFunctions, resolveAsyncFunctions, stripToolSetSnapshotMetadata, } from './async-params.js';
 import { AsyncToolRegistry, acquireAll, buildTaskToolStub, defaultCheckResult, hasTaskToolNameCollision, persistedTaskCheckResult, resolveCheckConfig, Semaphore, TASK_RESULT_BOUNDARY, TASK_TOOL_NAME, TaskToolInputSchema, ToolTask, } from './async-tools.js';
-import { appendToMessages, createInitialState, createRejectedResult, createUnsentResult, extractTextFromResponse as extractTextFromResponseState, normalizeInputToArray, partitionToolCalls, unsentResultsToAPIFormat, updateState, } from './conversation-state.js';
+import { appendToMessages, createInitialState, createRejectedResult, createUnsentResult, extractTextFromResponse as extractTextFromResponseState, normalizeInputToArray, partitionToolCalls, toolRequiresApproval, unsentResultsToAPIFormat, updateState, } from './conversation-state.js';
 import { canonicalizeKeyMaterial, DoomLoopMonitor, resolveDoomLoopOption, resolveLoopKeyMaterial, } from './doom-loop.js';
 import { applyNextTurnParamsToRequest, executeNextTurnParamsFunctions, } from './next-turn-params.js';
 import { ReusableReadableStream } from './reusable-stream.js';
@@ -143,6 +144,11 @@ function isEventStream(value) {
     const maybeStream = value;
     return typeof maybeStream.getReader === 'function';
 }
+function isTerminalResponseStreamEvent(event) {
+    return (isResponseCompletedEvent(event) ||
+        isResponseFailedEvent(event) ||
+        isResponseIncompleteEvent(event));
+}
 /**
  * Map the server's usage block onto the hook-facing ModelCallUsage shape.
  * Returns undefined when the response carried no usage accounting.
@@ -302,6 +308,8 @@ export class ModelResult {
         this.turnBroadcaster = null;
         this.initialStreamPipeStarted = false;
         this.initialPipePromise = null;
+        this.initialResponse = null;
+        this.initialResponseError = null;
         // Context store for typed tool context (persists across turns)
         this.contextStore = null;
         // Tracks whether SessionStart has already been emitted, so SessionEnd can be
@@ -317,6 +325,15 @@ export class ModelResult {
         // normal tool round consults this to synthesize rejected outputs instead of
         // executing the calls.
         this.hookDeniedCalls = new Map();
+        // PreToolUse outcomes parked between the approval gates and execution.
+        this.preparedToolCalls = new Map();
+        // Approval is idempotent per response object, tool-call occurrence, and phase.
+        // Occurrence tokens avoid content canonicalization and distinguish duplicates.
+        this.completedApprovalGates = new Set();
+        this.approvalResponseOccurrences = new WeakMap();
+        this.approvalCallOccurrences = new WeakMap();
+        this.nextApprovalResponseOccurrence = 0;
+        this.nextApprovalCallOccurrence = 0;
         // Running aggregate across every PostModelCall emit; surfaced as
         // SessionEnd.totalUsage.
         this.sessionUsage = {
@@ -382,6 +399,7 @@ export class ModelResult {
         // id. Aborted on run abort / cancel() so cooperative tool bodies stop.
         this.inflightToolControllers = new Map();
         this.options = options;
+        this.streamReplay = options.streamReplay ?? 'full';
         this.hooksManager = options.hooks;
         const doomLoopConfig = resolveDoomLoopOption(options.doomLoop);
         this.doomLoopMonitor = doomLoopConfig ? new DoomLoopMonitor(doomLoopConfig) : null;
@@ -475,7 +493,7 @@ export class ModelResult {
      */
     ensureTurnBroadcaster() {
         if (!this.turnBroadcaster) {
-            this.turnBroadcaster = new ToolEventBroadcaster();
+            this.turnBroadcaster = new ToolEventBroadcaster(this.streamReplay);
         }
         return this.turnBroadcaster;
     }
@@ -511,7 +529,27 @@ export class ModelResult {
                 timestamp: Date.now(),
             });
         })().catch((error) => {
-            broadcaster.complete(error instanceof Error ? error : new Error(String(error)));
+            const normalizedError = error instanceof Error ? error : new Error(String(error));
+            this.initialResponseError = normalizedError;
+            broadcaster.complete(normalizedError);
+        });
+    }
+    captureInitialStreamEvent(event) {
+        if (isResponseCompletedEvent(event) || isResponseIncompleteEvent(event)) {
+            this.initialResponse = event.response;
+            return;
+        }
+        if (isResponseFailedEvent(event)) {
+            this.initialResponseError = new Error(`Response failed: ${JSON.stringify(event.response.error)}`);
+        }
+    }
+    setReusableStream(stream) {
+        this.initialResponse = null;
+        this.initialResponseError = null;
+        this.reusableStream = new ReusableReadableStream(stream, {
+            streamReplay: this.streamReplay,
+            onValue: (event) => this.captureInitialStreamEvent(event),
+            isTerminalValue: isTerminalResponseStreamEvent,
         });
     }
     /**
@@ -563,10 +601,11 @@ export class ModelResult {
      * Push a tool result event to both the legacy tool event broadcaster
      * and the unified turn broadcaster.
      */
-    broadcastToolResult(toolCallId, source, result, preliminaryResults) {
+    broadcastToolResult(toolCallId, toolName, source, result, preliminaryResults) {
         this.toolEventBroadcaster?.push({
             type: 'tool_result',
             toolCallId,
+            toolName,
             source,
             result,
             ...(preliminaryResults?.length && {
@@ -576,6 +615,7 @@ export class ModelResult {
         this.turnBroadcaster?.push({
             type: 'tool.result',
             toolCallId,
+            toolName,
             source,
             result,
             timestamp: Date.now(),
@@ -588,15 +628,17 @@ export class ModelResult {
      * Push a preliminary result event to both the legacy tool event broadcaster
      * and the unified turn broadcaster.
      */
-    broadcastPreliminaryResult(toolCallId, result) {
+    broadcastPreliminaryResult(toolCallId, toolName, result) {
         this.toolEventBroadcaster?.push({
             type: 'preliminary_result',
             toolCallId,
+            toolName,
             result,
         });
         this.turnBroadcaster?.push({
             type: 'tool.preliminary_result',
             toolCallId,
+            toolName,
             result,
             timestamp: Date.now(),
         });
@@ -638,7 +680,10 @@ export class ModelResult {
      */
     async materializeResponse(value, turnNumber) {
         if (isEventStream(value)) {
-            const stream = new ReusableReadableStream(value);
+            const stream = new ReusableReadableStream(value, {
+                streamReplay: this.streamReplay,
+                isTerminalValue: isTerminalResponseStreamEvent,
+            });
             if (this.turnBroadcaster) {
                 return this.pipeAndConsumeStream(stream, turnNumber);
             }
@@ -663,6 +708,17 @@ export class ModelResult {
         if (this.finalResponse) {
             return this.finalResponse;
         }
+        const initialPipePromise = this.initialPipePromise;
+        if (initialPipePromise) {
+            await initialPipePromise;
+        }
+        if (this.initialResponseError) {
+            throw this.initialResponseError;
+        }
+        if (this.initialResponse) {
+            await this.emitPendingModelCallOnce(this.initialResponse);
+            return this.initialResponse;
+        }
         if (this.reusableStream) {
             const response = await consumeStreamForCompletion(this.reusableStream);
             await this.emitPendingModelCallOnce(response);
@@ -670,6 +726,24 @@ export class ModelResult {
         }
         throw new Error('Neither stream nor response initialized');
     }
+    extractCachedCompletion() {
+        if (this.initialResponseError) {
+            throw this.initialResponseError;
+        }
+        if (this.initialResponse) {
+            return this.initialResponse;
+        }
+        if (!this.reusableStream) {
+            throw new Error('Stream not initialized');
+        }
+        return extractCompletionFromBuffer(this.reusableStream);
+    }
+    tryExtractCachedCompletion() {
+        if (this.initialResponse) {
+            return this.initialResponse;
+        }
+        return this.reusableStream ? tryExtractCompletionFromBuffer(this.reusableStream) : undefined;
+    }
     /**
      * Save response output to state.
      * Appends the response output to the message history and records the response ID.
@@ -924,7 +998,7 @@ export class ModelResult {
      * - `execution`: The tool ran. `result` is the ToolExecutionResult.
      *   `effectiveToolCall` reflects any `mutatedInput` piped by PreToolUse.
      */
-    async runToolWithHooks(tool, toolCall, turnContext, onPreliminaryResult, extras) {
+    async runToolWithHooks(tool, toolCall, turnContext, onPreliminaryResult, extras, runPreToolUse = true) {
         // Reject raw-string arguments before any hook fires. When the model
         // produces invalid JSON, the parser leaves `toolCall.arguments` as the
         // raw string; handing that to PreToolUse would either fail payload
@@ -934,23 +1008,6 @@ export class ModelResult {
         // synthetic error without running the tool or firing hooks.
         const rawArgs = toolCall.arguments;
         if (typeof rawArgs === 'string') {
-            // Malformed calls are classic doom-loop fuel: a model stuck emitting
-            // the same invalid JSON re-triggers this parse error forever. Record
-            // the raw string as the call's identity so the streak trips the
-            // detector instead of bouncing off the parse error unbounded. The
-            // parse-error output below already prevents execution, so 'block'
-            // needs no extra handling; 'steer'/'stop' side effects are applied
-            // inside the ordered evaluation.
-            if (this.doomLoopMonitor) {
-                await this.enqueueDoomLoopEvaluation({
-                    toolName: String(toolCall.name),
-                    keyMaterial: rawArgs,
-                    fallbackKeyMaterial: null,
-                    allowBlock: true,
-                    detector: 'tool-fingerprint',
-                    toolCall,
-                });
-            }
             const errorMessage = `Failed to parse tool call arguments for "${toolCall.name}": The model provided invalid JSON. ` +
                 `Raw arguments received: "${rawArgs}". ` +
                 'Please provide valid JSON arguments for this tool call.';
@@ -968,32 +1025,20 @@ export class ModelResult {
                 },
             };
         }
-        // Doom-loop checkpoint — BEFORE PreToolUse, on the arguments the MODEL
-        // issued (pre-mutation): the loop evidence is the model repeating
-        // itself, and a PreToolUse hook that rewrites input each call (e.g.
-        // injecting a nonce) must not mask that repetition. A 'block' verdict
-        // returns the same `hook_blocked` shape as a PreToolUse block, so every
-        // caller handles it identically; PreToolUse deliberately does not fire
-        // for doom-blocked calls (nothing will execute — mirrors parse_error).
-        const doomOutcome = await this.checkDoomLoopBeforeExecution(tool, toolCall);
-        if (doomOutcome.blocked) {
+        const prepared = this.preparedToolCalls.get(toolCall.id);
+        this.preparedToolCalls.delete(toolCall.id);
+        if (prepared?.type === 'blocked') {
             return {
                 type: 'hook_blocked',
                 toolCall,
-                reason: doomOutcome.reason,
-                output: {
-                    type: 'function_call_output',
-                    id: `output_${toolCall.id}`,
-                    callId: toolCall.id,
-                    output: JSON.stringify({
-                        error: doomOutcome.reason,
-                    }),
-                },
+                reason: prepared.reason,
+                output: prepared.output,
             };
         }
-        let effectiveToolCall = toolCall;
-        // Emit PreToolUse hook -- can block or mutate input.
-        if (this.hooksManager) {
+        let effectiveToolCall = prepared?.type === 'ready' ? prepared.toolCall : toolCall;
+        // Emit PreToolUse here only when the approval gate has not already done
+        // so (for example, an approved call resumed from older persisted state).
+        if (this.hooksManager && !prepared && runPreToolUse) {
             // The hook payload coerces null/undefined arguments to {} for schema
             // validation, but `effectiveToolCall.arguments` only changes when the
             // chain reports an actual mutation (`emit.mutated`), so tools that
@@ -1830,7 +1875,7 @@ export class ModelResult {
                     // Sync backward scan of the retained buffer — not a consumer
                     // replay, which would cost one microtask hop per buffered event
                     // on every hook-less streaming teardown.
-                    await this.emitPendingModelCallOnce(extractCompletionFromBuffer(this.reusableStream));
+                    await this.emitPendingModelCallOnce(this.extractCachedCompletion());
                 }
                 else if (this.reusableStream) {
                     // Consumers stop at the terminal event (streamTerminationEvents),
@@ -1841,7 +1886,7 @@ export class ModelResult {
                     // dropping the parked telemetry. Stays silent (no emit, no
                     // throw) when nothing terminal was buffered — e.g. an errored
                     // mid-flight stream, where no materialized response exists.
-                    const buffered = tryExtractCompletionFromBuffer(this.reusableStream);
+                    const buffered = this.tryExtractCachedCompletion();
                     if (buffered) {
                         await this.emitPendingModelCallOnce(buffered);
                     }
@@ -1947,6 +1992,152 @@ export class ModelResult {
             }),
         };
     }
+    async prepareToolCallForApproval(toolCall) {
+        if (!this.hooksManager || typeof toolCall.arguments === 'string') {
+            return toolCall;
+        }
+        const preResult = await this.hooksManager.emit('PreToolUse', {
+            toolName: toolCall.name,
+            toolInput: (toolCall.arguments ?? {}),
+        }, this.hookEmitContext(toolCall.name));
+        if (preResult.blocked) {
+            const block = preResult.results.find((result) => result.block)?.block;
+            const reason = typeof block === 'string' ? block : 'Blocked by PreToolUse hook';
+            this.preparedToolCalls.set(toolCall.id, {
+                type: 'blocked',
+                reason,
+                output: {
+                    type: 'function_call_output',
+                    id: `output_${toolCall.id}`,
+                    callId: toolCall.id,
+                    output: JSON.stringify({
+                        error: reason,
+                    }),
+                },
+            });
+            return toolCall;
+        }
+        const effectiveToolCall = preResult.mutated
+            ? {
+                ...toolCall,
+                arguments: preResult.finalPayload.toolInput,
+            }
+            : toolCall;
+        this.preparedToolCalls.set(toolCall.id, {
+            type: 'ready',
+            toolCall: effectiveToolCall,
+            mutated: preResult.mutated,
+        });
+        return effectiveToolCall;
+    }
+    approvalResponseKey(response) {
+        let occurrence = this.approvalResponseOccurrences.get(response);
+        if (occurrence === undefined) {
+            occurrence = this.nextApprovalResponseOccurrence++;
+            this.approvalResponseOccurrences.set(response, occurrence);
+        }
+        return `${response.id}:${occurrence}`;
+    }
+    approvalGateKey(phase, responseKey, occurrence) {
+        return JSON.stringify([
+            phase,
+            responseKey,
+            occurrence,
+        ]);
+    }
+    assignApprovalCallOccurrences(response, toolCalls) {
+        let identities = this.approvalCallOccurrences.get(response);
+        if (!identities) {
+            identities = [];
+            this.approvalCallOccurrences.set(response, identities);
+        }
+        const occurrences = new Map();
+        for (const [index, toolCall] of toolCalls.entries()) {
+            const identity = identities[index] ?? `call:${this.nextApprovalCallOccurrence++}`;
+            identities[index] = identity;
+            occurrences.set(toolCall, identity);
+        }
+        return occurrences;
+    }
+    /** Re-check only approval sources whose answer can depend on input. */
+    async mutatedInputRequiresApproval(toolCall, context) {
+        const tools = this.options.tools;
+        if (!tools) {
+            return false;
+        }
+        const tool = tools.find((candidate) => isClientTool(candidate) && candidate.function.name === toolCall.name);
+        if (this.requireApprovalFn) {
+            return toolRequiresApproval(toolCall, tools, context, this.requireApprovalFn);
+        }
+        if (!tool || !isClientTool(tool) || typeof tool.function.requireApproval !== 'function') {
+            return false;
+        }
+        return toolRequiresApproval(toolCall, tools, context);
+    }
+    async emitPreparedFailure(toolCall, reason) {
+        if (!this.hooksManager) {
+            return;
+        }
+        await this.hooksManager.emit('PostToolUseFailure', {
+            toolName: toolCall.name,
+            toolInput: (toolCall.arguments ?? {}),
+            error: new Error(reason),
+        }, this.hookEmitContext(toolCall.name));
+    }
+    async blockPreparedToolCall(toolCall, reason) {
+        this.preparedToolCalls.set(toolCall.id, {
+            type: 'blocked',
+            reason,
+            output: {
+                type: 'function_call_output',
+                id: `output_${toolCall.id}`,
+                callId: toolCall.id,
+                output: JSON.stringify({
+                    error: reason,
+                }),
+            },
+        });
+        await this.emitPreparedFailure(toolCall, reason);
+    }
+    async validatePreparedMutation(effective) {
+        const tool = this.options.tools?.find((candidate) => isClientTool(candidate) && candidate.function.name === effective.name);
+        if (!tool || !isClientTool(tool)) {
+            return 'ready';
+        }
+        const parsed = z4.safeParse(tool.function.inputSchema, effective.arguments);
+        if (!parsed.success || !isRecord(parsed.data)) {
+            await this.blockPreparedToolCall(effective, `PreToolUse produced invalid input for "${effective.name}"`);
+            return 'blocked';
+        }
+        return 'ready';
+    }
+    async prepareAfterInitialApproval(toolCall, context, responseKey, occurrence) {
+        const effective = await this.prepareToolCallForApproval(toolCall);
+        const prepared = this.preparedToolCalls.get(toolCall.id);
+        if (prepared?.type !== 'ready' || !prepared.mutated) {
+            return prepared?.type === 'blocked' ? 'blocked' : 'ready';
+        }
+        if ((await this.validatePreparedMutation(effective)) === 'blocked') {
+            return 'blocked';
+        }
+        const key = this.approvalGateKey('mutated', responseKey, occurrence);
+        if (this.completedApprovalGates.has(key)) {
+            return 'ready';
+        }
+        this.completedApprovalGates.add(key);
+        if (!(await this.mutatedInputRequiresApproval(effective, context))) {
+            return 'ready';
+        }
+        const { decision, reason } = await this.emitPermissionRequest(effective);
+        if (decision === 'allow') {
+            return 'ready';
+        }
+        if (decision === 'deny') {
+            await this.blockPreparedToolCall(effective, reason ?? 'Denied by PermissionRequest hook');
+            return 'blocked';
+        }
+        return 'pending';
+    }
     /**
      * Run the UserPromptSubmit hook, supporting both string and structured
      * inputs. If a handler returns a mutated prompt, the returned object
@@ -2054,9 +2245,6 @@ export class ModelResult {
      * @returns Array of unsent tool results for later submission
      */
     async executeAutoApproveTools(toolCalls, turnContext) {
-        // Auto-approved batch = one doom-loop round: identical parallel calls
-        // count once (see beginDoomLoopRound).
-        await this.beginDoomLoopRound(toolCalls);
         const toolCallPromises = toolCalls.map(async (tc) => {
             const tool = this.options.tools?.find((t) => isClientTool(t) && t.function.name === tc.name);
             if (!tool || !isAutoResolvableTool(tool)) {
@@ -2067,7 +2255,7 @@ export class ModelResult {
             // JSON-parse failures so hooks never see a malformed payload.
             const hookOutcome = await this.runToolWithHooks(tool, tc, turnContext);
             if (hookOutcome.type === 'parse_error') {
-                this.broadcastToolResult(tc.id, isMcpTool(tool) ? 'mcp' : 'client', {
+                this.broadcastToolResult(tc.id, String(tc.name), isMcpTool(tool) ? 'mcp' : 'client', {
                     error: hookOutcome.errorMessage,
                 });
                 return createRejectedResult(tc.id, String(tc.name), hookOutcome.errorMessage);
@@ -2107,52 +2295,70 @@ export class ModelResult {
         }
         return results;
     }
-    /**
-     * Check for tools requiring approval and handle accordingly.
-     * Partitions tool calls into those needing approval and those that can auto-execute.
-     *
-     * @param toolCalls - The tool calls to check
-     * @param currentRound - The current execution round (1-indexed)
-     * @param currentResponse - The current response to save if pausing
-     * @returns True if execution should pause for approval, false to continue
-     * @throws Error if approval is required but no state accessor is configured
-     */
-    async handleApprovalCheck(toolCalls, currentRound, currentResponse) {
-        if (!this.options.tools) {
-            return false;
+    async classifyInitialApprovalCalls(toolCalls, responseKey, occurrences) {
+        const unseenCalls = [];
+        const blockedCalls = [];
+        const unseenKeys = toolCalls.filter((toolCall) => !this.completedApprovalGates.has(this.approvalGateKey('initial', responseKey, occurrences.get(toolCall) ?? '')));
+        await this.beginDoomLoopRound(unseenKeys);
+        for (const toolCall of toolCalls) {
+            const key = this.approvalGateKey('initial', responseKey, occurrences.get(toolCall) ?? '');
+            if (this.completedApprovalGates.has(key)) {
+                continue;
+            }
+            this.completedApprovalGates.add(key);
+            const tool = this.options.tools?.find((candidate) => isClientTool(candidate) && candidate.function.name === toolCall.name);
+            if (tool && isAutoResolvableTool(tool)) {
+                const rawArgs = toolCall.arguments;
+                const doomOutcome = typeof rawArgs === 'string' && this.doomLoopMonitor
+                    ? await this.enqueueDoomLoopEvaluation({
+                        toolName: String(toolCall.name),
+                        keyMaterial: rawArgs,
+                        fallbackKeyMaterial: null,
+                        allowBlock: true,
+                        detector: 'tool-fingerprint',
+                        toolCall,
+                    }).then((decision) => ({
+                        blocked: decision.action === 'block' || decision.action === 'stop',
+                        reason: decision.message ?? 'Blocked by doom loop',
+                    }))
+                    : await this.checkDoomLoopBeforeExecution(tool, toolCall);
+                if (doomOutcome.blocked) {
+                    this.preparedToolCalls.set(toolCall.id, {
+                        type: 'blocked',
+                        reason: doomOutcome.reason,
+                        output: {
+                            type: 'function_call_output',
+                            id: `output_${toolCall.id}`,
+                            callId: toolCall.id,
+                            output: JSON.stringify({
+                                error: doomOutcome.reason,
+                            }),
+                        },
+                    });
+                    blockedCalls.push(toolCall);
+                    continue;
+                }
+            }
+            unseenCalls.push(toolCall);
         }
-        const turnContext = {
-            numberOfTurns: currentRound,
-            // context is handled via contextStore, not on TurnContext
+        return {
+            unseenCalls,
+            blockedCalls,
         };
-        const { requiresApproval: needsApproval, autoExecute } = await partitionToolCalls(toolCalls, this.options.tools, turnContext, this.requireApprovalFn ?? undefined);
-        // Nothing needs an approval gate: return immediately WITHOUT executing
-        // anything. The main loop's executeToolRound runs every call exactly
-        // once; pre-executing here would double-run side-effecting tools.
-        if (needsApproval.length === 0) {
-            return false;
-        }
-        // Run the PermissionRequest hook for each tool that needs approval.
-        // This lets hooks short-circuit the approval flow in either direction:
-        // 'allow' promotes the call past the gate (executed once by the normal
-        // round), 'deny' synthesizes a rejection (recorded so the round emits a
-        // rejected output instead of executing), 'ask_user' falls through to the
-        // human approval flow.
+    }
+    async resolveApprovalPhases(needsApproval, autoExecute, turnContext, responseKey, occurrences) {
         const denied = [];
         const stillPending = [];
         if (this.hooksManager) {
             for (const tc of needsApproval) {
                 const { decision, reason } = await this.emitPermissionRequest(tc);
-                if (decision === 'allow') {
-                    // Promoted past the gate; the normal tool round executes it once.
-                }
-                else if (decision === 'deny') {
+                if (decision === 'deny') {
                     denied.push({
                         tc,
                         reason: reason ?? 'Denied by PermissionRequest hook',
                     });
                 }
-                else {
+                else if (decision !== 'allow') {
                     stillPending.push(tc);
                 }
             }
@@ -2160,10 +2366,59 @@ export class ModelResult {
         else {
             stillPending.push(...needsApproval);
         }
+        const initialSurvivors = [
+            ...autoExecute,
+            ...needsApproval.filter((tc) => !stillPending.some((pending) => pending.id === tc.id) &&
+                !denied.some((entry) => entry.tc.id === tc.id)),
+        ];
+        for (const toolCall of initialSurvivors) {
+            const tool = this.options.tools?.find((candidate) => isClientTool(candidate) && candidate.function.name === toolCall.name);
+            if (!tool || !isAutoResolvableTool(tool)) {
+                continue;
+            }
+            if ((await this.prepareAfterInitialApproval(toolCall, turnContext, responseKey, occurrences.get(toolCall) ?? '')) === 'pending') {
+                const prepared = this.preparedToolCalls.get(toolCall.id);
+                if (prepared?.type === 'ready') {
+                    stillPending.push(prepared.toolCall);
+                }
+            }
+        }
+        return {
+            denied,
+            stillPending,
+            initialSurvivors,
+        };
+    }
+    /**
+     * Check for tools requiring approval and handle accordingly.
+     * Partitions tool calls into those needing approval and those that can auto-execute.
+     *
+     * @param toolCalls - The tool calls to check
+     * @param currentRound - The current execution round (1-indexed)
+     * @param currentResponse - The current response to save if pausing
+     * @returns True if execution should pause for approval, false to continue
+     * @throws Error if approval is required but no state accessor is configured
+     */
+    async handleApprovalCheck(suppliedToolCalls, currentRound, currentResponse) {
+        if (!this.options.tools) {
+            return false;
+        }
+        const turnContext = {
+            numberOfTurns: currentRound,
+        };
+        const responseKey = this.approvalResponseKey(currentResponse);
+        // Always enumerate the complete response so subset visits find the original
+        // response-local occurrence and appended calls receive fresh identities.
+        const responseToolCalls = extractToolCallsFromResponse(currentResponse);
+        const toolCalls = responseToolCalls.length > 0 ? responseToolCalls : suppliedToolCalls;
+        const occurrences = this.assignApprovalCallOccurrences(currentResponse, toolCalls);
+        const { unseenCalls, blockedCalls } = await this.classifyInitialApprovalCalls(toolCalls, responseKey, occurrences);
+        if (unseenCalls.length === 0 && blockedCalls.length === 0) {
+            return false;
+        }
+        const { requiresApproval: needsApproval, autoExecute } = await partitionToolCalls(unseenCalls, this.options.tools, turnContext, this.requireApprovalFn ?? undefined);
+        const { denied, stillPending, initialSurvivors } = await this.resolveApprovalPhases(needsApproval, autoExecute, turnContext, responseKey, occurrences);
         if (stillPending.length === 0) {
-            // The hook resolved every gated call, so we do not pause. Record denied
-            // calls so executeToolRound synthesizes rejections instead of running
-            // them; allowed calls execute once via the normal round.
             for (const d of denied) {
                 this.hookDeniedCalls.set(d.tc.id, d.reason);
             }
@@ -2178,7 +2433,12 @@ export class ModelResult {
         // We are pausing: the normal tool round will NOT run for this response,
         // so execute the auto-approved calls now and persist their results as
         // unsent so the resume path can pick them up without re-executing.
-        const unsentResults = await this.executeAutoApproveTools(autoExecute, turnContext);
+        const pendingIds = new Set(stillPending.map((call) => call.id));
+        const executableNow = [
+            ...initialSurvivors.filter((call) => !pendingIds.has(call.id)),
+            ...blockedCalls,
+        ];
+        const unsentResults = await this.executeAutoApproveTools(executableNow, turnContext);
         // Combine pre-denied results (from hook "deny") with executed results.
         const combinedResults = [
             ...unsentResults,
@@ -2186,13 +2446,20 @@ export class ModelResult {
         ];
         // Save state with pending approvals (only reached when stillPending > 0).
         const stateUpdates = {
-            pendingToolCalls: stillPending,
+            pendingToolCalls: stillPending.map((toolCall) => ({
+                ...toolCall,
+                ...(this.preparedToolCalls.has(toolCall.id) && {
+                    preToolUseApplied: true,
+                }),
+            })),
             status: 'awaiting_approval',
         };
         if (combinedResults.length > 0) {
             stateUpdates.unsentToolResults = combinedResults;
         }
         await this.saveStateSafely(stateUpdates);
+        this.preparedToolCalls.clear();
+        this.hookDeniedCalls.clear();
         this.finalResponse = currentResponse;
         return true; // Pause for approval
     }
@@ -2315,7 +2582,7 @@ export class ModelResult {
             // Emit the canonical tool.result event with the FINAL value so
             // consumers watching only tool.result see real results exactly once.
             if (task.status === 'completed') {
-                this.broadcastToolResult(task.callId, this.toolSourceByName(task.name), task.result);
+                this.broadcastToolResult(task.callId, String(task.name), this.toolSourceByName(String(task.name)), task.result);
             }
             // PostToolUse/PostToolUseFailure fire at SETTLEMENT for async tools —
             // the observation-only audit surface (secret scanning, output review)
@@ -2450,7 +2717,7 @@ export class ModelResult {
             ? (callId, resultValue) => {
                 const typedResult = resultValue;
                 preliminaryResultsForCall.push(typedResult);
-                this.broadcastPreliminaryResult(callId, typedResult);
+                this.broadcastPreliminaryResult(callId, String(toolCall.name), typedResult);
             }
             : undefined;
         // Compose the per-call abort signal (run signal + tool/run timeout +
@@ -2503,7 +2770,7 @@ export class ModelResult {
                 return this.buildToolTimeoutOutcome(toolCall, tool, timeoutMs, preliminaryResultsForCall);
             }
             if (executed.type === 'parse_error') {
-                this.broadcastToolResult(toolCall.id, isMcpTool(tool) ? 'mcp' : 'client', {
+                this.broadcastToolResult(toolCall.id, String(toolCall.name), isMcpTool(tool) ? 'mcp' : 'client', {
                     error: executed.errorMessage,
                 });
                 return executed;
@@ -2557,7 +2824,7 @@ export class ModelResult {
      */
     buildToolTimeoutOutcome(toolCall, tool, timeoutMs, preliminaryResultsForCall) {
         const message = `Tool "${toolCall.name}" timed out after ${timeoutMs}ms`;
-        this.broadcastToolResult(toolCall.id, isMcpTool(tool) ? 'mcp' : 'client', {
+        this.broadcastToolResult(toolCall.id, String(toolCall.name), isMcpTool(tool) ? 'mcp' : 'client', {
             error: message,
         });
         return {
@@ -2624,9 +2891,6 @@ export class ModelResult {
         });
     }
     async executeToolRound(toolCalls, turnContext) {
-        // One executed batch = one doom-loop round: identical parallel calls in
-        // this batch count as ONE piece of loop evidence and share a decision.
-        await this.beginDoomLoopRound(toolCalls);
         const toolCallPromises = toolCalls.map((toolCall) => this.executeSingleToolCall(toolCall, turnContext));
         const settledResults = await Promise.allSettled(toolCallPromises);
         const toolResults = [];
@@ -2654,7 +2918,7 @@ export class ModelResult {
             if (settled.status === 'rejected') {
                 const errorMessage = settled.reason instanceof Error ? settled.reason.message : String(settled.reason);
                 // `runToolWithHooks` is the single point of emission for PostToolUseFailure.
-                this.broadcastToolResult(originalToolCall.id, this.toolSourceByName(originalToolCall.name), {
+                this.broadcastToolResult(originalToolCall.id, String(originalToolCall.name), this.toolSourceByName(String(originalToolCall.name)), {
                     error: errorMessage,
                 });
                 const rejectedOutput = {
@@ -2716,7 +2980,7 @@ export class ModelResult {
                     error: value.result.error.message,
                 }
                 : value.result.result);
-            this.broadcastToolResult(value.toolCall.id, isMcpTool(value.tool) ? 'mcp' : 'client', toolResult, value.preliminaryResultsForCall.length > 0 ? value.preliminaryResultsForCall : undefined);
+            this.broadcastToolResult(value.toolCall.id, String(value.toolCall.name), isMcpTool(value.tool) ? 'mcp' : 'client', toolResult, value.preliminaryResultsForCall.length > 0 ? value.preliminaryResultsForCall : undefined);
             const outputForModel = await this.computeToolOutputForModel(value);
             const executedOutput = {
                 type: 'function_call_output',
@@ -2851,7 +3115,7 @@ export class ModelResult {
                 // would be a double delivery).
                 registry.untrack(toolCall.id);
                 if (settled.outcome === 'ok') {
-                    this.broadcastToolResult(toolCall.id, source, settled.result);
+                    this.broadcastToolResult(toolCall.id, String(toolCall.name), source, settled.result);
                     const outputForModel = await this.computeToolOutputForModel({
                         toolCall,
                         tool,
@@ -2869,7 +3133,7 @@ export class ModelResult {
                     };
                 }
                 const message = settled.error instanceof Error ? settled.error.message : String(settled.error);
-                this.broadcastToolResult(toolCall.id, source, {
+                this.broadcastToolResult(toolCall.id, String(toolCall.name), source, {
                     error: message,
                 });
                 return {
@@ -2914,7 +3178,7 @@ export class ModelResult {
             return null;
         }
         const message = `Tool "${toolCall.name}": ctx.defer() taskId "${taskId}" is already in use by another pending task in this conversation (call ${duplicate.callId}). Task ids must be unique per conversation — include a per-call component (e.g. the ticket id plus your callId).`;
-        this.broadcastToolResult(toolCall.id, source, {
+        this.broadcastToolResult(toolCall.id, String(toolCall.name), source, {
             error: message,
         });
         return {
@@ -3120,7 +3384,7 @@ export class ModelResult {
         const taskTool = buildTaskToolStub();
         const answer = (result, error) => {
             if (error === undefined) {
-                this.broadcastToolResult(toolCall.id, 'client', result);
+                this.broadcastToolResult(toolCall.id, String(toolCall.name), 'client', result);
             }
             return {
                 type: 'execution',
@@ -3323,9 +3587,23 @@ export class ModelResult {
             return;
         }
         const computedParams = await executeNextTurnParamsFunctions(toolCalls, this.options.tools, this.resolvedRequest);
-        if (Object.keys(computedParams).length > 0) {
-            this.resolvedRequest = applyNextTurnParamsToRequest(this.resolvedRequest, computedParams);
+        if (Object.keys(computedParams).length === 0) {
+            return;
         }
+        const nextRequest = applyNextTurnParamsToRequest(this.resolvedRequest, computedParams);
+        /*
+         * A tool-computed `toolChoice` becomes the new caller-level policy, not a
+         * one-turn override. Merging it onto the request alone is not enough:
+         * `makeFollowupRequest` re-derives the wire choice from
+         * `configuredToolChoice` via `applyForcedToolChoicePolicy`, which would
+         * discard the tool's value before dispatch. Re-running the resolved-policy
+         * bookkeeping re-stamps the configured choice and its forced-choice
+         * consumption key together, so relaxation stays consistent for later turns.
+         */
+        this.resolvedRequest =
+            'toolChoice' in computedParams
+                ? this.applyResolvedForcedToolChoicePolicy(nextRequest)
+                : nextRequest;
     }
     /**
      * Make a follow-up API request with tool results.
@@ -3781,8 +4059,12 @@ export class ModelResult {
         // `clientOnlyFields` in async-params.ts, which handles the async path.
         // (`sharedContextSchema` is absent here: call-model.ts destructures it
         // before the request reaches ModelResult.)
-        const { stopWhen: _, state: _s, requireApproval: _r, approveToolCalls: _a, rejectToolCalls: _rj, context: _c, onTurnStart: _ots, onTurnEnd: _ote, allowFinalResponse: _afr, strictFinalResponse: _sfr, hooks: _h, doomLoop: _dl, signal: _sig, toolTimeoutMs: _ttm, toolConcurrency: _tc, asyncTools: _at, ...rest } = this.options.request;
-        return this.applyResolvedForcedToolChoicePolicy(rest);
+        const { stopWhen: _, state: _s, requireApproval: _r, approveToolCalls: _a, rejectToolCalls: _rj, context: _c, onTurnStart: _ots, onTurnEnd: _ote, allowFinalResponse: _afr, strictFinalResponse: _sfr, hooks: _h, doomLoop: _dl, streamReplay: _sr, signal: _sig, toolTimeoutMs: _ttm, toolConcurrency: _tc, asyncTools: _at, activeTools: _activeTools, ...rest } = this.options.request;
+        const resolved = {
+            ...rest,
+        };
+        stripToolSetSnapshotMetadata(resolved);
+        return this.applyResolvedForcedToolChoicePolicy(resolved);
     }
     /**
      * Record the freshly-resolved caller choice before deriving its wire value.
@@ -4282,7 +4564,7 @@ export class ModelResult {
             // Handle both streaming and non-streaming responses
             // The API may return a non-streaming response even when stream: true is requested
             if (isEventStream(apiResult.value)) {
-                this.reusableStream = new ReusableReadableStream(apiResult.value);
+                this.setReusableStream(apiResult.value);
             }
             else if (this.isNonStreamingResponse(apiResult.value)) {
                 // API returned a complete response directly - use it as the final response
@@ -4311,19 +4593,12 @@ export class ModelResult {
             numberOfTurns: this.allToolExecutionRounds.length + 1,
             // context is handled via contextStore, not on TurnContext
         };
+        // Calls that pause again after PreToolUse mutation remain pending without
+        // re-running the hook on the next resume.
+        const secondGatePausedIds = new Set();
         // Track approved HITL calls that paused (onToolCalled returned null) —
         // these stay in pendingToolCalls so the caller can resume them later.
         const hitlPausedIds = new Set();
-        // The approved batch is one doom-loop round: N approved duplicates of
-        // the same call count once (the sequential loop below still evaluates
-        // in order; restored streaks from the persisted state carry forward).
-        // Declared from the approved calls only — a pending call the user did not
-        // approve is not part of this round.
-        await this.beginDoomLoopRound([
-            ...this.approvedToolCalls,
-        ]
-            .map((callId) => pendingCalls.find((tc) => tc.id === callId))
-            .filter((tc) => tc !== undefined));
         // Process approvals - execute the approved tools. Route through
         // runToolWithHooks so PreToolUse/PostToolUse fire even on this path.
         for (const callId of this.approvedToolCalls) {
@@ -4337,9 +4612,22 @@ export class ModelResult {
                 unsentResults.push(createRejectedResult(callId, String(toolCall.name), 'Tool not found or not executable'));
                 continue;
             }
-            const hookOutcome = await this.runToolWithHooks(tool, toolCall, turnContext);
+            if (toolCall.preToolUseApplied !== true) {
+                const prepared = await this.prepareAfterInitialApproval(toolCall, turnContext, `persisted:${this.currentState.previousResponseId ?? 'unknown'}`, callId);
+                if (prepared === 'pending') {
+                    const ready = this.preparedToolCalls.get(callId);
+                    if (ready?.type === 'ready') {
+                        Object.assign(toolCall, ready.toolCall, {
+                            preToolUseApplied: true,
+                        });
+                    }
+                    secondGatePausedIds.add(callId);
+                    continue;
+                }
+            }
+            const hookOutcome = await this.runToolWithHooks(tool, toolCall, turnContext, undefined, undefined, false);
             if (hookOutcome.type === 'parse_error') {
-                this.broadcastToolResult(callId, this.toolSourceByName(String(toolCall.name)), {
+                this.broadcastToolResult(callId, String(toolCall.name), this.toolSourceByName(String(toolCall.name)), {
                     error: hookOutcome.errorMessage,
                 });
                 unsentResults.push(createRejectedResult(callId, String(toolCall.name), hookOutcome.errorMessage));
@@ -4373,7 +4661,13 @@ export class ModelResult {
             if (!toolCall) {
                 continue;
             }
-            unsentResults.push(createRejectedResult(callId, String(toolCall.name), 'Rejected by user'));
+            const reason = 'Rejected by user';
+            if (toolCall.preToolUseApplied === true) {
+                await this.emitPreparedFailure(toolCall, reason);
+            }
+            this.preparedToolCalls.delete(callId);
+            this.hookDeniedCalls.delete(callId);
+            unsentResults.push(createRejectedResult(callId, String(toolCall.name), reason));
         }
         // Remove processed calls from pending. Approved HITL calls that paused are
         // NOT considered processed — they stay on pendingToolCalls so getPendingToolCalls()
@@ -4381,7 +4675,7 @@ export class ModelResult {
         const processedIds = new Set([
             ...this.approvedToolCalls,
             ...this.rejectedToolCalls,
-        ].filter((id) => !hitlPausedIds.has(id)));
+        ].filter((id) => !hitlPausedIds.has(id) && !secondGatePausedIds.has(id)));
         const remainingPending = pendingCalls.filter((tc) => !processedIds.has(tc.id));
         // Determine status:
         //   - Any still-unprocessed approval-required call keeps us in 'awaiting_approval'
@@ -4432,6 +4726,8 @@ export class ModelResult {
         // user message between dangling function_calls and their future
         // outputs would be invalid history).
         if (nextStatus !== 'in_progress') {
+            this.preparedToolCalls.clear();
+            this.hookDeniedCalls.clear();
             return;
         }
         // A doom-stop armed while executing the approved calls (the restored
@@ -4506,7 +4802,7 @@ export class ModelResult {
         }
         // Handle both streaming and non-streaming responses
         if (isEventStream(apiResult.value)) {
-            this.reusableStream = new ReusableReadableStream(apiResult.value);
+            this.setReusableStream(apiResult.value);
         }
         else if (this.isNonStreamingResponse(apiResult.value)) {
             this.finalResponse = apiResult.value;
@@ -4794,6 +5090,24 @@ export class ModelResult {
                     pendingToolCalls.length > 0 &&
                     this.hasExecutableToolCalls(pendingToolCalls)) {
                     const turnNumber = currentRound + 1;
+                    // Gate these calls exactly like a normal round would. This path
+                    // executes real tools, so it needs the same approval check as the
+                    // in-loop call sites above — without it, `stopWhen` firing on a turn
+                    // that carries a `requireApproval` call would run that call
+                    // unguarded, and hook-based 'deny' would never fire either (the
+                    // deny bookkeeping lives inside handleApprovalCheck).
+                    //
+                    // On pause, handleApprovalCheck persists `pendingToolCalls` +
+                    // status 'awaiting_approval', executes any auto-approved calls as
+                    // unsent results, and sets `finalResponse` — so returning here is
+                    // safe: nothing executed, so there is no round to record, and we
+                    // must NOT fall through to markStateComplete() or the final
+                    // text-coercion request. `sessionEndReason` stays 'max_turns' —
+                    // accurate (the loop did stop on the stop condition) and consistent
+                    // with the HITL pause return further down this same block.
+                    if (await this.handleApprovalCheck(pendingToolCalls, turnNumber, currentResponse)) {
+                        return;
+                    }
                     const turnContext = {
                         numberOfTurns: turnNumber,
                     };
@@ -5352,10 +5666,12 @@ export class ModelResult {
                     continue;
                 }
                 if (event.type === 'tool.preliminary_result') {
+                    const prelim = event;
                     yield {
                         type: 'preliminary_result',
-                        toolCallId: event.toolCallId,
-                        result: event.result,
+                        toolCallId: prelim.toolCallId,
+                        toolName: prelim.toolName,
+                        result: prelim.result,
                     };
                 }
             }
@@ -5379,7 +5695,7 @@ export class ModelResult {
         if (!this.reusableStream) {
             throw new Error('Stream not initialized');
         }
-        const completedResponse = await consumeStreamForCompletion(this.reusableStream);
+        const completedResponse = await this.getInitialResponse();
         await this.emitPendingModelCallOnce(completedResponse);
         return extractToolCallsFromResponse(completedResponse);
     }
@@ -5652,7 +5968,7 @@ export class ModelResult {
                 // reusable stream is a passive observation: it buffers events
                 // without executing tools or mutating conversation state, so the
                 // resume generation is counted without advancing the loop.
-                await this.emitPendingModelCallOnce(await consumeStreamForCompletion(this.reusableStream));
+                await this.emitPendingModelCallOnce(await this.getInitialResponse());
             }
         }
         catch (error) {