@openrouter/agent 0.7.1 → 0.8.0

package/esm/lib/model-result.js

@@ -9,14 +9,30 @@ import { hasTypeProperty, isFunctionCallItem, isFunctionCallOutputItem, isOutput
 import { resolveContext, ToolContextStore } from './tool-context.js';
 import { ToolEventBroadcaster } from './tool-event-broadcaster.js';
 import { applyOnResponseReceivedHooks, executeTool } from './tool-executor.js';
-import { isAutoResolvableTool, isClientTool, isServerTool, isToolCallOutputEvent, } from './tool-types.js';
+import { isAutoResolvableTool, isClientTool, isMcpTool, isServerTool, isToolCallOutputEvent, } from './tool-types.js';
 import { normalizeInputToArray } from './turn-context.js';
+/**
+ * Default directive appended as a final user message on the forced final
+ * turn (`allowFinalResponse` defaulting to on, or explicitly `true`).
+ * Forbidding tools via `toolChoice: 'none'` alone is not enough: models
+ * that emit tool-call syntax as text (e.g. GLM) will attempt another call
+ * and leak it into `content` as unparsed `<tool_call>…` text unless they
+ * are told this is the final turn.
+ * Pass a non-empty string to `allowFinalResponse` to override the wording,
+ * or `''` to append no message at all (legacy behavior).
+ */
+export const DEFAULT_FINAL_RESPONSE_DIRECTIVE = 'You have reached the tool-use limit, and tools are no longer available. Do not attempt to call any more tools. Using the information you already have, write your final answer now.';
 /**
  * Typeguard for plain-object records (non-null, non-array).
  */
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+// Cap consecutive Stop-hook forceResume overrides so a misbehaving handler
+// cannot spin the loop forever. 3 is a conservative upper bound -- enough to
+// let a hook gather a couple of follow-up actions but small enough that a
+// buggy handler fails fast with a visible warning.
+const MAX_FORCE_RESUME_OVERRIDES = 3;
 /**
  * Human-readable label for a value that failed the `isRecord` check. Used
  * exclusively to make `toModelOutput` misuse errors specific.
@@ -44,6 +60,113 @@ function isEventStream(value) {
     const maybeStream = value;
     return typeof maybeStream.getReader === 'function';
 }
+/**
+ * Map the server's usage block onto the hook-facing ModelCallUsage shape.
+ * Returns undefined when the response carried no usage accounting.
+ */
+function extractModelCallUsage(usage) {
+    if (!usage) {
+        return undefined;
+    }
+    return {
+        inputTokens: usage.inputTokens,
+        outputTokens: usage.outputTokens,
+        totalTokens: usage.totalTokens,
+        cachedTokens: usage.inputTokensDetails?.cachedTokens ?? 0,
+        reasoningTokens: usage.outputTokensDetails?.reasoningTokens ?? 0,
+        ...(usage.cost !== null &&
+            usage.cost !== undefined && {
+            cost: usage.cost,
+        }),
+    };
+}
+/**
+ * Type guard for an input message with a user role and a string `content`.
+ * These are the messages we can safely surface to UserPromptSubmit hooks.
+ */
+function isUserStringMessage(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const obj = value;
+    return obj.role === 'user' && typeof obj.content === 'string';
+}
+/**
+ * Find the index of the last user-role, string-content message in an input
+ * array. Returns -1 when no such message exists.
+ */
+function findLatestUserStringIndex(arr) {
+    for (let i = arr.length - 1; i >= 0; i--) {
+        if (isUserStringMessage(arr[i])) {
+            return i;
+        }
+    }
+    return -1;
+}
+/**
+ * Extract a user-facing prompt string from an input (string or message array),
+ * and return an applier that writes a mutated prompt back into the same shape.
+ *
+ * For structured inputs we look at the LAST user message with a string
+ * content — this is the most common shape emitted by the SDK's own helpers
+ * (`normalizeInputToArray`) and matches what a handler would reasonably
+ * expect to mutate.
+ *
+ * Returns `{ prompt: undefined }` when no usable prompt can be extracted; the
+ * caller should skip the hook in that case.
+ */
+function extractPromptAndApplier(input) {
+    if (typeof input === 'string') {
+        return {
+            prompt: input,
+            applyMutated: (mutated) => mutated,
+        };
+    }
+    if (Array.isArray(input)) {
+        const targetIndex = findLatestUserStringIndex(input);
+        if (targetIndex === -1) {
+            return {
+                prompt: undefined,
+                applyMutated: (_mutated, original) => original ?? input,
+            };
+        }
+        const target = input[targetIndex];
+        if (!isUserStringMessage(target)) {
+            return {
+                prompt: undefined,
+                applyMutated: (_mutated, original) => original ?? input,
+            };
+        }
+        return {
+            prompt: target.content,
+            applyMutated: (mutated, original) => {
+                // Re-derive the target index from the effective base array so an
+                // arbitrary `original` shape lands the mutation in the correct slot
+                // rather than the closed-over index from the initial extraction.
+                const base = Array.isArray(original) ? original : input;
+                const idx = findLatestUserStringIndex(base);
+                if (idx === -1) {
+                    return base;
+                }
+                const out = [
+                    ...base,
+                ];
+                const existing = out[idx];
+                if (isUserStringMessage(existing)) {
+                    out[idx] = {
+                        ...existing,
+                        content: mutated,
+                    };
+                }
+                return out;
+            },
+        };
+    }
+    return {
+        prompt: undefined,
+        applyMutated: (_mutated, original) => original ?? input,
+    };
+}
 /**
  * A wrapper around a streaming response that provides multiple consumption patterns.
  *
@@ -75,6 +198,7 @@ export class ModelResult {
         this.allToolExecutionRounds = [];
         // Track resolved request after async function resolution
         this.resolvedRequest = null;
+        this.resumingFromClientTools = false;
         // State management for multi-turn conversations
         this.stateAccessor = null;
         this.currentState = null;
@@ -88,7 +212,33 @@ export class ModelResult {
         this.initialPipePromise = null;
         // Context store for typed tool context (persists across turns)
         this.contextStore = null;
+        // Tracks whether SessionStart has already been emitted, so SessionEnd can be
+        // guarded to fire only when a matching SessionStart actually succeeded.
+        // Without this, an exception in initStream before SessionStart would lead to
+        // a dangling SessionEnd (breaking audit-log / resource-pair contracts).
+        this.sessionStartEmitted = false;
+        // Pairs with sessionStartEmitted: guards emitSessionEndOnce so the
+        // tool-execution path and the no-tools stream paths can both attempt the
+        // emit without double-firing.
+        this.sessionEndEmitted = false;
+        // Tool call ids the PermissionRequest hook denied without pausing. The
+        // normal tool round consults this to synthesize rejected outputs instead of
+        // executing the calls.
+        this.hookDeniedCalls = new Map();
+        // Running aggregate across every PostModelCall emit; surfaced as
+        // SessionEnd.totalUsage.
+        this.sessionUsage = {
+            modelCalls: 0,
+            inputTokens: 0,
+            outputTokens: 0,
+            totalTokens: 0,
+            cachedTokens: 0,
+            reasoningTokens: 0,
+            cost: 0,
+            hasCost: false,
+        };
         this.options = options;
+        this.hooksManager = options.hooks;
         // Runtime validation: approval decisions require state
         const hasApprovalDecisions = (options.approveToolCalls && options.approveToolCalls.length > 0) ||
             (options.rejectToolCalls && options.rejectToolCalls.length > 0);
@@ -183,14 +333,24 @@ export class ModelResult {
         }
         return completedResponse;
     }
+    /**
+     * Resolve a tool's result `source` from its call name by looking it up in the
+     * configured tools. Used where the concrete tool reference isn't in scope
+     * (e.g. a rejected execution). Defaults to `'client'` when not found.
+     */
+    toolSourceByName(name) {
+        const matched = this.options.tools?.find((t) => isClientTool(t) && t.function.name === name);
+        return matched !== undefined && isMcpTool(matched) ? 'mcp' : 'client';
+    }
     /**
      * Push a tool result event to both the legacy tool event broadcaster
      * and the unified turn broadcaster.
      */
-    broadcastToolResult(toolCallId, result, preliminaryResults) {
+    broadcastToolResult(toolCallId, source, result, preliminaryResults) {
         this.toolEventBroadcaster?.push({
             type: 'tool_result',
             toolCallId,
+            source,
             result,
             ...(preliminaryResults?.length && {
                 preliminaryResults,
@@ -199,6 +359,7 @@ export class ModelResult {
         this.turnBroadcaster?.push({
             type: 'tool.result',
             toolCallId,
+            source,
             result,
             timestamp: Date.now(),
             ...(preliminaryResults?.length && {
@@ -253,6 +414,24 @@ export class ModelResult {
     isNonStreamingResponse(value) {
         return (value !== null && typeof value === 'object' && 'output' in value && !isEventStream(value));
     }
+    /**
+     * Materialize a betaResponsesSend result value into a completed response:
+     * streaming values are consumed to completion (through the turn
+     * broadcaster when one is attached), non-streaming values pass through.
+     */
+    async materializeResponse(value, turnNumber) {
+        if (isEventStream(value)) {
+            const stream = new ReusableReadableStream(value);
+            if (this.turnBroadcaster) {
+                return this.pipeAndConsumeStream(stream, turnNumber);
+            }
+            return consumeStreamForCompletion(stream);
+        }
+        if (this.isNonStreamingResponse(value)) {
+            return value;
+        }
+        throw new Error('Unexpected response type from API');
+    }
     // =========================================================================
     // Extracted Helper Methods for executeToolsIfNeeded
     // =========================================================================
@@ -268,7 +447,9 @@ export class ModelResult {
             return this.finalResponse;
         }
         if (this.reusableStream) {
-            return consumeStreamForCompletion(this.reusableStream);
+            const response = await consumeStreamForCompletion(this.reusableStream);
+            await this.emitPendingModelCallOnce(response);
+            return response;
         }
         throw new Error('Neither stream nor response initialized');
     }
@@ -295,10 +476,21 @@ export class ModelResult {
             messages = appendToMessages(messages, this.pendingFreshItems);
             this.pendingFreshItems = undefined;
         }
-        await this.saveStateSafely({
+        const stateUpdates = {
             messages: appendToMessages(messages, outputItems),
             previousResponseId: response.id,
-        });
+        };
+        if (this.resumingFromClientTools) {
+            this.currentState = {
+                ...this.currentState,
+            };
+            this.clearOptionalStateProperties([
+                'pendingToolCalls',
+            ]);
+            this.resumingFromClientTools = false;
+            stateUpdates.status = 'in_progress';
+        }
+        await this.saveStateSafely(stateUpdates);
     }
     /**
      * Mark state as complete.
@@ -352,6 +544,57 @@ export class ModelResult {
         this.finalResponse = currentResponse;
         return true;
     }
+    /**
+     * Inject a user-role message into the conversation state and into the
+     * accumulated request input, so the next turn picks it up. Used by the
+     * Stop hook's `appendPrompt` to nudge the model without forcing a resume.
+     *
+     * This advances observable state (messages/input change) so the next
+     * iteration of the execution loop is not a no-op.
+     */
+    async injectAppendPromptMessage(prompt) {
+        const injectedMessage = {
+            role: 'user',
+            content: prompt,
+        };
+        if (this.currentState) {
+            // Mutate the in-memory state directly so loop progress is observable
+            // even when no StateAccessor is configured (forceResume needs state to
+            // change to avoid looping). Persist when an accessor is available.
+            const nextMessages = appendToMessages(this.currentState.messages, [
+                injectedMessage,
+            ]);
+            this.currentState = updateState(this.currentState, {
+                messages: nextMessages,
+            });
+            if (this.stateAccessor) {
+                await this.saveStateSafely();
+            }
+        }
+        if (this.resolvedRequest) {
+            const currentInput = this.resolvedRequest.input;
+            const nextInput = Array.isArray(currentInput)
+                ? [
+                    ...currentInput,
+                    injectedMessage,
+                ]
+                : currentInput
+                    ? [
+                        {
+                            role: 'user',
+                            content: currentInput,
+                        },
+                        injectedMessage,
+                    ]
+                    : [
+                        injectedMessage,
+                    ];
+            this.resolvedRequest = {
+                ...this.resolvedRequest,
+                input: nextInput,
+            };
+        }
+    }
     /**
      * Check if stop conditions are met.
      * Returns true if execution should stop.
@@ -383,11 +626,18 @@ export class ModelResult {
                 // `toolResults` is client-tool-centric; server-tool output items are
                 // surfaced on `serverToolResults` so stop conditions can react to
                 // either class of result.
-                toolResults: round.toolResults.filter(isFunctionCallOutput).map((tr) => ({
-                    toolCallId: tr.callId,
-                    toolName: round.toolCalls.find((tc) => tc.id === tr.callId)?.name ?? '',
-                    result: typeof tr.output === 'string' ? JSON.parse(tr.output) : tr.output,
-                })),
+                toolResults: round.toolResults.filter(isFunctionCallOutput).map((tr) => {
+                    const toolName = round.toolCalls.find((tc) => tc.id === tr.callId)?.name ?? '';
+                    const matchedTool = this.options.tools?.find((t) => isClientTool(t) && t.function.name === toolName);
+                    return {
+                        toolCallId: tr.callId,
+                        toolName,
+                        source: matchedTool !== undefined && isMcpTool(matchedTool)
+                            ? 'mcp'
+                            : 'client',
+                        result: typeof tr.output === 'string' ? JSON.parse(tr.output) : tr.output,
+                    };
+                }),
                 serverToolResults: round.toolResults.filter(isServerToolResult),
                 response: round.response,
                 usage: round.response.usage,
@@ -423,6 +673,422 @@ export class ModelResult {
         const tool = this.options.tools?.find((t) => isClientTool(t) && t.function.name === item.name);
         return !!tool && !isAutoResolvableTool(tool);
     }
+    /**
+     * Shared helper: execute a single tool and emit the full Pre/Post lifecycle
+     * hooks around it.
+     *
+     * Every code path that ultimately calls `executeTool()` for a user-visible
+     * tool call funnels through here so that PreToolUse/PostToolUse/
+     * PostToolUseFailure fire consistently — regardless of whether the tool was
+     * auto-executed, required approval, or was approved later.
+     *
+     * Return shape:
+     * - `parse_error`: `toolCall.arguments` was a raw JSON string the model
+     *   failed to produce valid JSON for. The caller should use the prebuilt
+     *   FunctionCallOutputItem and not execute the tool. No hooks fire.
+     * - `hook_blocked`: PreToolUse returned `block` (boolean true or a reason
+     *   string). The caller should synthesize a denied result without invoking
+     *   the tool. The FunctionCallOutputItem is prebuilt for convenience.
+     * - `execution`: The tool ran. `result` is the ToolExecutionResult.
+     *   `effectiveToolCall` reflects any `mutatedInput` piped by PreToolUse.
+     */
+    async runToolWithHooks(tool, toolCall, turnContext, onPreliminaryResult) {
+        // 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
+        // validation (silent no-op in non-strict mode) or deliver a malformed
+        // `toolInput` to handlers. Fail closed here so every execution path
+        // (auto-approve, manual approval, approved-on-resume) gets a consistent
+        // synthetic error without running the tool or firing hooks.
+        const rawArgs = toolCall.arguments;
+        if (typeof rawArgs === 'string') {
+            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.';
+            return {
+                type: 'parse_error',
+                toolCall,
+                errorMessage,
+                output: {
+                    type: 'function_call_output',
+                    id: `output_${toolCall.id}`,
+                    callId: toolCall.id,
+                    output: JSON.stringify({
+                        error: errorMessage,
+                    }),
+                },
+            };
+        }
+        let effectiveToolCall = toolCall;
+        // Emit PreToolUse hook -- can block or mutate input.
+        if (this.hooksManager) {
+            // 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
+            // legitimately distinguish "no args" from "empty args" are unaffected.
+            const originalToolInput = (toolCall.arguments ?? {});
+            const preResult = await this.hooksManager.emit('PreToolUse', {
+                toolName: toolCall.name,
+                toolInput: originalToolInput,
+            }, this.hookEmitContext(toolCall.name));
+            if (preResult.blocked) {
+                // Every entry in `results` passed the PreToolUseResult schema (see
+                // EmitResult.results invariant), so no structural re-narrowing needed.
+                const block = preResult.results.find((r) => r.block)?.block;
+                const reason = typeof block === 'string' ? block : 'Blocked by PreToolUse hook';
+                return {
+                    type: 'hook_blocked',
+                    toolCall,
+                    reason,
+                    output: {
+                        type: 'function_call_output',
+                        id: `output_${toolCall.id}`,
+                        callId: toolCall.id,
+                        output: JSON.stringify({
+                            error: reason,
+                        }),
+                    },
+                };
+            }
+            // Apply mutated input only when a handler actually piped a replacement
+            // (`emit.mutated`). Payload validation clones the object, so a
+            // reference comparison against the original would false-positive and
+            // coerce legitimately-null arguments to {}.
+            if (preResult.mutated) {
+                effectiveToolCall = {
+                    ...toolCall,
+                    arguments: preResult.finalPayload.toolInput,
+                };
+            }
+        }
+        // performance.now() gives monotonic, sub-ms precision and is immune to
+        // system clock jumps, unlike Date.now().
+        const startTime = performance.now();
+        const result = await executeTool(tool, effectiveToolCall, turnContext, onPreliminaryResult, this.contextStore ?? undefined, this.options.sharedContextSchema);
+        const durationMs = performance.now() - startTime;
+        // HITL tools may pause (executeTool returns null). No output was produced
+        // yet, so neither PostToolUse nor PostToolUseFailure fires; they will fire
+        // if/when the tool is resumed and actually executes.
+        // Emit PostToolUse or PostToolUseFailure.
+        if (this.hooksManager && result !== null) {
+            if (result.error) {
+                await this.hooksManager.emit('PostToolUseFailure', {
+                    toolName: effectiveToolCall.name,
+                    toolInput: (effectiveToolCall.arguments ?? {}),
+                    error: result.error,
+                }, this.hookEmitContext(effectiveToolCall.name));
+            }
+            else {
+                await this.hooksManager.emit('PostToolUse', {
+                    toolName: effectiveToolCall.name,
+                    toolInput: (effectiveToolCall.arguments ?? {}),
+                    toolOutput: result.result,
+                    durationMs,
+                }, this.hookEmitContext(effectiveToolCall.name));
+            }
+        }
+        return {
+            type: 'execution',
+            effectiveToolCall,
+            result,
+        };
+    }
+    /**
+     * Build the per-emit context for lifecycle hook emits. Threads this run's
+     * session identity into `context.sessionId` on every emit, so a
+     * `HooksManager` instance shared across concurrent runs never leaks one
+     * run's id into another's handlers (the manager-level `setSessionId`
+     * default is a single mutable field and would be clobbered by the last
+     * run to start).
+     */
+    hookEmitContext(toolName) {
+        return {
+            ...(toolName !== undefined && {
+                toolName,
+            }),
+            sessionId: this.currentState?.id ?? '',
+        };
+    }
+    /**
+     * Emit SessionEnd exactly once, and only when a matching SessionStart
+     * actually succeeded. Safe to call from multiple teardown paths.
+     */
+    async emitSessionEndOnce(reason) {
+        if (!this.hooksManager || !this.sessionStartEmitted || this.sessionEndEmitted) {
+            return;
+        }
+        this.sessionEndEmitted = true;
+        await this.hooksManager.emit('SessionEnd', {
+            reason,
+            ...(this.sessionUsage.modelCalls > 0 && {
+                totalUsage: {
+                    modelCalls: this.sessionUsage.modelCalls,
+                    inputTokens: this.sessionUsage.inputTokens,
+                    outputTokens: this.sessionUsage.outputTokens,
+                    totalTokens: this.sessionUsage.totalTokens,
+                    cachedTokens: this.sessionUsage.cachedTokens,
+                    reasoningTokens: this.sessionUsage.reasoningTokens,
+                    ...(this.sessionUsage.hasCost && {
+                        cost: this.sessionUsage.cost,
+                    }),
+                },
+            }),
+        }, this.hookEmitContext());
+    }
+    /**
+     * Emit PostModelCall for a completed model response and fold its usage
+     * into the session aggregate. One emit per materialized response.
+     */
+    async emitPostModelCall(response, startedAt, turnType, turnNumber) {
+        if (!this.hooksManager) {
+            return;
+        }
+        const usage = extractModelCallUsage(response.usage);
+        this.sessionUsage.modelCalls++;
+        if (usage) {
+            this.sessionUsage.inputTokens += usage.inputTokens;
+            this.sessionUsage.outputTokens += usage.outputTokens;
+            this.sessionUsage.totalTokens += usage.totalTokens;
+            this.sessionUsage.cachedTokens += usage.cachedTokens;
+            this.sessionUsage.reasoningTokens += usage.reasoningTokens;
+            if (usage.cost !== undefined) {
+                this.sessionUsage.cost += usage.cost;
+                this.sessionUsage.hasCost = true;
+            }
+        }
+        await this.hooksManager.emit('PostModelCall', {
+            sessionId: this.currentState?.id ?? '',
+            responseId: response.id,
+            model: response.model ?? '',
+            durationMs: performance.now() - startedAt,
+            turnType,
+            turnNumber,
+            ...(usage && {
+                usage,
+            }),
+        }, this.hookEmitContext());
+    }
+    /**
+     * Emit the parked initial/resume PostModelCall once its response has been
+     * materialized. No-ops when nothing is parked (e.g. the non-streaming
+     * branch already emitted). Safe to call from multiple materialization
+     * sites; the first wins.
+     */
+    async emitPendingModelCallOnce(response) {
+        const pending = this.pendingModelCall;
+        if (!pending) {
+            return;
+        }
+        this.pendingModelCall = undefined;
+        await this.emitPostModelCall(response, pending.startedAt, pending.turnType, pending.turnNumber);
+    }
+    /**
+     * Emit the Stop hook when a stopWhen condition halts the loop, and decide
+     * whether the loop should resume.
+     *
+     * - `appendPrompt` values from all handlers are concatenated (newline
+     *   separated) and injected as a user message. Honored independently of
+     *   forceResume so a handler can nudge the next turn without resuming.
+     * - `forceResume` is honored if ANY handler returns it, capped at
+     *   MAX_FORCE_RESUME_OVERRIDES consecutive overrides without tool
+     *   progress (the caller resets its counter when a tool round or a fresh
+     *   response lands).
+     *
+     * Returns 'resume' when the loop should continue, 'stop' otherwise.
+     */
+    async runStopHook(forceResumeCount) {
+        if (!this.hooksManager) {
+            return 'stop';
+        }
+        // shouldStopExecution() is driven by stopWhen conditions (default
+        // stepCountIs), so 'max_turns' is the semantically accurate reason.
+        const stopResult = await this.hooksManager.emit('Stop', {
+            reason: 'max_turns',
+        }, this.hookEmitContext());
+        // Every entry in `results` passed the StopResult schema (see
+        // EmitResult.results invariant), so the fields can be read directly.
+        const shouldForceResume = stopResult.results.some((r) => r.forceResume === true);
+        const appendPrompt = stopResult.results
+            .map((r) => r.appendPrompt)
+            .filter((p) => typeof p === 'string' && p.length > 0)
+            .join('\n');
+        if (appendPrompt) {
+            await this.injectAppendPromptMessage(appendPrompt);
+        }
+        if (!shouldForceResume) {
+            return 'stop';
+        }
+        if (forceResumeCount >= MAX_FORCE_RESUME_OVERRIDES) {
+            // Don't let the hook loop the engine forever. Log and stop.
+            console.warn(`[Stop hook] forceResume honored ${MAX_FORCE_RESUME_OVERRIDES} times without new progress; stopping to prevent an infinite loop.`);
+            return 'stop';
+        }
+        return 'resume';
+    }
+    /**
+     * Session teardown for the no-tools stream paths, which bypass
+     * executeToolsIfNeeded (the normal SessionEnd site). Emits SessionEnd once
+     * and drains pending hook work. Never throws: teardown must not mask the
+     * stream's own outcome.
+     */
+    async finishHooksSessionForStream(reason = 'complete') {
+        if (!this.hooksManager) {
+            return;
+        }
+        try {
+            // Materialize the parked initial-call telemetry when the stream fully
+            // completed (the retained buffer replays without touching the source).
+            // A failed/errored stream skips it: no materialized response exists.
+            // (`response.incomplete` responses DO emit — they are materialized, have
+            // a generation id, and consumed tokens.)
+            // Isolated try: a telemetry failure (e.g. a buffer without a completion
+            // event, or a throwing strict-mode handler) must not skip SessionEnd or
+            // the drain below — those are contractual on every exit path.
+            try {
+                if (this.pendingModelCall) {
+                    if (this.finalResponse) {
+                        await this.emitPendingModelCallOnce(this.finalResponse);
+                    }
+                    else if (this.reusableStream?.isComplete) {
+                        await this.emitPendingModelCallOnce(await consumeStreamForCompletion(this.reusableStream));
+                    }
+                }
+            }
+            catch (telemetryError) {
+                console.warn('[PostModelCall] error during stream teardown:', telemetryError);
+            }
+            await this.emitSessionEndOnce(reason);
+            await this.hooksManager.drain();
+        }
+        catch (teardownError) {
+            console.warn('[SessionEnd] error during stream teardown:', teardownError);
+        }
+    }
+    /**
+     * initStream wrapper for the streaming getters. initStream can throw
+     * after SessionStart was emitted (e.g. the initial API call fails), and
+     * the "Stream not initialized" guard can throw right after it — on both
+     * paths the hook session must still be torn down (SessionEnd + drain),
+     * otherwise Start/End handlers that treat the pair as a contract see a
+     * dangling Start. Teardown is emit-once, so the tools path (which runs
+     * its own teardown in executeToolsIfNeeded) is unaffected.
+     */
+    async initStreamGuarded(options) {
+        // The not-initialized invariant applies to streaming getters only:
+        // state-inspection methods (getPendingToolCalls/getState/...) are valid
+        // on paused resumes (awaiting_hitl/awaiting_approval) where initStream
+        // returns early with neither a stream nor a finalResponse.
+        const requireStream = options?.requireStream ?? true;
+        try {
+            await this.initStream();
+            if (requireStream && !this.reusableStream && !this.finalResponse) {
+                throw new Error('Stream not initialized');
+            }
+        }
+        catch (error) {
+            await this.finishHooksSessionForStream('error');
+            throw error;
+        }
+    }
+    /**
+     * Emit the PermissionRequest hook before the SDK blocks for user approval.
+     *
+     * Returns the hook's collective decision:
+     * - `allow`: the tool should proceed as if auto-approved (skip approval gate)
+     * - `deny`: the tool should NOT run; caller should produce a denied result
+     * - `ask_user`: fall through to the existing approval flow (the default)
+     *
+     * Last-wins when multiple handlers return conflicting decisions.
+     */
+    async emitPermissionRequest(toolCall) {
+        if (!this.hooksManager) {
+            return {
+                decision: 'ask_user',
+            };
+        }
+        // Raw-string arguments mean the model produced invalid JSON. Fail closed
+        // (fall through to the human approval flow) rather than emitting a
+        // malformed payload the schema would reject anyway -- mirrors the guard
+        // in runToolWithHooks.
+        if (typeof toolCall.arguments === 'string') {
+            return {
+                decision: 'ask_user',
+            };
+        }
+        // Derive risk level from the approval gate's shape: a callback (tool- or
+        // call-level requireApproval function) => 'high' (caller actively
+        // decides per call), blanket true => 'medium', otherwise 'low'.
+        const tool = this.options.tools?.find((t) => isClientTool(t) && t.function.name === toolCall.name);
+        const requireApproval = tool && isClientTool(tool) ? tool.function.requireApproval : undefined;
+        const riskLevel = typeof requireApproval === 'function' || this.requireApprovalFn
+            ? 'high'
+            : requireApproval === true
+                ? 'medium'
+                : 'low';
+        const emit = await this.hooksManager.emit('PermissionRequest', {
+            toolName: toolCall.name,
+            toolInput: (toolCall.arguments ?? {}),
+            riskLevel,
+        }, this.hookEmitContext(toolCall.name));
+        // Last-wins: if multiple handlers disagree, the most recently registered
+        // handler dictates the outcome. This is documented and intentional —
+        // callers that want stricter semantics should register a single final
+        // handler (or use `throwOnHandlerError` to surface conflicts in tests).
+        // Every entry in `results` passed the PermissionRequestResult schema
+        // (`decision` is a required enum), so it can be read directly.
+        const last = emit.results.at(-1);
+        if (!last) {
+            return {
+                decision: 'ask_user',
+            };
+        }
+        return {
+            decision: last.decision,
+            ...(last.reason !== undefined && {
+                reason: last.reason,
+            }),
+        };
+    }
+    /**
+     * Run the UserPromptSubmit hook, supporting both string and structured
+     * inputs. If a handler returns a mutated prompt, the returned object
+     * applies the mutation back to the original input shape (string in =
+     * string out, message array in = message array out with the latest user
+     * text replaced).
+     *
+     * Throws if any handler rejects the prompt.
+     *
+     * Returns `undefined` when the hook does nothing, or when no usable prompt
+     * could be extracted from a structured input (handler is skipped and a
+     * one-time `console.warn` in dev builds explains why).
+     */
+    async maybeRunUserPromptSubmit(currentInput) {
+        if (!this.hooksManager || currentInput === undefined) {
+            return undefined;
+        }
+        const { prompt, applyMutated } = extractPromptAndApplier(currentInput);
+        if (prompt === undefined) {
+            if (process.env['NODE_ENV'] !== 'production') {
+                console.warn('[UserPromptSubmit] Could not extract a user prompt from structured input; skipping hook.');
+            }
+            return undefined;
+        }
+        const emit = await this.hooksManager.emit('UserPromptSubmit', {
+            prompt,
+        }, this.hookEmitContext());
+        if (emit.blocked) {
+            // Every entry in `results` passed the UserPromptSubmitResult schema.
+            const reject = emit.results.find((r) => r.reject)?.reject;
+            throw new Error(typeof reject === 'string' ? reject : 'Prompt rejected by hook');
+        }
+        if (!emit.mutated) {
+            return undefined;
+        }
+        const mutated = emit.finalPayload.prompt;
+        return {
+            applyTo: (original) => applyMutated(mutated, original),
+        };
+    }
     /**
      * Execute tools that can auto-execute (don't require approval) in parallel.
      *
@@ -436,7 +1102,20 @@ export class ModelResult {
             if (!tool || !isAutoResolvableTool(tool)) {
                 return null;
             }
-            const result = await executeTool(tool, tc, turnContext, undefined, this.contextStore ?? undefined, this.options.sharedContextSchema);
+            // Route through runToolWithHooks so PreToolUse/PostToolUse fire even on
+            // the auto-approve path. `runToolWithHooks` also fails closed on raw
+            // 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', {
+                    error: hookOutcome.errorMessage,
+                });
+                return createRejectedResult(tc.id, String(tc.name), hookOutcome.errorMessage);
+            }
+            if (hookOutcome.type === 'hook_blocked') {
+                return createRejectedResult(tc.id, String(tc.name), hookOutcome.reason);
+            }
+            const result = hookOutcome.result;
             if (result === null) {
                 // HITL tool paused — no unsent result for this call in this round
                 return null;
@@ -484,24 +1163,71 @@ export class ModelResult {
             // context is handled via contextStore, not on TurnContext
         };
         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;
         }
-        // Validate: approval requires state accessor
+        // 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.
+        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') {
+                    denied.push({
+                        tc,
+                        reason: reason ?? 'Denied by PermissionRequest hook',
+                    });
+                }
+                else {
+                    stillPending.push(tc);
+                }
+            }
+        }
+        else {
+            stillPending.push(...needsApproval);
+        }
+        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);
+            }
+            return false;
+        }
+        // Validate: pausing for approval requires a state accessor.
         if (!this.stateAccessor) {
-            const toolNames = needsApproval.map((tc) => tc.name).join(', ');
+            const toolNames = stillPending.map((tc) => tc.name).join(', ');
             throw new Error(`Tool(s) require approval but no state accessor is configured: ${toolNames}. ` +
                 'Provide a StateAccessor via the "state" parameter to enable approval workflows.');
         }
-        // Execute auto-approve tools
+        // 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);
-        // Save state with pending approvals
+        // Combine pre-denied results (from hook "deny") with executed results.
+        const combinedResults = [
+            ...unsentResults,
+            ...denied.map((d) => createRejectedResult(d.tc.id, String(d.tc.name), d.reason)),
+        ];
+        // Save state with pending approvals (only reached when stillPending > 0).
         const stateUpdates = {
-            pendingToolCalls: needsApproval,
+            pendingToolCalls: stillPending,
             status: 'awaiting_approval',
         };
-        if (unsentResults.length > 0) {
-            stateUpdates.unsentToolResults = unsentResults;
+        if (combinedResults.length > 0) {
+            stateUpdates.unsentToolResults = combinedResults;
         }
         await this.saveStateSafely(stateUpdates);
         this.finalResponse = currentResponse;
@@ -533,6 +1259,41 @@ export class ModelResult {
         };
         await this.saveStateSafely(stateUpdates);
     }
+    /**
+     * Persist state when the loop stops due to unresolved manual (client-executed)
+     * tool calls — tools with neither `execute` nor `onToolCalled`.
+     *
+     * Mirrors `persistHitlPause` so callers can read the unresolved calls via
+     * `getPendingToolCalls()` / `getState()` after the loop ends. Uses the
+     * distinct status `awaiting_client_tools` so consumers can discriminate
+     * manual pauses from HITL pauses (`awaiting_hitl`).
+     *
+     * Resume behavior: `awaiting_client_tools` is intentionally NOT treated as a
+     * resumable status for `processApprovalDecisions` — manual tools are not
+     * approved/rejected via call IDs; the caller executes them externally and
+     * typically supplies `function_call_output` items as new input on the next
+     * `callModel`. The paused status and calls remain durable until that request
+     * produces a response; they are then cleared atomically with the response.
+     *
+     * Without a `StateAccessor` nothing is persisted (mirroring
+     * `persistHitlPause`): `getPendingToolCalls()` returns `[]` and the caller
+     * must read the unresolved `function_call` items off `getResponse().output`.
+     * Manual tools require a StateAccessor to be recoverable across processes.
+     *
+     * @param currentResponse - The response that produced the unresolved calls
+     * @param unresolvedCalls - Manual (or otherwise non-auto-resolvable) tool calls
+     */
+    async persistClientToolsPause(currentResponse, unresolvedCalls) {
+        this.finalResponse = currentResponse;
+        if (!this.stateAccessor || unresolvedCalls.length === 0) {
+            return;
+        }
+        const stateUpdates = {
+            pendingToolCalls: unresolvedCalls,
+            status: 'awaiting_client_tools',
+        };
+        await this.saveStateSafely(stateUpdates);
+    }
     /**
      * Compute the `output` payload sent to the model for a successfully
      * settled tool execution. Routes through `toModelOutput` when the tool
@@ -578,60 +1339,76 @@ export class ModelResult {
      *   `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 || !isAutoResolvableTool(tool)) {
-                return null;
-            }
-            // Check if arguments failed to parse (remained as string instead of object)
-            const args = toolCall.arguments;
-            if (typeof args === 'string') {
-                const rawArgs = args;
-                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.';
-                this.broadcastToolResult(toolCall.id, {
-                    error: errorMessage,
-                });
-                return {
-                    type: 'parse_error',
-                    toolCall,
-                    output: {
-                        type: 'function_call_output',
-                        id: `output_${toolCall.id}`,
-                        callId: toolCall.id,
-                        output: JSON.stringify({
-                            error: errorMessage,
-                        }),
-                    },
-                };
-            }
-            const preliminaryResultsForCall = [];
-            const hasBroadcaster = this.toolEventBroadcaster || this.turnBroadcaster;
-            const onPreliminaryResult = hasBroadcaster
-                ? (callId, resultValue) => {
-                    const typedResult = resultValue;
-                    preliminaryResultsForCall.push(typedResult);
-                    this.broadcastPreliminaryResult(callId, typedResult);
-                }
-                : 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,
-                };
-            }
+    /**
+     * Execute one tool call for a round: resolve the tool, honor any pending
+     * PermissionRequest denial, wire preliminary-result broadcasting, and run
+     * the tool through the full Pre/Post lifecycle hooks. Returns a tagged
+     * outcome consumed by `executeToolRound`'s aggregation loop.
+     */
+    async executeSingleToolCall(toolCall, turnContext) {
+        const tool = this.options.tools?.find((t) => isClientTool(t) && t.function.name === toolCall.name);
+        if (!tool || !isAutoResolvableTool(tool)) {
+            return null;
+        }
+        // PermissionRequest hook denied this call without pausing: synthesize a
+        // rejection instead of executing. Consume the entry so a later round
+        // with a reused id is not affected.
+        const denialReason = this.hookDeniedCalls.get(toolCall.id);
+        if (denialReason !== undefined) {
+            this.hookDeniedCalls.delete(toolCall.id);
             return {
-                type: 'execution',
+                type: 'hook_blocked',
+                output: {
+                    type: 'function_call_output',
+                    id: `output_${toolCall.id}`,
+                    callId: toolCall.id,
+                    output: JSON.stringify({
+                        error: denialReason,
+                    }),
+                },
+            };
+        }
+        const preliminaryResultsForCall = [];
+        const hasBroadcaster = this.toolEventBroadcaster || this.turnBroadcaster;
+        const onPreliminaryResult = hasBroadcaster
+            ? (callId, resultValue) => {
+                const typedResult = resultValue;
+                preliminaryResultsForCall.push(typedResult);
+                this.broadcastPreliminaryResult(callId, typedResult);
+            }
+            : undefined;
+        // Run the tool through the full Pre/Post lifecycle hooks. The helper
+        // fails closed on a JSON-parse failure in toolCall.arguments so hooks
+        // never see a malformed payload; the caller handles that case via the
+        // shared `parse_error` / `hook_blocked` branch.
+        const executed = await this.runToolWithHooks(tool, toolCall, turnContext, onPreliminaryResult);
+        if (executed.type === 'parse_error') {
+            this.broadcastToolResult(toolCall.id, isMcpTool(tool) ? 'mcp' : 'client', {
+                error: executed.errorMessage,
+            });
+            return executed;
+        }
+        if (executed.type === 'hook_blocked') {
+            return executed;
+        }
+        const result = executed.result;
+        if (result === null) {
+            // HITL tool paused — surface as manual (no output this round)
+            return {
+                type: 'paused',
                 toolCall,
-                tool,
-                result,
-                preliminaryResultsForCall,
             };
-        });
+        }
+        return {
+            type: 'execution',
+            toolCall: executed.effectiveToolCall,
+            tool,
+            result,
+            preliminaryResultsForCall,
+        };
+    }
+    async executeToolRound(toolCalls, turnContext) {
+        const toolCallPromises = toolCalls.map((toolCall) => this.executeSingleToolCall(toolCall, turnContext));
         const settledResults = await Promise.allSettled(toolCallPromises);
         const toolResults = [];
         const pausedCalls = [];
@@ -643,7 +1420,8 @@ export class ModelResult {
             }
             if (settled.status === 'rejected') {
                 const errorMessage = settled.reason instanceof Error ? settled.reason.message : String(settled.reason);
-                this.broadcastToolResult(originalToolCall.id, {
+                // `runToolWithHooks` is the single point of emission for PostToolUseFailure.
+                this.broadcastToolResult(originalToolCall.id, this.toolSourceByName(originalToolCall.name), {
                     error: errorMessage,
                 });
                 const rejectedOutput = {
@@ -666,7 +1444,7 @@ export class ModelResult {
             if (!value) {
                 continue;
             }
-            if (value.type === 'parse_error') {
+            if (value.type === 'parse_error' || value.type === 'hook_blocked') {
                 toolResults.push(value.output);
                 this.turnBroadcaster?.push({
                     type: 'tool.call_output',
@@ -688,7 +1466,7 @@ export class ModelResult {
                     error: value.result.error.message,
                 }
                 : value.result.result);
-            this.broadcastToolResult(value.toolCall.id, toolResult, value.preliminaryResultsForCall.length > 0 ? value.preliminaryResultsForCall : undefined);
+            this.broadcastToolResult(value.toolCall.id, 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',
@@ -781,32 +1559,24 @@ export class ModelResult {
             ...this.resolvedRequest,
             stream: true,
         };
+        const startedAt = performance.now();
         const newResult = await betaResponsesSend(this.options.client, {
             responsesRequest: newRequest,
         }, this.options.options);
         if (!newResult.ok) {
             throw newResult.error;
         }
-        // Handle streaming or non-streaming response
-        const value = newResult.value;
-        if (isEventStream(value)) {
-            const followUpStream = new ReusableReadableStream(value);
-            if (this.turnBroadcaster) {
-                return this.pipeAndConsumeStream(followUpStream, turnNumber);
-            }
-            return consumeStreamForCompletion(followUpStream);
-        }
-        if (this.isNonStreamingResponse(value)) {
-            return value;
-        }
-        throw new Error('Unexpected response type from API');
+        const response = await this.materializeResponse(newResult.value, turnNumber);
+        await this.emitPostModelCall(response, startedAt, 'tool_round', turnNumber);
+        return response;
     }
     /**
-     * Make a final no-tools request to coerce a text response after the loop
-     * was halted by `stopWhen` mid-tool-call. Reuses the resolved request so
-     * `instructions`, `model`, and other API fields ride along unchanged.
-     * `tools`, `toolChoice`, and `parallelToolCalls` are stripped — the whole
-     * point is to force a text turn. The caller is expected to have already
+     * Make a final no-tool-calls request to coerce a text response after the
+     * loop was halted by `stopWhen` mid-tool-call. Reuses the resolved request
+     * so `instructions`, `model`, and other API fields ride along unchanged.
+     * `tools` stays in the request with `toolChoice: 'none'` — forbidding
+     * calls while keeping the prompt-cache prefix intact (stripping the tools
+     * block would bust the cache). The caller is expected to have already
      * executed the pending tool calls and to pass their outputs in
      * `toolOutputs` so every function_call in the input has a matching output.
      */
@@ -825,6 +1595,12 @@ export class ModelResult {
                     },
                 ]
                 : [];
+        // Default-on (`undefined`) and bare `true` get the built-in directive;
+        // a non-empty string overrides the wording; `''` appends nothing
+        // (explicit opt-out).
+        const finalDirective = allowFinalResponse === true || allowFinalResponse === undefined
+            ? DEFAULT_FINAL_RESPONSE_DIRECTIVE
+            : allowFinalResponse;
         const newInput = [
             ...normalizedOriginalInput,
             ...(Array.isArray(currentResponse.output)
@@ -833,54 +1609,89 @@ export class ModelResult {
                     currentResponse.output,
                 ]),
             ...toolOutputs,
-            ...(typeof allowFinalResponse === 'string' && allowFinalResponse.length > 0
+            ...(typeof finalDirective === 'string' && finalDirective.length > 0
                 ? [
                     {
                         role: 'user',
-                        content: allowFinalResponse,
+                        content: finalDirective,
                     },
                 ]
                 : []),
         ];
-        const { tools: _tools, toolChoice: _toolChoice, parallelToolCalls: _parallelToolCalls, ...rest } = this.resolvedRequest;
         const finalRequest = {
-            ...rest,
+            ...this.resolvedRequest,
+            // Forbid tool calls without dropping the tools block: removing
+            // `tools` would invalidate the prompt-cache prefix.
+            ...(this.resolvedRequest.tools !== undefined && {
+                toolChoice: 'none',
+            }),
             input: newInput,
             stream: true,
         };
+        this.resolvedRequest = finalRequest;
+        const startedAt = performance.now();
         const result = await betaResponsesSend(this.options.client, {
             responsesRequest: finalRequest,
         }, this.options.options);
         if (!result.ok) {
             throw result.error;
         }
-        const value = result.value;
-        if (isEventStream(value)) {
-            const stream = new ReusableReadableStream(value);
-            if (this.turnBroadcaster) {
-                return this.pipeAndConsumeStream(stream, turnNumber);
-            }
-            return consumeStreamForCompletion(stream);
-        }
-        if (this.isNonStreamingResponse(value)) {
-            return value;
-        }
-        throw new Error('Unexpected response type from API');
+        const response = await this.materializeResponse(result.value, turnNumber);
+        await this.emitPostModelCall(response, startedAt, 'final', turnNumber);
+        return response;
     }
     /**
      * Validate the final response has required fields.
      *
      * @param response - The response to validate
+     * @param allowEmptyOutput - When true, tolerate an empty (but present) output array
      * @throws Error if response is missing required fields or has invalid output
      */
-    validateFinalResponse(response) {
+    validateFinalResponse(response, allowEmptyOutput = false) {
         if (!response?.id || !response?.output) {
             throw new Error('Invalid final response: missing required fields');
         }
         if (!Array.isArray(response.output) || response.output.length === 0) {
+            if (allowEmptyOutput) {
+                return;
+            }
             throw new Error('Invalid final response: empty or invalid output');
         }
     }
+    /**
+     * Re-send the current resolved request (same accumulated input) once.
+     * Used when a follow-up after tool execution returned an empty `output`.
+     *
+     * `toolChoice` is forced to `'none'` when tools are present (mirroring
+     * `makeFinalResponseRequest`) so the retry coerces a text turn: on the
+     * natural-loop-completion path the resolved request still carries tools,
+     * and a retry that emitted a fresh `function_call` would pass
+     * `validateFinalResponse` but never be executed — silently dropping a
+     * proposed tool call. Tools stay in the request to keep the prompt-cache
+     * prefix intact.
+     */
+    async retryCurrentRequest(turnNumber) {
+        if (!this.resolvedRequest) {
+            throw new Error('Request not initialized');
+        }
+        const newRequest = {
+            ...this.resolvedRequest,
+            ...(this.resolvedRequest.tools !== undefined && {
+                toolChoice: 'none',
+            }),
+            stream: true,
+        };
+        const startedAt = performance.now();
+        const newResult = await betaResponsesSend(this.options.client, {
+            responsesRequest: newRequest,
+        }, this.options.options);
+        if (!newResult.ok) {
+            throw newResult.error;
+        }
+        const response = await this.materializeResponse(newResult.value, turnNumber);
+        await this.emitPostModelCall(response, startedAt, 'retry', turnNumber);
+        return response;
+    }
     /**
      * Resolve async functions in the request for a given turn context.
      * Extracts non-function fields and resolves any async parameter functions.
@@ -892,9 +1703,12 @@ export class ModelResult {
         if (hasAsyncFunctions(this.options.request)) {
             return resolveAsyncFunctions(this.options.request, context);
         }
-        // Already resolved, extract non-function fields
-        // Filter out stopWhen and state-related fields that aren't part of the API request
-        const { stopWhen: _, state: _s, requireApproval: _r, approveToolCalls: _a, rejectToolCalls: _rj, context: _c, ...rest } = this.options.request;
+        // Already resolved, extract non-function fields.
+        // Strip ALL client-only fields — keep this list in sync with
+        // `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, ...rest } = this.options.request;
         return rest;
     }
     /**
@@ -1035,6 +1849,12 @@ export class ModelResult {
                             this.contextStore = new ToolContextStore(resolvedCtx);
                         }
                         this.isResumingFromApproval = true;
+                        // This path bypasses the SessionStart block below but still fires
+                        // tool hooks (PreToolUse/PostToolUse) during the resume. Those
+                        // emits thread the session id per emit via hookEmitContext();
+                        // priming the manager-level default here covers direct emit()
+                        // callers on a shared manager.
+                        this.hooksManager?.setSessionId(loadedState.id);
                         await this.processApprovalDecisions();
                         return; // Skip normal initialization, we're resuming
                     }
@@ -1049,14 +1869,19 @@ export class ModelResult {
                         ]);
                         await this.saveStateSafely();
                     }
+                    // Keep manual calls durable until the resumed request produces a
+                    // response. Clearing before the API call would lose the only copy if
+                    // that request failed.
+                    this.resumingFromClientTools = loadedState.status === 'awaiting_client_tools';
                 }
                 else {
                     this.currentState = createInitialState();
                 }
-                // Update status to in_progress
-                await this.saveStateSafely({
-                    status: 'in_progress',
-                });
+                if (!this.resumingFromClientTools) {
+                    await this.saveStateSafely({
+                        status: 'in_progress',
+                    });
+                }
             }
             // Resolve async functions before initial request
             // Build initial turn context (turn 0 for initial request)
@@ -1070,6 +1895,44 @@ export class ModelResult {
             }
             // Resolve any async functions first
             let baseRequest = await this.resolveRequestForContext(initialContext);
+            // Emit SessionStart hook. The `config` payload carries a stable, small
+            // summary of session-level options so handlers can make routing/auditing
+            // decisions without the SDK having to promise more than it can deliver.
+            // If future session config becomes available, extend this object rather
+            // than introducing a new payload field.
+            if (this.hooksManager) {
+                // Prime the manager-level default for callers that emit custom hooks
+                // on a shared manager; the engine's own emits thread the session id
+                // per emit via hookEmitContext() so concurrent runs sharing one
+                // manager can't clobber each other's context.sessionId.
+                this.hooksManager.setSessionId(this.currentState?.id ?? '');
+                await this.hooksManager.emit('SessionStart', {
+                    config: {
+                        hasTools: !!this.options.tools?.length,
+                        hasApproval: !!this.requireApprovalFn ||
+                            !!(this.options.tools ?? []).some((t) => isClientTool(t) &&
+                                (t.function.requireApproval === true ||
+                                    typeof t.function.requireApproval === 'function')),
+                        hasState: !!this.stateAccessor,
+                    },
+                }, this.hookEmitContext());
+                this.sessionStartEmitted = true;
+            }
+            // Emit UserPromptSubmit hook BEFORE the stateful input-wrapping block so
+            // the handler sees the original user-supplied prompt string (and can
+            // reject or mutate it before any messages are appended). For structured
+            // (non-string) inputs we extract the latest user-role text content so
+            // handlers still get a chance to intercept; if nothing suitable is
+            // found we skip silently and document the limitation in the log below.
+            if (this.hooksManager) {
+                const promptResult = await this.maybeRunUserPromptSubmit(baseRequest.input);
+                if (promptResult) {
+                    baseRequest = {
+                        ...baseRequest,
+                        input: promptResult.applyTo(baseRequest.input),
+                    };
+                }
+            }
             // 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
@@ -1094,15 +1957,12 @@ export class ModelResult {
                 // SDK input items with different nominal types, and BaseInputsUnion
                 // already includes `any` in its element type, so the runtime shape
                 // is preserved either way.
+                // Normalize (not just wrap): bare strings must become EasyInputMessage
+                // items, exactly as the no-history branch does via
+                // normalizeInputToArray. Passing a raw string through to the request
+                // input array is rejected by OpenResponses validation (400).
                 const newInput = baseRequest.input;
-                let freshItems;
-                if (newInput !== undefined) {
-                    freshItems = Array.isArray(newInput)
-                        ? newInput
-                        : [
-                            newInput,
-                        ];
-                }
+                const freshItems = newInput !== undefined ? normalizeInputToArray(newInput) : undefined;
                 // Hook fresh items only (historical function_calls serve as
                 // name-resolution context). Leave historical items untouched.
                 const hookedFresh = freshItems
@@ -1134,6 +1994,14 @@ export class ModelResult {
             };
             // Force stream mode for initial request
             const request = this.resolvedRequest;
+            // Park PostModelCall telemetry for this dispatch: the response is
+            // materialized later (getInitialResponse or the no-tools stream
+            // teardown), which completes the emit with the true duration.
+            this.pendingModelCall = {
+                startedAt: performance.now(),
+                turnType: 'initial',
+                turnNumber: 0,
+            };
             // Make the API request
             const apiResult = await betaResponsesSend(this.options.client, {
                 responsesRequest: request,
@@ -1156,6 +2024,7 @@ export class ModelResult {
             else if (this.isNonStreamingResponse(apiResult.value)) {
                 // API returned a complete response directly - use it as the final response
                 this.finalResponse = apiResult.value;
+                await this.emitPendingModelCallOnce(this.finalResponse);
             }
             else {
                 throw new Error('Unexpected response type from API');
@@ -1182,7 +2051,8 @@ export class ModelResult {
         // 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
+        // Process approvals - execute the approved tools. Route through
+        // runToolWithHooks so PreToolUse/PostToolUse fire even on this path.
         for (const callId of this.approvedToolCalls) {
             const toolCall = pendingCalls.find((tc) => tc.id === callId);
             if (!toolCall) {
@@ -1194,7 +2064,19 @@ export class ModelResult {
                 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);
+            const hookOutcome = await this.runToolWithHooks(tool, toolCall, turnContext);
+            if (hookOutcome.type === 'parse_error') {
+                this.broadcastToolResult(callId, this.toolSourceByName(String(toolCall.name)), {
+                    error: hookOutcome.errorMessage,
+                });
+                unsentResults.push(createRejectedResult(callId, String(toolCall.name), hookOutcome.errorMessage));
+                continue;
+            }
+            if (hookOutcome.type === 'hook_blocked') {
+                unsentResults.push(createRejectedResult(callId, String(toolCall.name), hookOutcome.reason));
+                continue;
+            }
+            const result = hookOutcome.result;
             if (result === null) {
                 // HITL tool paused on approval — keep the call visible to the caller
                 // via pendingToolCalls (status becomes 'awaiting_hitl' below).
@@ -1314,6 +2196,12 @@ export class ModelResult {
             stream: true,
         };
         this.resolvedRequest = request;
+        // Park PostModelCall telemetry for the resume dispatch (see initStream).
+        this.pendingModelCall = {
+            startedAt: performance.now(),
+            turnType: 'resume',
+            turnNumber: turnContext.numberOfTurns,
+        };
         // Make the API request
         const apiResult = await betaResponsesSend(this.options.client, {
             responsesRequest: request,
@@ -1327,6 +2215,7 @@ export class ModelResult {
         }
         else if (this.isNonStreamingResponse(apiResult.value)) {
             this.finalResponse = apiResult.value;
+            await this.emitPendingModelCallOnce(this.finalResponse);
         }
         else {
             throw new Error('Unexpected response type from API');
@@ -1342,187 +2231,299 @@ export class ModelResult {
         }
         // biome-ignore lint: IIFE used for lazy initialization pattern
         this.toolExecutionPromise = (async () => {
-            await this.initStream();
-            // 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
-            let currentResponse = await this.getInitialResponse();
-            // Save initial response to state
-            await this.saveResponseToState(currentResponse);
-            // Check if tools should be executed
-            const hasToolCalls = currentResponse.output.some((item) => hasTypeProperty(item) && item.type === 'function_call');
-            if (!this.options.tools?.length || !hasToolCalls) {
-                this.finalResponse = currentResponse;
-                await this.markStateComplete();
-                return;
-            }
-            // Extract and check tool calls
-            const toolCalls = extractToolCallsFromResponse(currentResponse);
-            // Check for approval requirements
-            if (await this.handleApprovalCheck(toolCalls, 0, currentResponse)) {
-                return; // Paused for approval
-            }
-            if (!this.hasExecutableToolCalls(toolCalls)) {
-                this.finalResponse = currentResponse;
-                await this.markStateComplete();
-                return;
-            }
-            // Main execution loop
-            let currentRound = 0;
-            let stoppedByStopWhen = false;
-            while (true) {
-                // Check for external interruption
-                if (await this.checkForInterruption(currentResponse)) {
+            // SessionEnd/drain must fire on every exit path (success, early return,
+            // approval pause, interruption, and exceptions), so wrap the body in
+            // try/catch/finally and track the session-end reason as we go.
+            // Approval pauses keep reason='complete' because the run hasn't failed —
+            // it's simply paused awaiting user decisions.
+            let sessionEndReason = 'complete';
+            try {
+                await this.initStream();
+                // 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;
                 }
-                // Check stop conditions
-                if (await this.shouldStopExecution()) {
-                    stoppedByStopWhen = true;
-                    break;
-                }
-                const currentToolCalls = extractToolCallsFromResponse(currentResponse);
-                if (currentToolCalls.length === 0) {
-                    break;
+                // Get initial response
+                let currentResponse = await this.getInitialResponse();
+                // Save initial response to state
+                await this.saveResponseToState(currentResponse);
+                // Check if tools should be executed
+                const hasToolCalls = currentResponse.output.some((item) => hasTypeProperty(item) && item.type === 'function_call');
+                if (!this.options.tools?.length || !hasToolCalls) {
+                    // No tool work: keep hard throw on empty/invalid final output.
+                    this.validateFinalResponse(currentResponse);
+                    this.finalResponse = currentResponse;
+                    await this.markStateComplete();
+                    return;
                 }
+                // Extract and check tool calls
+                const toolCalls = extractToolCallsFromResponse(currentResponse);
                 // Check for approval requirements
-                if (await this.handleApprovalCheck(currentToolCalls, currentRound + 1, currentResponse)) {
-                    return;
+                if (await this.handleApprovalCheck(toolCalls, 0, currentResponse)) {
+                    return; // Paused for approval
                 }
-                if (!this.hasExecutableToolCalls(currentToolCalls)) {
-                    break;
+                // All tool calls are manual (no execute / no onToolCalled) or
+                // otherwise non-auto-resolvable — stop and surface them as pending
+                // client tools instead of marking the conversation complete with
+                // empty pendings.
+                if (!this.hasExecutableToolCalls(toolCalls)) {
+                    await this.persistClientToolsPause(currentResponse, toolCalls);
+                    return;
                 }
-                // Build turn context
-                const turnNumber = currentRound + 1;
-                const turnContext = {
-                    numberOfTurns: turnNumber,
-                };
-                await this.options.onTurnStart?.(turnContext);
-                // Resolve async functions for this turn
-                await this.resolveAsyncFunctionsForTurn(turnContext);
-                // Execute tools
-                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 = [];
-                for (const item of currentResponse.output) {
-                    if (!hasTypeProperty(item)) {
-                        continue;
+                // Main execution loop
+                let currentRound = 0;
+                let stoppedByStopWhen = false;
+                // Counts consecutive Stop-hook forceResume overrides without tool
+                // progress; reset when a tool round or fresh response lands. See
+                // runStopHook for the cap.
+                let forceResumeCount = 0;
+                while (true) {
+                    // Check for external interruption
+                    if (await this.checkForInterruption(currentResponse)) {
+                        sessionEndReason = 'user';
+                        return;
+                    }
+                    // Check stop conditions
+                    if (await this.shouldStopExecution()) {
+                        // Emit the Stop hook -- handlers can force resume or inject a
+                        // prompt. The helper enforces the consecutive-override cap so a
+                        // misbehaving handler cannot spin the loop forever.
+                        const stopDecision = await this.runStopHook(forceResumeCount);
+                        if (stopDecision === 'resume') {
+                            forceResumeCount++;
+                            // Continue the loop. If appendPrompt was supplied it was
+                            // already injected, which advances state so the stop condition
+                            // may no longer fire on the next iteration.
+                            continue;
+                        }
+                        // Stop condition fired and the hook (if any) did not force resume
+                        // -- this is a max_turns-style exit, not a natural completion.
+                        sessionEndReason = 'max_turns';
+                        stoppedByStopWhen = true;
+                        break;
+                    }
+                    const currentToolCalls = extractToolCallsFromResponse(currentResponse);
+                    if (currentToolCalls.length === 0) {
+                        break;
+                    }
+                    // Check for approval requirements
+                    if (await this.handleApprovalCheck(currentToolCalls, currentRound + 1, currentResponse)) {
+                        return;
+                    }
+                    // All-manual (or otherwise non-auto-resolvable) mid-loop round: stop
+                    // and persist the unresolved calls the same way the first-round
+                    // guard does above, so getPendingToolCalls() surfaces them after
+                    // loop end.
+                    if (!this.hasExecutableToolCalls(currentToolCalls)) {
+                        await this.persistClientToolsPause(currentResponse, currentToolCalls);
+                        return;
+                    }
+                    // Build turn context
+                    const turnNumber = currentRound + 1;
+                    const turnContext = {
+                        numberOfTurns: turnNumber,
+                    };
+                    await this.options.onTurnStart?.(turnContext);
+                    // Resolve async functions for this turn
+                    await this.resolveAsyncFunctionsForTurn(turnContext);
+                    // Execute tools
+                    const { toolResults, pausedCalls } = await this.executeToolRound(currentToolCalls, turnContext);
+                    // A tool round with observable progress resets the consecutive
+                    // forceResume counter so a legitimate override earlier in the run
+                    // does not count against a later, independent one.
+                    // Hook-blocked / rejected outputs deliberately count as progress:
+                    // the model receives the block or denial as feedback and can change
+                    // course on the next turn, which is observable forward motion even
+                    // though no tool body executed. A PreToolUse hook that blocks every
+                    // call therefore keeps resetting this counter -- acceptable,
+                    // because each reset requires a full model round trip (the loop
+                    // cannot spin hot) and stopWhen conditions still bound the run.
+                    if (toolResults.length > 0) {
+                        forceResumeCount = 0;
+                    }
+                    // Server-tool output items are already-executed results in the
+                    // response; collect them so toolResults presents a unified list.
+                    const serverToolItems = [];
+                    for (const item of currentResponse.output) {
+                        if (!hasTypeProperty(item)) {
+                            continue;
+                        }
+                        if (item.type === 'message' ||
+                            item.type === 'reasoning' ||
+                            item.type === 'function_call') {
+                            continue;
+                        }
+                        // Everything else is a server-tool output item (web_search_call,
+                        // image_generation_call, file_search_call, or generic
+                        // OutputServerToolItem covering openrouter:datetime and any new
+                        // SDK server tool types).
+                        if (isServerToolResultItem(item)) {
+                            serverToolItems.push(item);
+                        }
                     }
-                    if (item.type === 'message' ||
-                        item.type === 'reasoning' ||
-                        item.type === 'function_call') {
-                        continue;
+                    // Track execution round
+                    this.allToolExecutionRounds.push({
+                        round: currentRound,
+                        toolCalls: currentToolCalls,
+                        response: currentResponse,
+                        toolResults: [
+                            ...toolResults,
+                            ...serverToolItems,
+                        ],
+                    });
+                    // 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;
                     }
-                    // Everything else is a server-tool output item (web_search_call,
-                    // image_generation_call, file_search_call, or generic
-                    // OutputServerToolItem covering openrouter:datetime and any new
-                    // SDK server tool types).
-                    if (isServerToolResultItem(item)) {
-                        serverToolItems.push(item);
+                    // Manual (client-executed) tools produce no output this round —
+                    // `executeToolRound` returns nothing for them — so a mixed round of
+                    // auto-executed and manual calls would otherwise send a follow-up
+                    // request whose input contains a `function_call` with no matching
+                    // `function_call_output`. Providers reject that history with a 400
+                    // ("No tool output found for function call ..."). Stop the loop and
+                    // surface the response instead, so the caller can execute the manual
+                    // calls and continue — mirroring the all-manual behavior of the
+                    // `hasExecutableToolCalls` guards. Also covers calls to tool names
+                    // not present in `options.tools` at all.
+                    const resolvedCallIds = new Set(toolResults.map((r) => r.callId));
+                    const unresolvedToolCalls = currentToolCalls.filter((tc) => !resolvedCallIds.has(tc.id));
+                    if (unresolvedToolCalls.length > 0) {
+                        // Mixed auto + manual (or unknown-name) round — regular tool
+                        // outputs were already persisted via saveToolResultsToState above;
+                        // surface the unresolved calls on pendingToolCalls and stop.
+                        await this.persistClientToolsPause(currentResponse, unresolvedToolCalls);
+                        return;
                     }
+                    // Apply nextTurnParams
+                    await this.applyNextTurnParams(currentToolCalls);
+                    currentResponse = await this.makeFollowupRequest(currentResponse, toolResults, turnNumber);
+                    // A fresh response replaces the prior one -- that's new progress,
+                    // so reset consecutive forceResume counting.
+                    forceResumeCount = 0;
+                    await this.options.onTurnEnd?.(turnContext, currentResponse);
+                    // Save new response to state
+                    await this.saveResponseToState(currentResponse);
+                    currentRound++;
                 }
-                // Track execution round
-                this.allToolExecutionRounds.push({
-                    round: currentRound,
-                    toolCalls: currentToolCalls,
-                    response: currentResponse,
-                    toolResults: [
+                // If stopWhen broke the loop while the model was still emitting tool
+                // calls, execute those tool calls so they have matching outputs, then
+                // make one more `toolChoice: 'none'` request to coerce a final text
+                // response. Default-on: `undefined`, `true`, and any string enable
+                // it (`''` means "don't append a user message"); `false` opts out.
+                const allowFinalResponse = this.options.allowFinalResponse;
+                const finalResponseEnabled = allowFinalResponse !== false;
+                const pendingToolCalls = stoppedByStopWhen
+                    ? extractToolCallsFromResponse(currentResponse)
+                    : [];
+                if (stoppedByStopWhen &&
+                    finalResponseEnabled &&
+                    pendingToolCalls.length > 0 &&
+                    this.hasExecutableToolCalls(pendingToolCalls)) {
+                    const turnNumber = currentRound + 1;
+                    const turnContext = {
+                        numberOfTurns: turnNumber,
+                    };
+                    await this.options.onTurnStart?.(turnContext);
+                    await this.resolveAsyncFunctionsForTurn(turnContext);
+                    const { toolResults, pausedCalls } = await this.executeToolRound(pendingToolCalls, turnContext);
+                    // Track the executed round and persist real outputs BEFORE the HITL
+                    // pause check — mirrors the in-loop ordering at executeToolsIfNeeded
+                    // so a partial batch (HITL + regular tools) doesn't drop the regular
+                    // tool's output from state on resume.
+                    this.allToolExecutionRounds.push({
+                        round: currentRound,
+                        toolCalls: pendingToolCalls,
+                        response: currentResponse,
+                        toolResults: [
+                            ...toolResults,
+                        ],
+                    });
+                    await this.saveToolResultsToState(toolResults);
+                    if (pausedCalls.length > 0) {
+                        // HITL paused — persist and exit without making the final
+                        // text-coercion request. The conversation will resume via the
+                        // normal awaiting_hitl flow.
+                        await this.persistHitlPause(currentResponse, pausedCalls);
+                        return;
+                    }
+                    // Apply any nextTurnParams from the executed tools so they affect the
+                    // final text-coercion request (mirrors the in-loop behavior).
+                    await this.applyNextTurnParams(pendingToolCalls);
+                    // Pair any manual tool calls (no execute fn) with stub outputs so
+                    // every function_call in the *request* has a matching output. Stubs
+                    // are NOT persisted to state — only real tool outputs are — so a
+                    // resumed conversation doesn't see "Tool execution skipped" as if it
+                    // were a real result.
+                    const executedCallIds = new Set(toolResults.map((r) => r.callId));
+                    const stubOutputs = pendingToolCalls
+                        .filter((tc) => !executedCallIds.has(tc.id))
+                        .map((tc) => ({
+                        type: 'function_call_output',
+                        callId: tc.id,
+                        output: 'Tool execution skipped: step limit reached.',
+                    }));
+                    const requestOutputs = [
                         ...toolResults,
-                        ...serverToolItems,
-                    ],
-                });
-                // 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;
+                        ...stubOutputs,
+                    ];
+                    currentResponse = await this.makeFinalResponseRequest(currentResponse, requestOutputs, allowFinalResponse, turnNumber);
+                    await this.options.onTurnEnd?.(turnContext, currentResponse);
+                    await this.saveResponseToState(currentResponse);
                 }
-                // Apply nextTurnParams
-                await this.applyNextTurnParams(currentToolCalls);
-                currentResponse = await this.makeFollowupRequest(currentResponse, toolResults, turnNumber);
-                await this.options.onTurnEnd?.(turnContext, currentResponse);
-                // Save new response to state
-                await this.saveResponseToState(currentResponse);
-                currentRound++;
-            }
-            // If stopWhen broke the loop while the model was still emitting tool
-            // calls, execute those tool calls so they have matching outputs, then
-            // make one more no-tools request to coerce a final text response. An
-            // empty string still counts as "on" — it just means "don't append a
-            // user message."
-            const allowFinalResponse = this.options.allowFinalResponse;
-            const finalResponseEnabled = allowFinalResponse === true || typeof allowFinalResponse === 'string';
-            const pendingToolCalls = stoppedByStopWhen
-                ? extractToolCallsFromResponse(currentResponse)
-                : [];
-            if (stoppedByStopWhen &&
-                finalResponseEnabled &&
-                pendingToolCalls.length > 0 &&
-                this.hasExecutableToolCalls(pendingToolCalls)) {
-                const turnNumber = currentRound + 1;
-                const turnContext = {
-                    numberOfTurns: turnNumber,
-                };
-                await this.options.onTurnStart?.(turnContext);
-                await this.resolveAsyncFunctionsForTurn(turnContext);
-                const { toolResults, pausedCalls } = await this.executeToolRound(pendingToolCalls, turnContext);
-                // Track the executed round and persist real outputs BEFORE the HITL
-                // pause check — mirrors the in-loop ordering at executeToolsIfNeeded
-                // so a partial batch (HITL + regular tools) doesn't drop the regular
-                // tool's output from state on resume.
-                this.allToolExecutionRounds.push({
-                    round: currentRound,
-                    toolCalls: pendingToolCalls,
-                    response: currentResponse,
-                    toolResults: [
-                        ...toolResults,
-                    ],
-                });
-                await this.saveToolResultsToState(toolResults);
-                if (pausedCalls.length > 0) {
-                    // HITL paused — persist and exit without making the final no-tools
-                    // request. The conversation will resume via the normal awaiting_hitl
-                    // flow.
-                    await this.persistHitlPause(currentResponse, pausedCalls);
-                    return;
+                // Validate and finalize. Mini-class models intermittently return an
+                // empty final turn after a successful tool round (the tool call was
+                // the answer). Retry once, then tolerate empty output so a completed
+                // run isn't reported as failure — unless `strictFinalResponse` is set.
+                const canTolerateEmptyFinal = this.allToolExecutionRounds.length > 0 && this.options.strictFinalResponse !== true;
+                const isEmptyOutput = Array.isArray(currentResponse.output) && currentResponse.output.length === 0;
+                if (canTolerateEmptyFinal && isEmptyOutput) {
+                    const turnNumber = this.allToolExecutionRounds.length + 1;
+                    currentResponse = await this.retryCurrentRequest(turnNumber);
+                    // Persist the retried response like every other response in the
+                    // loop — otherwise stateful conversations silently lose the final
+                    // turn's content on resume.
+                    await this.saveResponseToState(currentResponse);
+                }
+                const allowEmptyOutput = canTolerateEmptyFinal &&
+                    Array.isArray(currentResponse.output) &&
+                    currentResponse.output.length === 0;
+                this.validateFinalResponse(currentResponse, allowEmptyOutput);
+                this.finalResponse = currentResponse;
+                await this.markStateComplete();
+            }
+            catch (error) {
+                sessionEndReason = 'error';
+                throw error;
+            }
+            finally {
+                // Session teardown must never mask the original error: a throw from
+                // a `finally` block replaces the in-flight exception, so a throwing
+                // SessionEnd handler (strict mode) would silently swallow the real
+                // root cause. Log teardown failures instead.
+                //
+                // drain() runs unconditionally (not gated on SessionStart) so
+                // fire-and-forget hook work from paths that skip SessionStart --
+                // e.g. approval resume, which runs Pre/PostToolUse in initStream --
+                // is still awaited before the run settles.
+                try {
+                    await this.emitSessionEndOnce(sessionEndReason);
+                    if (this.hooksManager) {
+                        await this.hooksManager.drain();
+                    }
+                }
+                catch (teardownError) {
+                    console.warn('[SessionEnd] error during session teardown:', teardownError);
                 }
-                // Apply any nextTurnParams from the executed tools so they affect the
-                // final no-tools request (mirrors the in-loop behavior).
-                await this.applyNextTurnParams(pendingToolCalls);
-                // Pair any manual tool calls (no execute fn) with stub outputs so
-                // every function_call in the *request* has a matching output. Stubs
-                // are NOT persisted to state — only real tool outputs are — so a
-                // resumed conversation doesn't see "Tool execution skipped" as if it
-                // were a real result.
-                const executedCallIds = new Set(toolResults.map((r) => r.callId));
-                const stubOutputs = pendingToolCalls
-                    .filter((tc) => !executedCallIds.has(tc.id))
-                    .map((tc) => ({
-                    type: 'function_call_output',
-                    callId: tc.id,
-                    output: 'Tool execution skipped: step limit reached.',
-                }));
-                const requestOutputs = [
-                    ...toolResults,
-                    ...stubOutputs,
-                ];
-                currentResponse = await this.makeFinalResponseRequest(currentResponse, requestOutputs, allowFinalResponse, turnNumber);
-                await this.options.onTurnEnd?.(turnContext, currentResponse);
-                await this.saveResponseToState(currentResponse);
             }
-            // Validate and finalize
-            this.validateFinalResponse(currentResponse);
-            this.finalResponse = currentResponse;
-            await this.markStateComplete();
         })();
         return this.toolExecutionPromise;
     }
@@ -1566,17 +2567,24 @@ export class ModelResult {
      */
     getFullResponsesStream() {
         return async function* () {
-            await this.initStream();
-            if (!this.reusableStream && !this.finalResponse) {
-                throw new Error('Stream not initialized');
-            }
+            await this.initStreamGuarded();
             if (!this.options.tools?.length) {
-                if (this.reusableStream) {
-                    const consumer = this.reusableStream.createConsumer();
-                    for await (const event of consumer) {
-                        yield event;
+                let streamFailed = false;
+                try {
+                    if (this.reusableStream) {
+                        const consumer = this.reusableStream.createConsumer();
+                        for await (const event of consumer) {
+                            yield event;
+                        }
                     }
                 }
+                catch (error) {
+                    streamFailed = true;
+                    throw error;
+                }
+                finally {
+                    await this.finishHooksSessionForStream(streamFailed ? 'error' : 'complete');
+                }
                 return;
             }
             const { consumer, executionPromise } = this.startTurnBroadcasterExecution();
@@ -1593,13 +2601,20 @@ export class ModelResult {
      */
     getTextStream() {
         return async function* () {
-            await this.initStream();
-            if (!this.reusableStream && !this.finalResponse) {
-                throw new Error('Stream not initialized');
-            }
+            await this.initStreamGuarded();
             if (!this.options.tools?.length) {
-                if (this.reusableStream) {
-                    yield* extractTextDeltas(this.reusableStream);
+                let streamFailed = false;
+                try {
+                    if (this.reusableStream) {
+                        yield* extractTextDeltas(this.reusableStream);
+                    }
+                }
+                catch (error) {
+                    streamFailed = true;
+                    throw error;
+                }
+                finally {
+                    await this.finishHooksSessionForStream(streamFailed ? 'error' : 'complete');
                 }
                 return;
             }
@@ -1652,19 +2667,26 @@ export class ModelResult {
             return false;
         };
         return async function* () {
-            await this.initStream();
-            if (!this.reusableStream && !this.finalResponse) {
-                throw new Error('Stream not initialized');
-            }
+            await this.initStreamGuarded();
             // No tools — stream single turn directly (no broadcaster needed)
             if (!this.options.tools?.length) {
-                if (this.reusableStream) {
-                    for await (const item of buildItemsStream(this.reusableStream)) {
-                        if (isInScope(item)) {
-                            yield item;
+                let streamFailed = false;
+                try {
+                    if (this.reusableStream) {
+                        for await (const item of buildItemsStream(this.reusableStream)) {
+                            if (isInScope(item)) {
+                                yield item;
+                            }
                         }
                     }
                 }
+                catch (error) {
+                    streamFailed = true;
+                    throw error;
+                }
+                finally {
+                    await this.finishHooksSessionForStream(streamFailed ? 'error' : 'complete');
+                }
                 return;
             }
             // Use turnBroadcaster (same pattern as getTextStream/getFullResponsesStream).
@@ -1806,10 +2828,10 @@ export class ModelResult {
      */
     getNewMessagesStream() {
         return async function* () {
-            await this.initStream();
-            if (!this.reusableStream && !this.finalResponse) {
-                throw new Error('Stream not initialized');
-            }
+            // Guarded: tears down the hook session (SessionEnd + drain) if
+            // initStream throws after SessionStart. Includes the not-initialized
+            // guard, so the manual check below is covered too.
+            await this.initStreamGuarded();
             // First yield messages from the stream in responses format
             if (this.reusableStream) {
                 yield* buildResponsesMessageStream(this.reusableStream);
@@ -1862,13 +2884,20 @@ export class ModelResult {
      */
     getReasoningStream() {
         return async function* () {
-            await this.initStream();
-            if (!this.reusableStream && !this.finalResponse) {
-                throw new Error('Stream not initialized');
-            }
+            await this.initStreamGuarded();
             if (!this.options.tools?.length) {
-                if (this.reusableStream) {
-                    yield* extractReasoningDeltas(this.reusableStream);
+                let streamFailed = false;
+                try {
+                    if (this.reusableStream) {
+                        yield* extractReasoningDeltas(this.reusableStream);
+                    }
+                }
+                catch (error) {
+                    streamFailed = true;
+                    throw error;
+                }
+                finally {
+                    await this.finishHooksSessionForStream(streamFailed ? 'error' : 'complete');
                 }
                 return;
             }
@@ -1889,19 +2918,26 @@ export class ModelResult {
      */
     getToolStream() {
         return async function* () {
-            await this.initStream();
-            if (!this.reusableStream && !this.finalResponse) {
-                throw new Error('Stream not initialized');
-            }
+            await this.initStreamGuarded();
             if (!this.options.tools?.length) {
-                if (this.reusableStream) {
-                    for await (const delta of extractToolDeltas(this.reusableStream)) {
-                        yield {
-                            type: 'delta',
-                            content: delta,
-                        };
+                let streamFailed = false;
+                try {
+                    if (this.reusableStream) {
+                        for await (const delta of extractToolDeltas(this.reusableStream)) {
+                            yield {
+                                type: 'delta',
+                                content: delta,
+                            };
+                        }
                     }
                 }
+                catch (error) {
+                    streamFailed = true;
+                    throw error;
+                }
+                finally {
+                    await this.finishHooksSessionForStream(streamFailed ? 'error' : 'complete');
+                }
                 return;
             }
             const { consumer, executionPromise } = this.startTurnBroadcasterExecution();
@@ -1931,7 +2967,9 @@ export class ModelResult {
      * Returns structured tool calls with parsed arguments.
      */
     async getToolCalls() {
-        await this.initStream();
+        await this.initStreamGuarded({
+            requireStream: false,
+        });
         // Handle non-streaming response case - use finalResponse directly
         if (this.finalResponse) {
             return extractToolCallsFromResponse(this.finalResponse);
@@ -1940,6 +2978,7 @@ export class ModelResult {
             throw new Error('Stream not initialized');
         }
         const completedResponse = await consumeStreamForCompletion(this.reusableStream);
+        await this.emitPendingModelCallOnce(completedResponse);
         return extractToolCallsFromResponse(completedResponse);
     }
     /**
@@ -1948,10 +2987,8 @@ export class ModelResult {
      */
     getToolCallsStream() {
         return async function* () {
-            await this.initStream();
-            if (!this.reusableStream && !this.finalResponse) {
-                throw new Error('Stream not initialized');
-            }
+            // Guarded: hook-session teardown on init failure (see initStreamGuarded).
+            await this.initStreamGuarded();
             if (this.reusableStream) {
                 yield* buildToolCallStream(this.reusableStream);
             }
@@ -1970,8 +3007,11 @@ export class ModelResult {
      * ```
      */
     async *getContextUpdates() {
-        // Ensure stream is initialized (which creates the context store)
-        await this.initStream();
+        // Ensure stream is initialized (which creates the context store).
+        // Guarded: hook-session teardown on init failure.
+        await this.initStreamGuarded({
+            requireStream: false,
+        });
         if (!this.contextStore) {
             return;
         }
@@ -2033,16 +3073,21 @@ export class ModelResult {
     // Multi-Turn Conversation State Methods
     // =========================================================================
     /**
-     * Check if the conversation requires human input to continue.
+     * Check if the conversation requires human/client 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.
+     * decisions — approval/rejection (`awaiting_approval`), HITL tool resume
+     * (`awaiting_hitl`), or client-executed manual tools (`awaiting_client_tools`).
+     * Also returns true whenever `pendingToolCalls` is populated regardless of
+     * status.
      */
     async requiresApproval() {
-        await this.initStream();
+        await this.initStreamGuarded({
+            requireStream: false,
+        });
         const status = this.currentState?.status;
-        if (status === 'awaiting_approval' || status === 'awaiting_hitl') {
+        if (status === 'awaiting_approval' ||
+            status === 'awaiting_hitl' ||
+            status === 'awaiting_client_tools') {
             return true;
         }
         // Also check if pendingToolCalls is populated
@@ -2053,7 +3098,9 @@ export class ModelResult {
      * Returns empty array if no approvals needed.
      */
     async getPendingToolCalls() {
-        await this.initStream();
+        await this.initStreamGuarded({
+            requireStream: false,
+        });
         // Try to trigger tool execution to populate pending calls
         if (!this.isResumingFromApproval) {
             await this.executeToolsIfNeeded();
@@ -2067,7 +3114,9 @@ export class ModelResult {
      * To resume a conversation, use the StateAccessor pattern.
      */
     async getState() {
-        await this.initStream();
+        await this.initStreamGuarded({
+            requireStream: false,
+        });
         // Ensure tool execution has been attempted (to populate final state)
         if (!this.isResumingFromApproval) {
             await this.executeToolsIfNeeded();