@openrouter/agent 0.4.0 → 0.6.0

package/esm/lib/model-result.js

@@ -3,18 +3,13 @@ import { hasAsyncFunctions, resolveAsyncFunctions } from './async-params.js';
 import { appendToMessages, createInitialState, createRejectedResult, createUnsentResult, extractTextFromResponse as extractTextFromResponseState, partitionToolCalls, unsentResultsToAPIFormat, updateState, } from './conversation-state.js';
 import { applyNextTurnParamsToRequest, executeNextTurnParamsFunctions, } from './next-turn-params.js';
 import { ReusableReadableStream } from './reusable-stream.js';
-import { isStopConditionMet, stepCountIs } from './stop-conditions.js';
+import { isStopConditionMet } from './stop-conditions.js';
 import { buildItemsStream, buildResponsesMessageStream, buildToolCallStream, consumeStreamForCompletion, extractReasoningDeltas, extractResponsesMessageFromResponse, extractTextDeltas, extractTextFromResponse, extractToolCallsFromResponse, extractToolDeltas, itemsStreamHandlers, streamTerminationEvents, } from './stream-transformers.js';
 import { hasTypeProperty, isFunctionCallItem, isFunctionCallOutputItem, isOutputTextDeltaEvent, isReasoningDeltaEvent, isResponseCompletedEvent, isResponseFailedEvent, isResponseIncompleteEvent, isServerToolResultItem, } from './stream-type-guards.js';
 import { resolveContext, ToolContextStore } from './tool-context.js';
 import { ToolEventBroadcaster } from './tool-event-broadcaster.js';
-import { executeTool } from './tool-executor.js';
-import { hasExecuteFunction, isClientTool, isServerTool, isToolCallOutputEvent, } from './tool-types.js';
-/**
- * Default maximum number of tool execution steps if no stopWhen is specified.
- * This prevents infinite loops in tool execution.
- */
-const DEFAULT_MAX_STEPS = 5;
+import { applyOnResponseReceivedHooks, executeTool } from './tool-executor.js';
+import { isAutoResolvableTool, isClientTool, isServerTool, isToolCallOutputEvent, } from './tool-types.js';
 /**
  * Typeguard for plain-object records (non-null, non-array).
  */
@@ -22,21 +17,31 @@ function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 /**
- * Type guard for stream event with toReadableStream method
- * Checks constructor name, prototype, and method availability
+ * Human-readable label for a value that failed the `isRecord` check. Used
+ * exclusively to make `toModelOutput` misuse errors specific.
+ */
+function describeNonRecord(value) {
+    if (value === null) {
+        return 'null';
+    }
+    if (Array.isArray(value)) {
+        return 'array';
+    }
+    return typeof value;
+}
+/**
+ * Type guard for stream event responses
+ * Checks constructor name and readable stream behavior
  */
 function isEventStream(value) {
     if (value === null || typeof value !== 'object') {
         return false;
     }
-    // Check constructor name for EventStream
-    const constructorName = Object.getPrototypeOf(value)?.constructor?.name;
-    if (constructorName === 'EventStream') {
+    if (typeof ReadableStream !== 'undefined' && value instanceof ReadableStream) {
         return true;
     }
-    // Fallback: check for toReadableStream method (may be on prototype)
     const maybeStream = value;
-    return typeof maybeStream.toReadableStream === 'function';
+    return typeof maybeStream.getReader === 'function';
 }
 /**
  * A wrapper around a streaming response that provides multiple consumption patterns.
@@ -242,13 +247,10 @@ export class ModelResult {
     }
     /**
      * Type guard to check if a value is a non-streaming response
-     * Only requires 'output' field and absence of 'toReadableStream' method
+     * Only requires 'output' field and absence of readable stream behavior
      */
     isNonStreamingResponse(value) {
-        return (value !== null &&
-            typeof value === 'object' &&
-            'output' in value &&
-            !('toReadableStream' in value));
+        return (value !== null && typeof value === 'object' && 'output' in value && !isEventStream(value));
     }
     // =========================================================================
     // Extracted Helper Methods for executeToolsIfNeeded
@@ -346,11 +348,16 @@ export class ModelResult {
      * Returns true if execution should stop.
      *
      * @remarks
-     * Default: stepCountIs(DEFAULT_MAX_STEPS) if no stopWhen is specified.
+     * When no `stopWhen` is specified, this returns false and execution stops
+     * only when the model produces a turn without tool calls. Pass an explicit
+     * `stopWhen` (e.g. `stepCountIs(n)`, `maxCost(...)`) to bound the loop.
      * This evaluates stop conditions against the complete step history.
      */
     async shouldStopExecution() {
-        const stopWhen = this.options.stopWhen ?? stepCountIs(DEFAULT_MAX_STEPS);
+        const { stopWhen } = this.options;
+        if (stopWhen === undefined) {
+            return false;
+        }
         const stopConditions = Array.isArray(stopWhen)
             ? stopWhen
             : [
@@ -380,21 +387,32 @@ export class ModelResult {
         });
     }
     /**
-     * Check if any tool calls have execute functions.
+     * Check if any tool calls can be auto-resolved in the current turn.
      * Used to determine if automatic tool execution should be attempted.
      *
+     * A tool call is auto-resolvable if its tool has either an `execute` function
+     * (regular or generator) or an `onToolCalled` hook (HITL). HITL tools are
+     * included here because their hook fires before the model's follow-up request,
+     * even when the hook ultimately decides to pause by returning `null`.
+     *
      * @param toolCalls - The tool calls to check
-     * @returns True if at least one tool call has an executable function
+     * @returns True if at least one tool call is auto-resolvable
      */
     hasExecutableToolCalls(toolCalls) {
         return toolCalls.some((toolCall) => {
             const tool = this.options.tools?.find((t) => isClientTool(t) && t.function.name === toolCall.name);
-            return tool && hasExecuteFunction(tool);
+            return tool && isAutoResolvableTool(tool);
         });
     }
+    /**
+     * A manual tool call is one whose tool has neither an `execute` function nor
+     * an `onToolCalled` hook — i.e. the caller is expected to produce the output
+     * externally. HITL tools are auto-resolvable even when they pause, so they
+     * are not classified as manual here.
+     */
     isManualToolCall(item) {
         const tool = this.options.tools?.find((t) => isClientTool(t) && t.function.name === item.name);
-        return !!tool && !hasExecuteFunction(tool);
+        return !!tool && !isAutoResolvableTool(tool);
     }
     /**
      * Execute tools that can auto-execute (don't require approval) in parallel.
@@ -406,10 +424,14 @@ export class ModelResult {
     async executeAutoApproveTools(toolCalls, turnContext) {
         const toolCallPromises = toolCalls.map(async (tc) => {
             const tool = this.options.tools?.find((t) => isClientTool(t) && t.function.name === tc.name);
-            if (!tool || !hasExecuteFunction(tool)) {
+            if (!tool || !isAutoResolvableTool(tool)) {
                 return null;
             }
             const result = await executeTool(tool, tc, turnContext, undefined, this.contextStore ?? undefined, this.options.sharedContextSchema);
+            if (result === null) {
+                // HITL tool paused — no unsent result for this call in this round
+                return null;
+            }
             if (result.error) {
                 return createRejectedResult(tc.id, String(tc.name), result.error.message);
             }
@@ -476,18 +498,81 @@ export class ModelResult {
         this.finalResponse = currentResponse;
         return true; // Pause for approval
     }
+    /**
+     * Persist state when one or more HITL tools paused during a round.
+     *
+     * Mirrors `handleApprovalCheck` so paused HITL calls are surfaced through
+     * `pendingToolCalls` (visible via `getPendingToolCalls()` / `getState()`).
+     * Sets the status to `awaiting_hitl` so the caller can discriminate HITL
+     * pauses from approval pauses.
+     *
+     * Already-executed results from the same round are persisted on the turn's
+     * message history via `saveToolResultsToState` (called by the outer loop
+     * before this helper) — no need to duplicate them in `unsentToolResults`.
+     *
+     * @param currentResponse - The response that produced the paused tool calls
+     * @param pausedCalls - HITL tool calls whose `onToolCalled` returned `null`
+     */
+    async persistHitlPause(currentResponse, pausedCalls) {
+        this.finalResponse = currentResponse;
+        if (!this.stateAccessor) {
+            return;
+        }
+        const stateUpdates = {
+            pendingToolCalls: pausedCalls,
+            status: 'awaiting_hitl',
+        };
+        await this.saveStateSafely(stateUpdates);
+    }
+    /**
+     * Compute the `output` payload sent to the model for a successfully
+     * settled tool execution. Routes through `toModelOutput` when the tool
+     * defines one (which may itself throw to surface an error), falls back to
+     * `JSON.stringify(result)` otherwise, and emits an error envelope when the
+     * executor itself reported an error.
+     */
+    async computeToolOutputForModel(value) {
+        if (value.result.error) {
+            return JSON.stringify({
+                error: value.result.error.message,
+            });
+        }
+        if (!isAutoResolvableTool(value.tool) || !value.tool.function.toModelOutput) {
+            return JSON.stringify(value.result.result);
+        }
+        // Arguments have already been validated upstream by the tool's Zod
+        // inputSchema (which must be a ZodObject), so the runtime shape is
+        // always a record here. A non-record value here signals a real upstream
+        // bug we want surfaced, not a case to paper over with `{}`.
+        const rawArgs = value.toolCall.arguments;
+        if (!isRecord(rawArgs)) {
+            throw new Error(`toolCall.arguments for "${value.toolCall.name}" must be an object after Zod validation, got ${describeNonRecord(rawArgs)}`);
+        }
+        const modelOutputResult = await value.tool.function.toModelOutput({
+            output: value.result.result,
+            input: rawArgs,
+        });
+        if (modelOutputResult.type === 'content') {
+            return modelOutputResult.value;
+        }
+        return JSON.stringify(value.result.result);
+    }
     /**
      * Execute all tools in a single round in parallel.
      * Emits tool.result events after tool execution completes.
      *
      * @param toolCalls - The tool calls to execute
      * @param turnContext - The current turn context
-     * @returns Array of function call outputs formatted for the API
+     * @returns Object with the function call outputs formatted for the API and
+     *   the list of HITL tool calls that paused (returned `null` from
+     *   `onToolCalled`). Callers should break out of the execution loop when
+     *   `pausedCalls` is non-empty rather than sending an incomplete set of
+     *   outputs back to the model.
      */
     async executeToolRound(toolCalls, turnContext) {
         const toolCallPromises = toolCalls.map(async (toolCall) => {
             const tool = this.options.tools?.find((t) => isClientTool(t) && t.function.name === toolCall.name);
-            if (!tool || !hasExecuteFunction(tool)) {
+            if (!tool || !isAutoResolvableTool(tool)) {
                 return null;
             }
             // Check if arguments failed to parse (remained as string instead of object)
@@ -523,6 +608,13 @@ export class ModelResult {
                 }
                 : undefined;
             const result = await executeTool(tool, toolCall, turnContext, onPreliminaryResult, this.contextStore ?? undefined, this.options.sharedContextSchema);
+            if (result === null) {
+                // HITL tool paused — surface as manual (no output this round)
+                return {
+                    type: 'paused',
+                    toolCall,
+                };
+            }
             return {
                 type: 'execution',
                 toolCall,
@@ -533,6 +625,7 @@ export class ModelResult {
         });
         const settledResults = await Promise.allSettled(toolCallPromises);
         const toolResults = [];
+        const pausedCalls = [];
         for (let i = 0; i < settledResults.length; i++) {
             const settled = settledResults[i];
             const originalToolCall = toolCalls[i];
@@ -573,42 +666,21 @@ export class ModelResult {
                 });
                 continue;
             }
+            if (value.type === 'paused') {
+                // HITL tool returned null — record the pause so the caller can break
+                // out of the outer loop before attempting a follow-up request with an
+                // incomplete set of outputs. The call will be surfaced via state
+                // (pendingToolCalls + status='awaiting_hitl') for manual resume.
+                pausedCalls.push(value.toolCall);
+                continue;
+            }
             const toolResult = (value.result.error
                 ? {
                     error: value.result.error.message,
                 }
                 : value.result.result);
             this.broadcastToolResult(value.toolCall.id, toolResult, value.preliminaryResultsForCall.length > 0 ? value.preliminaryResultsForCall : undefined);
-            let outputForModel;
-            if (value.result.error) {
-                outputForModel = JSON.stringify({
-                    error: value.result.error.message,
-                });
-            }
-            else if (value.tool.function.toModelOutput) {
-                // toModelOutput exists - call it (may throw, which surfaces the error).
-                // Arguments have already been validated upstream by the tool's Zod
-                // inputSchema (which must be a ZodObject), so the runtime shape is
-                // always a record here. The `Tool` union widening loses the specific
-                // InferToolInput type, so we re-narrow defensively — a non-record
-                // value here signals a real upstream bug we want surfaced, not a
-                // case to paper over with `{}`.
-                const rawArgs = value.toolCall.arguments;
-                if (!isRecord(rawArgs)) {
-                    throw new Error(`toolCall.arguments for "${value.toolCall.name}" must be an object after Zod validation, got ${rawArgs === null ? 'null' : Array.isArray(rawArgs) ? 'array' : typeof rawArgs}`);
-                }
-                const modelOutputResult = await value.tool.function.toModelOutput({
-                    output: value.result.result,
-                    input: rawArgs,
-                });
-                outputForModel =
-                    modelOutputResult.type === 'content'
-                        ? modelOutputResult.value
-                        : JSON.stringify(value.result.result);
-            }
-            else {
-                outputForModel = JSON.stringify(value.result.result);
-            }
+            const outputForModel = await this.computeToolOutputForModel(value);
             const executedOutput = {
                 type: 'function_call_output',
                 id: `output_${value.toolCall.id}`,
@@ -622,7 +694,10 @@ export class ModelResult {
                 timestamp: Date.now(),
             });
         }
-        return toolResults;
+        return {
+            toolResults,
+            pausedCalls,
+        };
     }
     /**
      * Resolve async functions for the current turn.
@@ -747,6 +822,72 @@ export class ModelResult {
         const { stopWhen: _, state: _s, requireApproval: _r, approveToolCalls: _a, rejectToolCalls: _rj, context: _c, ...rest } = this.options.request;
         return rest;
     }
+    /**
+     * Apply `onResponseReceived` hooks to the freshly-supplied input items
+     * only, without re-hooking historical items that live in
+     * `currentState.messages`. Historical `function_call` items are passed to
+     * `applyOnResponseReceivedHooks` purely as callId → toolName
+     * name-resolution context and are dropped from the returned array.
+     *
+     * This keeps hooks idempotent across `callModel` invocations on the same
+     * conversation: the first call hooks the caller-supplied output, and
+     * subsequent calls (which rehydrate state) do not re-fire it.
+     *
+     * @param freshItems - Items newly supplied this turn (not yet hooked).
+     *   May contain any mix of InputsUnion array members — only
+     *   `function_call_output` items are affected by hooks; everything else
+     *   is returned unchanged.
+     * @param historicalItems - Existing messages from loaded state. Only
+     *   `function_call` entries are consulted for name resolution; no other
+     *   items are inspected and none are mutated.
+     * @param turnContext - Turn context for hook invocation
+     * @returns The fresh items in original order, with `output` rewritten on
+     *   any `function_call_output` whose matching HITL tool defines
+     *   `onResponseReceived`.
+     */
+    async applyHooksToFreshItems(freshItems, historicalItems, turnContext) {
+        if (freshItems.length === 0) {
+            return freshItems;
+        }
+        // Collect function_call items from history so the hook executor can
+        // resolve callId -> toolName without us having to mirror that logic.
+        const historyArray = Array.isArray(historicalItems)
+            ? historicalItems
+            : [
+                historicalItems,
+            ];
+        const functionCallItems = [];
+        for (const item of historyArray) {
+            if (isFunctionCallItem(item)) {
+                functionCallItems.push(item);
+            }
+        }
+        // Build a synthetic input that puts the historical function_calls
+        // BEFORE the fresh items. `applyOnResponseReceivedHooks` only rewrites
+        // function_call_output items, so the function_call items are seen only
+        // as name-resolution context.
+        const syntheticInput = [
+            ...functionCallItems,
+            ...freshItems,
+        ];
+        const hookedInput = await applyOnResponseReceivedHooks(syntheticInput, this.options.tools, turnContext, this.contextStore ?? undefined, this.options.sharedContextSchema);
+        if (hookedInput === syntheticInput) {
+            // No rewrites; return the originals unchanged.
+            return freshItems;
+        }
+        // Drop the leading function_call items we prepended; what remains is
+        // the fresh items in their original order (some with rewritten outputs).
+        const hookedArray = Array.isArray(hookedInput)
+            ? hookedInput
+            : [
+                hookedInput,
+            ];
+        if (hookedArray.length !== syntheticInput.length) {
+            // Shouldn't happen (hooks only rewrite in-place), but be conservative.
+            return freshItems;
+        }
+        return hookedArray.slice(functionCallItems.length);
+    }
     /**
      * Safely persist state with error handling.
      * Wraps state save operations to ensure failures are properly reported.
@@ -801,8 +942,14 @@ export class ModelResult {
                 const loadedState = await this.stateAccessor.load();
                 if (loadedState) {
                     this.currentState = loadedState;
-                    // Check if we're resuming from awaiting_approval with decisions
-                    if (loadedState.status === 'awaiting_approval' &&
+                    // Check if we're resuming from awaiting_approval or awaiting_hitl
+                    // with decisions. `awaiting_hitl` reuses `processApprovalDecisions`
+                    // because the resume mechanism is identical — the caller supplies
+                    // `approveToolCalls`/`rejectToolCalls` for paused call IDs, and we
+                    // re-invoke `executeTool` on approved calls (which re-runs
+                    // `onToolCalled` for HITL tools).
+                    const isResumableStatus = loadedState.status === 'awaiting_approval' || loadedState.status === 'awaiting_hitl';
+                    if (isResumableStatus &&
                         (this.approvedToolCalls.length > 0 || this.rejectedToolCalls.length > 0)) {
                         // Initialize context store before resuming so tools have access
                         if (this.options.context !== undefined) {
@@ -848,29 +995,55 @@ export class ModelResult {
             }
             // Resolve any async functions first
             let baseRequest = await this.resolveRequestForContext(initialContext);
-            // If we have state with existing messages, use those as input
-            if (this.currentState?.messages &&
+            // Split input into "historical" (already in state.messages) and "fresh"
+            // (newly supplied this turn). `onResponseReceived` must fire only for
+            // fresh items — re-hooking historical outputs on every callModel call
+            // would double-invoke non-idempotent hooks.
+            const hasLoadedHistory = !!this.currentState?.messages &&
                 Array.isArray(this.currentState.messages) &&
-                this.currentState.messages.length > 0) {
-                // Append new input to existing messages
+                this.currentState.messages.length > 0;
+            if (hasLoadedHistory && this.currentState) {
+                // `currentState.messages` is InputsUnion — keep it as that union so
+                // appendToMessages (which expects InputsUnion) accepts it directly.
+                const historicalMessages = this.currentState.messages;
+                // Normalize the caller-supplied input for this turn into an array of
+                // fresh items. Undefined stays undefined (no new items). The widening
+                // to BaseInputsUnion[] matches the signature of appendToMessages and
+                // mirrors the pre-existing pattern elsewhere in this file; the two
+                // union shapes (InputsUnion1 vs BaseInputsUnion1) describe the same
+                // SDK input items with different nominal types, and BaseInputsUnion
+                // already includes `any` in its element type, so the runtime shape
+                // is preserved either way.
                 const newInput = baseRequest.input;
-                if (newInput) {
-                    const inputArray = Array.isArray(newInput)
+                let freshItems;
+                if (newInput !== undefined) {
+                    freshItems = Array.isArray(newInput)
                         ? newInput
                         : [
                             newInput,
                         ];
-                    baseRequest = {
-                        ...baseRequest,
-                        input: appendToMessages(this.currentState.messages, inputArray),
-                    };
-                }
-                else {
-                    baseRequest = {
-                        ...baseRequest,
-                        input: this.currentState.messages,
-                    };
                 }
+                // Hook fresh items only (historical function_calls serve as
+                // name-resolution context). Leave historical items untouched.
+                const hookedFresh = freshItems
+                    ? await this.applyHooksToFreshItems(freshItems, historicalMessages, initialContext)
+                    : undefined;
+                baseRequest = {
+                    ...baseRequest,
+                    input: hookedFresh
+                        ? appendToMessages(historicalMessages, hookedFresh)
+                        : historicalMessages,
+                };
+            }
+            else if (baseRequest.input !== undefined) {
+                // No loaded history — everything in input is fresh. Hook the whole
+                // thing (non-array inputs pass through applyOnResponseReceivedHooks
+                // unchanged).
+                const hookedInput = await applyOnResponseReceivedHooks(baseRequest.input, this.options.tools, initialContext, this.contextStore ?? undefined, this.options.sharedContextSchema);
+                baseRequest = {
+                    ...baseRequest,
+                    input: hookedInput,
+                };
             }
             // Store resolved request with stream mode
             this.resolvedRequest = {
@@ -917,6 +1090,9 @@ export class ModelResult {
             numberOfTurns: this.allToolExecutionRounds.length + 1,
             // context is handled via contextStore, not on TurnContext
         };
+        // Track approved HITL calls that paused (onToolCalled returned null) —
+        // these stay in pendingToolCalls so the caller can resume them later.
+        const hitlPausedIds = new Set();
         // Process approvals - execute the approved tools
         for (const callId of this.approvedToolCalls) {
             const toolCall = pendingCalls.find((tc) => tc.id === callId);
@@ -924,12 +1100,18 @@ export class ModelResult {
                 continue;
             }
             const tool = this.options.tools?.find((t) => isClientTool(t) && t.function.name === toolCall.name);
-            if (!tool || !hasExecuteFunction(tool)) {
+            if (!tool || !isAutoResolvableTool(tool)) {
                 // Can't execute, create error result
                 unsentResults.push(createRejectedResult(callId, String(toolCall.name), 'Tool not found or not executable'));
                 continue;
             }
             const result = await executeTool(tool, toolCall, turnContext, undefined, this.contextStore ?? undefined, this.options.sharedContextSchema);
+            if (result === null) {
+                // HITL tool paused on approval — keep the call visible to the caller
+                // via pendingToolCalls (status becomes 'awaiting_hitl' below).
+                hitlPausedIds.add(callId);
+                continue;
+            }
             if (result.error) {
                 unsentResults.push(createRejectedResult(callId, String(toolCall.name), result.error.message));
             }
@@ -945,15 +1127,32 @@ export class ModelResult {
             }
             unsentResults.push(createRejectedResult(callId, String(toolCall.name), 'Rejected by user'));
         }
-        // Remove processed calls from pending
+        // Remove processed calls from pending. Approved HITL calls that paused are
+        // NOT considered processed — they stay on pendingToolCalls so getPendingToolCalls()
+        // still surfaces them to the caller on resume.
         const processedIds = new Set([
             ...this.approvedToolCalls,
             ...this.rejectedToolCalls,
-        ]);
+        ].filter((id) => !hitlPausedIds.has(id)));
         const remainingPending = pendingCalls.filter((tc) => !processedIds.has(tc.id));
+        // Determine status:
+        //   - Any still-unprocessed approval-required call keeps us in 'awaiting_approval'
+        //   - Otherwise, any HITL paused call moves us to 'awaiting_hitl'
+        //   - Otherwise, we continue with 'in_progress'
+        const remainingUnresolvedApprovals = remainingPending.filter((tc) => !hitlPausedIds.has(tc.id));
+        let nextStatus;
+        if (remainingUnresolvedApprovals.length > 0) {
+            nextStatus = 'awaiting_approval';
+        }
+        else if (hitlPausedIds.size > 0) {
+            nextStatus = 'awaiting_hitl';
+        }
+        else {
+            nextStatus = 'in_progress';
+        }
         // Update state - conditionally include optional properties only if they have values
         const stateUpdates = {
-            status: remainingPending.length > 0 ? 'awaiting_approval' : 'in_progress',
+            status: nextStatus,
         };
         if (remainingPending.length > 0) {
             stateUpdates.pendingToolCalls = remainingPending;
@@ -974,8 +1173,8 @@ export class ModelResult {
             this.clearOptionalStateProperties(propsToClear);
             await this.saveStateSafely();
         }
-        // If we still have pending approvals, stop here
-        if (remainingPending.length > 0) {
+        // If we are paused (for approval or for HITL), stop here
+        if (nextStatus !== 'in_progress') {
             return;
         }
         // Otherwise, continue with tool execution using unsent results
@@ -994,7 +1193,16 @@ export class ModelResult {
         }
         // Convert to API format
         const toolOutputs = unsentResultsToAPIFormat(unsentResults);
-        // Build new input with tool results
+        // Build turn context for hook resolution
+        // numberOfTurns represents the current turn number (1-indexed after initial)
+        const turnContext = {
+            numberOfTurns: this.allToolExecutionRounds.length + 1,
+        };
+        // Append SDK-generated tool outputs directly — `onResponseReceived` is
+        // reserved for caller-supplied outputs (the resume-with-function-call-
+        // output path, hooked during init). SDK-produced outputs from auto-
+        // executed tools already went through the tool's own execute/generator
+        // pipeline and must not be mutated by the resume hook.
         const currentMessages = this.currentState.messages;
         const newInput = appendToMessages(currentMessages, toolOutputs);
         // Clear unsent results from state
@@ -1006,12 +1214,11 @@ export class ModelResult {
         ]);
         await this.saveStateSafely();
         // Build request with the updated input
-        // numberOfTurns represents the current turn number (1-indexed after initial)
-        const turnContext = {
-            numberOfTurns: this.allToolExecutionRounds.length + 1,
-        };
         const baseRequest = await this.resolveRequestForContext(turnContext);
-        // Create request with the accumulated messages
+        // No hooking here: SDK-generated outputs are appended as-is and any
+        // caller-supplied items in `newInput` (carried over from init) were
+        // already hooked during `initStream` — re-hooking would double-fire
+        // non-idempotent hooks.
         const request = {
             ...baseRequest,
             input: newInput,
@@ -1047,8 +1254,12 @@ export class ModelResult {
         // biome-ignore lint: IIFE used for lazy initialization pattern
         this.toolExecutionPromise = (async () => {
             await this.initStream();
-            // If resuming from approval and still pending, don't continue
-            if (this.isResumingFromApproval && this.currentState?.status === 'awaiting_approval') {
+            // If resuming from approval or HITL pause and still pending, don't continue.
+            // `processApprovalDecisions` runs in initStream for resumes; if it left us
+            // paused (any remaining pending calls), the outer loop should not execute.
+            if (this.isResumingFromApproval &&
+                (this.currentState?.status === 'awaiting_approval' ||
+                    this.currentState?.status === 'awaiting_hitl')) {
                 return;
             }
             // Get initial response
@@ -1104,7 +1315,7 @@ export class ModelResult {
                 // Resolve async functions for this turn
                 await this.resolveAsyncFunctionsForTurn(turnContext);
                 // Execute tools
-                const toolResults = await this.executeToolRound(currentToolCalls, turnContext);
+                const { toolResults, pausedCalls } = await this.executeToolRound(currentToolCalls, turnContext);
                 // Server-tool output items are already-executed results in the
                 // response; collect them so toolResults presents a unified list.
                 const serverToolItems = [];
@@ -1137,6 +1348,13 @@ export class ModelResult {
                 });
                 // Save tool results to state
                 await this.saveToolResultsToState(toolResults);
+                // If any HITL tools paused this round, stop here without making a
+                // follow-up request — sending an incomplete set of outputs would be
+                // incorrect. Persist the paused calls so the caller can resume later.
+                if (pausedCalls.length > 0) {
+                    await this.persistHitlPause(currentResponse, pausedCalls);
+                    return;
+                }
                 // Apply nextTurnParams
                 await this.applyNextTurnParams(currentToolCalls);
                 currentResponse = await this.makeFollowupRequest(currentResponse, toolResults, turnNumber);
@@ -1659,13 +1877,16 @@ export class ModelResult {
     // Multi-Turn Conversation State Methods
     // =========================================================================
     /**
-     * Check if the conversation requires human approval to continue.
-     * Returns true if there are pending tool calls awaiting approval.
+     * Check if the conversation requires human input to continue.
+     * Returns true when the conversation is paused waiting for caller-supplied
+     * decisions — either approval/rejection (`awaiting_approval`) or HITL tool
+     * resume (`awaiting_hitl`). Also returns true whenever `pendingToolCalls`
+     * is populated regardless of status.
      */
     async requiresApproval() {
         await this.initStream();
-        // If we have pending tool calls in state, approval is required
-        if (this.currentState?.status === 'awaiting_approval') {
+        const status = this.currentState?.status;
+        if (status === 'awaiting_approval' || status === 'awaiting_hitl') {
             return true;
         }
         // Also check if pendingToolCalls is populated