@openrouter/agent 0.8.0 → 0.9.0

package/esm/lib/model-result.js

@@ -1,16 +1,17 @@
 import { betaResponsesSend } from '@openrouter/sdk/funcs/betaResponsesSend';
 import { hasAsyncFunctions, resolveAsyncFunctions } from './async-params.js';
-import { appendToMessages, createInitialState, createRejectedResult, createUnsentResult, extractTextFromResponse as extractTextFromResponseState, partitionToolCalls, unsentResultsToAPIFormat, updateState, } from './conversation-state.js';
+import { AsyncToolRegistry, acquireAll, buildTaskToolStub, defaultCheckResult, hasTaskToolNameCollision, persistedTaskCheckResult, resolveCheckConfig, Semaphore, TASK_RESULT_BOUNDARY, TASK_TOOL_NAME, TaskToolInputSchema, ToolTask, } from './async-tools.js';
+import { appendToMessages, createInitialState, createRejectedResult, createUnsentResult, extractTextFromResponse as extractTextFromResponseState, normalizeInputToArray, partitionToolCalls, unsentResultsToAPIFormat, updateState, } from './conversation-state.js';
+import { canonicalizeKeyMaterial, DoomLoopMonitor, resolveDoomLoopOption, resolveLoopKeyMaterial, } from './doom-loop.js';
 import { applyNextTurnParamsToRequest, executeNextTurnParamsFunctions, } from './next-turn-params.js';
 import { ReusableReadableStream } from './reusable-stream.js';
 import { isStopConditionMet } from './stop-conditions.js';
-import { buildItemsStream, buildResponsesMessageStream, buildToolCallStream, consumeStreamForCompletion, extractReasoningDeltas, extractResponsesMessageFromResponse, extractTextDeltas, extractTextFromResponse, extractToolCallsFromResponse, extractToolDeltas, itemsStreamHandlers, streamTerminationEvents, } from './stream-transformers.js';
+import { buildItemsStream, buildResponsesMessageStream, buildToolCallStream, consumeStreamForCompletion, extractCompletionFromBuffer, extractReasoningDeltas, extractResponsesMessageFromResponse, extractTextDeltas, extractTextFromResponse, extractToolCallsFromResponse, extractToolDeltas, itemsStreamHandlers, responseHasToolCalls, streamTerminationEvents, tryExtractCompletionFromBuffer, } from './stream-transformers.js';
 import { hasTypeProperty, isFunctionCallItem, isFunctionCallOutputItem, isOutputTextDeltaEvent, isReasoningDeltaEvent, isResponseCompletedEvent, isResponseFailedEvent, isResponseIncompleteEvent, isServerToolResultItem, } from './stream-type-guards.js';
 import { resolveContext, ToolContextStore } from './tool-context.js';
 import { ToolEventBroadcaster } from './tool-event-broadcaster.js';
-import { applyOnResponseReceivedHooks, executeTool } from './tool-executor.js';
-import { isAutoResolvableTool, isClientTool, isMcpTool, isServerTool, isToolCallOutputEvent, } from './tool-types.js';
-import { normalizeInputToArray } from './turn-context.js';
+import { applyOnResponseReceivedHooks, executeTool, isAsyncToolInvocation, validateToolInput, } from './tool-executor.js';
+import { isAgentTool, isAutoResolvableTool, isClientTool, isLongRunningTool, isMcpTool, isServerTool, isToolCallOutputEvent, isUnifiedTool, } from './tool-types.js';
 /**
  * Default directive appended as a final user message on the forced final
  * turn (`allowFinalResponse` defaulting to on, or explicitly `true`).
@@ -28,11 +29,93 @@ export const DEFAULT_FINAL_RESPONSE_DIRECTIVE = 'You have reached the tool-use l
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+/**
+ * Relax a tool choice that *forces* a tool call, for follow-up turns after a
+ * tool round has executed (DEV-785).
+ *
+ * - `'required'` → `'auto'`
+ * - a specific-tool object (`{ type: 'function', name }`, `{ type: 'shell' }`,
+ *   …) → `'auto'`
+ * - `allowed_tools` with `mode: 'required'` → same set with `mode: 'auto'`
+ *   (the constraint on *which* tools may be used still applies; only the
+ *   force-a-call part is spent)
+ * - `'auto'`, `'none'`, `allowed_tools` with `mode: 'auto'`, and `undefined`
+ *   pass through unchanged.
+ */
+function relaxForcedToolChoice(toolChoice) {
+    if (toolChoice === undefined || typeof toolChoice === 'string') {
+        return toolChoice === 'required' ? 'auto' : toolChoice;
+    }
+    if (toolChoice.type === 'allowed_tools') {
+        return toolChoice.mode === 'required'
+            ? {
+                ...toolChoice,
+                mode: 'auto',
+            }
+            : toolChoice;
+    }
+    return 'auto';
+}
+/** Whether a caller-configured tool choice requires this turn to call a tool. */
+function isForcedToolChoice(toolChoice) {
+    if (toolChoice === undefined || typeof toolChoice === 'string') {
+        return toolChoice === 'required';
+    }
+    return toolChoice.type !== 'allowed_tools' || toolChoice.mode === 'required';
+}
+/** Stable identity for a concrete forced choice; null means tools are not forced. */
+function forcedToolChoiceKey(toolChoice) {
+    return isForcedToolChoice(toolChoice) ? canonicalizeKeyMaterial(toolChoice) : null;
+}
+/**
+ * Extract the call identity echoed on a server-tool output item, for
+ * doom-loop fingerprinting. Server tools never pass through the client
+ * execution funnel; their output items echo what was asked (a web-search
+ * item carries its `action`/`query`, an MCP server-tool item its
+ * `name`/`arguments`, etc.). We take every primitive/JSON field except
+ * volatile per-invocation ones (ids, status, timing) and the result payload
+ * itself, so identical repeated requests fingerprint identically. Returns
+ * null when nothing identifying remains (item types with no echoed
+ * request identity are skipped rather than collided onto `{}`).
+ */
+function extractServerToolIdentity(item) {
+    const record = item;
+    // Object.create(null), not `{}`: keys come from a JSON-parsed API response, so
+    // a `__proto__` key would hit the prototype setter instead of creating an own
+    // property and drop out of the fingerprint. Same reasoning as the
+    // Map-backed streak store.
+    const identity = Object.create(null);
+    for (const [key, value] of Object.entries(record)) {
+        if (key === 'id' ||
+            key === 'type' ||
+            key === 'status' ||
+            key === 'output' ||
+            key === 'result' ||
+            key === 'results' ||
+            key === 'error') {
+            continue;
+        }
+        if (value === undefined || typeof value === 'function' || typeof value === 'symbol') {
+            continue;
+        }
+        identity[key] = value;
+    }
+    return Object.keys(identity).length > 0 ? identity : null;
+}
 // 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;
+/**
+ * Sentinel marking a tool-call id that appeared MORE THAN ONCE in one batch.
+ * Ids are model-emitted and nothing upstream enforces uniqueness; a colliding
+ * id must poison the loop-key cache entry rather than let the last write win,
+ * or one call's doom-loop identity aliases onto another's and its repetition
+ * becomes invisible to the per-call detector. Colliding calls fall through to
+ * per-call resolution at the checkpoint.
+ */
+const DUPLICATE_CALL_ID = Symbol('duplicate-call-id');
 /**
  * Human-readable label for a value that failed the `isRecord` check. Used
  * exclusively to make `toModelOutput` misuse errors specific.
@@ -198,7 +281,16 @@ export class ModelResult {
         this.allToolExecutionRounds = [];
         // Track resolved request after async function resolution
         this.resolvedRequest = null;
+        // A forced caller-configured tool choice is one-shot until its resolved
+        // semantic value changes. The consumed key survives state-backed pauses;
+        // the configured key/value are refreshed whenever async parameters resolve.
+        this.activeConsumedForcedToolChoiceKey = null;
+        this.configuredForcedToolChoiceKey = null;
+        this.preparedToolChoiceCommit = null;
+        this.dispatchedToolChoiceCommit = null;
+        this.dispatchedCallerToolChoice = false;
         this.resumingFromClientTools = false;
+        this.resumingFromAsyncTools = false;
         // State management for multi-turn conversations
         this.stateAccessor = null;
         this.currentState = null;
@@ -237,8 +329,63 @@ export class ModelResult {
             cost: 0,
             hasCost: false,
         };
+        // Set when a verdict resolves to 'stop'; checked at the loop boundaries.
+        // Persisted inside ConversationState.doomLoop (as `stopVerdict`) so a
+        // condemned run stays condemned across decision-only resumes; cleared by
+        // a fresh conversational turn (see the initStream restore site).
+        this.doomLoopStop = null;
+        // Steer messages queued by 'steer' verdicts, injected before the next
+        // model request (same mechanism as the Stop hook's appendPrompt).
+        // Persisted as `pendingSteer` so guidance queued right before a pause is
+        // delivered on resume instead of silently dropped.
+        this.pendingDoomLoopSteer = [];
+        // Monotonic round counter for doom-loop streaks. Bumped at every
+        // execution-batch boundary (tool round, approval auto-approve batch,
+        // approved-on-resume batch); identical calls within one batch count as
+        // ONE piece of loop evidence (a streak measures the model re-issuing a
+        // call after seeing its result, which requires a round trip).
+        this.doomLoopRound = 0;
+        // Final decision for each (tool, fingerprint) in the current round.
+        // Duplicates reuse the decision instead of re-incrementing the streak or
+        // re-emitting the DoomLoopDetected hook; `message` carries the verdict's
+        // explanation for block outputs.
+        this.doomLoopRoundDecisions = new Map();
+        // Loop-key resolutions computed while declaring the current round, keyed by
+        // tool-call id. A `loopKey` function is user code that may count, log, or
+        // return something different each time, so it must run at most once per
+        // call: the per-call checkpoint reuses what the declaration resolved instead
+        // of resolving again. Cleared with the round. An id seen twice in one batch
+        // maps to DUPLICATE_CALL_ID — see the write site.
+        this.doomLoopRoundKeyMaterial = new Map();
+        // Serialization chain for doom evaluations: parallel tool executions
+        // append their evaluation here in call order (the .map() over a round's
+        // calls runs synchronously to the first await), so streak recording
+        // stays a pure function of the transcript even though hashing is async.
+        this.doomLoopChain = Promise.resolve();
+        // Armed by an 'escalate' verdict; consumed by the next follow-up request
+        // as ONE-TURN overrides (model swap and/or forced openrouter:advisor).
+        // Deliberately NOT persisted: an escalation is a reaction to the loop's
+        // live state; a resumed run re-detects and re-escalates if still stuck
+        // (the CONSUMED budget does persist, via the monitor's escalationsUsed).
+        this.pendingDoomLoopEscalation = null;
+        // Async tool support (tool.background / tool.deferred). The registry
+        // tracks task identity and settled outcomes; created lazily on the first
+        // async tool call so runs without async tools carry zero overhead.
+        this.asyncToolRegistry = null;
+        // Concurrency gates: the round gate bounds simultaneous executions within
+        // a tool round; per-tool gates bound one tool across the run; the
+        // background pool bounds detached background work.
+        this.roundGate = null;
+        this.backgroundPool = null;
+        this.perToolGates = new Map();
+        // Per-call abort controllers for in-flight tool executions, keyed by call
+        // id. Aborted on run abort / cancel() so cooperative tool bodies stop.
+        this.inflightToolControllers = new Map();
         this.options = options;
         this.hooksManager = options.hooks;
+        const doomLoopConfig = resolveDoomLoopOption(options.doomLoop);
+        this.doomLoopMonitor = doomLoopConfig ? new DoomLoopMonitor(doomLoopConfig) : null;
+        this.doomLoopEscalation = doomLoopConfig?.escalation ?? null;
         // Runtime validation: approval decisions require state
         const hasApprovalDecisions = (options.approveToolCalls && options.approveToolCalls.length > 0) ||
             (options.rejectToolCalls && options.rejectToolCalls.length > 0);
@@ -251,6 +398,76 @@ export class ModelResult {
         this.requireApprovalFn = options.requireApproval ?? null;
         this.approvedToolCalls = options.approveToolCalls ?? [];
         this.rejectedToolCalls = options.rejectToolCalls ?? [];
+        // Concurrency gates. Round default stays unbounded (existing behavior);
+        // the background pool always has a cap (default 16 — detached work has
+        // no round to bound it).
+        const concurrency = options.toolConcurrency;
+        const roundLimit = typeof concurrency === 'number' ? concurrency : concurrency?.round;
+        if (roundLimit !== undefined) {
+            this.roundGate = new Semaphore(roundLimit);
+        }
+        const backgroundLimit = typeof concurrency === 'object' ? (concurrency.background ?? 16) : 16;
+        this.backgroundPool = new Semaphore(backgroundLimit);
+    }
+    /** Lazily create the async tool registry. */
+    ensureAsyncToolRegistry() {
+        if (!this.asyncToolRegistry) {
+            this.asyncToolRegistry = new AsyncToolRegistry();
+        }
+        return this.asyncToolRegistry;
+    }
+    /** Per-tool concurrency gate, created on first use. */
+    perToolGate(toolName) {
+        const tool = this.options.tools?.find((t) => isClientTool(t) && t.function.name === toolName);
+        if (!tool || isServerTool(tool)) {
+            return undefined;
+        }
+        const limit = tool.function.maxConcurrency;
+        if (limit === undefined) {
+            return undefined;
+        }
+        let gate = this.perToolGates.get(toolName);
+        if (!gate) {
+            gate = new Semaphore(limit);
+            this.perToolGates.set(toolName, gate);
+        }
+        return gate;
+    }
+    /**
+     * Compose the per-call abort signal for one tool execution: the run
+     * signal plus a per-call controller the engine can abort independently
+     * (timeout race, cancelTask, cancel()). The tool deadline deliberately
+     * does NOT ride the signal here — the race in `executeSingleToolCall`
+     * owns exactly one timer (which aborts the controller), so the round's
+     * timeout resolution and the body's abort observation cannot disagree.
+     */
+    composeToolSignal(toolName, callId) {
+        const tool = this.options.tools?.find((t) => isClientTool(t) && t.function.name === toolName);
+        const timeoutMs = tool && !isServerTool(tool)
+            ? (tool.function.timeoutMs ?? this.options.toolTimeoutMs)
+            : this.options.toolTimeoutMs;
+        const controller = new AbortController();
+        this.inflightToolControllers.set(callId, controller);
+        const signal = this.options.signal
+            ? AbortSignal.any([
+                controller.signal,
+                this.options.signal,
+            ])
+            : controller.signal;
+        return {
+            controller,
+            signal,
+            timeoutMs,
+        };
+    }
+    /** Abort every in-flight tool execution and background task. */
+    abortAllToolWork(reason) {
+        const error = new Error(reason ?? 'Run aborted');
+        for (const controller of this.inflightToolControllers.values()) {
+            controller.abort(error);
+        }
+        this.inflightToolControllers.clear();
+        this.asyncToolRegistry?.abortAll(reason);
     }
     /**
      * Get or create the unified turn broadcaster (lazy initialization).
@@ -490,6 +707,13 @@ export class ModelResult {
             this.resumingFromClientTools = false;
             stateUpdates.status = 'in_progress';
         }
+        if (this.resumingFromAsyncTools) {
+            // The resumed request succeeded — the conversation is moving again.
+            // Pending tasks that are still unresolved stay on pendingAsyncTools
+            // (resumeToolResults maintains that list); only the status advances.
+            this.resumingFromAsyncTools = false;
+            stateUpdates.status = 'in_progress';
+        }
         await this.saveStateSafely(stateUpdates);
     }
     /**
@@ -497,6 +721,9 @@ export class ModelResult {
      * Sets the conversation status to 'complete' indicating no further tool execution is needed.
      */
     async markStateComplete() {
+        // A later conversational turn is a new logical run and may force its
+        // first tool call again.
+        this.resetForcedToolChoicePolicy();
         await this.saveStateSafely({
             status: 'complete',
         });
@@ -533,6 +760,7 @@ export class ModelResult {
         // Save partial state
         if (this.currentState) {
             const currentToolCalls = extractToolCallsFromResponse(currentResponse);
+            this.resetForcedToolChoicePolicy();
             await this.saveStateSafely({
                 status: 'interrupted',
                 partialResponse: {
@@ -659,6 +887,10 @@ export class ModelResult {
      */
     hasExecutableToolCalls(toolCalls) {
         return toolCalls.some((toolCall) => {
+            // The universal task tool is engine-intercepted — always executable.
+            if (toolCall.name === TASK_TOOL_NAME && this.taskToolActive()) {
+                return true;
+            }
             const tool = this.options.tools?.find((t) => isClientTool(t) && t.function.name === toolCall.name);
             return tool && isAutoResolvableTool(tool);
         });
@@ -692,7 +924,7 @@ export class ModelResult {
      * - `execution`: The tool ran. `result` is the ToolExecutionResult.
      *   `effectiveToolCall` reflects any `mutatedInput` piped by PreToolUse.
      */
-    async runToolWithHooks(tool, toolCall, turnContext, onPreliminaryResult) {
+    async runToolWithHooks(tool, toolCall, turnContext, onPreliminaryResult, extras) {
         // 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
@@ -702,6 +934,23 @@ export class ModelResult {
         // synthetic error without running the tool or firing hooks.
         const rawArgs = toolCall.arguments;
         if (typeof rawArgs === 'string') {
+            // Malformed calls are classic doom-loop fuel: a model stuck emitting
+            // the same invalid JSON re-triggers this parse error forever. Record
+            // the raw string as the call's identity so the streak trips the
+            // detector instead of bouncing off the parse error unbounded. The
+            // parse-error output below already prevents execution, so 'block'
+            // needs no extra handling; 'steer'/'stop' side effects are applied
+            // inside the ordered evaluation.
+            if (this.doomLoopMonitor) {
+                await this.enqueueDoomLoopEvaluation({
+                    toolName: String(toolCall.name),
+                    keyMaterial: rawArgs,
+                    fallbackKeyMaterial: null,
+                    allowBlock: true,
+                    detector: 'tool-fingerprint',
+                    toolCall,
+                });
+            }
             const errorMessage = `Failed to parse tool call arguments for "${toolCall.name}": The model provided invalid JSON. ` +
                 `Raw arguments received: "${rawArgs}". ` +
                 'Please provide valid JSON arguments for this tool call.';
@@ -719,6 +968,29 @@ export class ModelResult {
                 },
             };
         }
+        // Doom-loop checkpoint — BEFORE PreToolUse, on the arguments the MODEL
+        // issued (pre-mutation): the loop evidence is the model repeating
+        // itself, and a PreToolUse hook that rewrites input each call (e.g.
+        // injecting a nonce) must not mask that repetition. A 'block' verdict
+        // returns the same `hook_blocked` shape as a PreToolUse block, so every
+        // caller handles it identically; PreToolUse deliberately does not fire
+        // for doom-blocked calls (nothing will execute — mirrors parse_error).
+        const doomOutcome = await this.checkDoomLoopBeforeExecution(tool, toolCall);
+        if (doomOutcome.blocked) {
+            return {
+                type: 'hook_blocked',
+                toolCall,
+                reason: doomOutcome.reason,
+                output: {
+                    type: 'function_call_output',
+                    id: `output_${toolCall.id}`,
+                    callId: toolCall.id,
+                    output: JSON.stringify({
+                        error: doomOutcome.reason,
+                    }),
+                },
+            };
+        }
         let effectiveToolCall = toolCall;
         // Emit PreToolUse hook -- can block or mutate input.
         if (this.hooksManager) {
@@ -764,13 +1036,18 @@ export class ModelResult {
         // 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 result = await executeTool(tool, effectiveToolCall, turnContext, onPreliminaryResult, this.contextStore ?? undefined, this.options.sharedContextSchema, extras);
         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.
+        // Async invocations (background/deferred) haven't produced their final
+        // output either — Post hooks fire at settlement via
+        // emitAsyncSettledHooks (in-process delivery). Results delivered by
+        // resumeToolResults in ANOTHER process have no hooksManager there;
+        // that path stays uncovered and is documented on resumeToolResults.
         // Emit PostToolUse or PostToolUseFailure.
-        if (this.hooksManager && result !== null) {
+        if (this.hooksManager && result !== null && !isAsyncToolInvocation(result)) {
             if (result.error) {
                 await this.hooksManager.emit('PostToolUseFailure', {
                     toolName: effectiveToolCall.name,
@@ -793,6 +1070,557 @@ export class ModelResult {
             result,
         };
     }
+    /**
+     * Advance the doom-loop round counter and declare the round's calls. Called
+     * at every execution-batch boundary (main tool round, auto-approve batch
+     * while pausing, approved-on-resume batch). Identical calls WITHIN one round
+     * are duplicates — one piece of loop evidence, one shared decision.
+     *
+     * `batch` is every call the round will make. A round's identity for one tool
+     * is the *set* of fingerprints it was called with, and that set has to be
+     * complete before any of the round's calls is scored: accumulating it call
+     * by call made a round that is a superset of the previous one transiently
+     * match it, blocking calls that represented real progress, with the outcome
+     * depending on emission order. Declaration is best-effort — a call whose key
+     * material is exempt or unhashable is simply left out, and the per-call
+     * fallback chain in `enqueueDoomLoopEvaluation` still governs identity at
+     * record time.
+     *
+     * Only calls that the round will actually CHECK are declared. A `loopKey`
+     * function is user code that may count or log, so it must not run for a call
+     * the detector never evaluates: manual tool calls (no `execute`, no
+     * `onToolCalled`) are handed to the caller and never recorded, and every
+     * execution path skips them with the same `isAutoResolvableTool` predicate
+     * used here. Their absence from the declared set is also correct on its own
+     * terms — they are not evidence, so they are not part of the round.
+     *
+     * INVARIANT — every declared member must eventually be recorded. A call
+     * that is declared but never reaches the doom-loop checkpoint is a phantom
+     * member of the round's identity: the tool's streak silently resets the
+     * moment the phantom stops being emitted (pinned by the "declared-but-
+     * never-recorded member" test in doom-loop-fanout.test.ts). The filters
+     * below therefore MIRROR every path that skips recording — unknown/manual
+     * tools (`isAutoResolvableTool`, also gating executeAutoApproveTools and
+     * the approval-resume loop), `hookDeniedCalls` (consumed before the
+     * checkpoint in executeSingleToolCall), and `loopKey`-exempt calls (early
+     * return in checkDoomLoopBeforeExecution; the same resolution is cached
+     * here so both sides agree). If you add a new short-circuit between
+     * declaration and the checkpoint — a pre-execution gate, a batch filter —
+     * it MUST be reflected here, or fan-out detection degrades silently for
+     * that tool rather than failing loudly.
+     *
+     * KNOWN RESIDUAL (documented, not mirrored): a per-request timeout or
+     * abort can cancel a call AFTER declaration but BEFORE its checkpoint,
+     * leaving a declared phantom for that round. Bounded and fail-safe: the
+     * round-set streak for that tool resets when the phantom stops recurring,
+     * while per-call streaks are unaffected — detection degrades to per-call
+     * for the affected tool rather than being lost. Un-declaring mid-round
+     * would mutate the round's identity while it is being scored, which is the
+     * incremental-set order-dependence this design exists to prevent.
+     */
+    async beginDoomLoopRound(batch = []) {
+        const monitor = this.doomLoopMonitor;
+        if (!monitor) {
+            return;
+        }
+        this.doomLoopRound++;
+        this.doomLoopRoundDecisions.clear();
+        this.doomLoopRoundKeyMaterial.clear();
+        const declared = [];
+        for (const toolCall of batch) {
+            const tool = this.options.tools?.find((t) => isClientTool(t) && t.function.name === toolCall.name);
+            /*
+             * Never checked => never recorded => must not be declared. Declaring a
+             * call that never arrives inflates the round's identity: a sibling that
+             * IS recorded gets scored against a set containing a phantom member, and
+             * the streak resets spuriously once the phantom stops appearing (e.g. the
+             * model drops a malformed call while still repeating the valid one).
+             * Keeping `loopKey` from running for such a call is the same check.
+             *
+             * This gate deliberately precedes the malformed-arguments branch below:
+             * a raw-string call to an unknown or manual tool is still never recorded.
+             */
+            if (tool === undefined || !isAutoResolvableTool(tool)) {
+                continue;
+            }
+            /*
+             * Same reasoning for a call the PermissionRequest hook denied without
+             * pausing: `hookDeniedCalls` is populated before the round begins, and
+             * `runToolWithHooks` synthesizes the rejection before reaching the
+             * doom-loop checkpoint, so the call is never recorded either.
+             */
+            if (this.hookDeniedCalls.has(toolCall.id)) {
+                continue;
+            }
+            const rawArgs = toolCall.arguments;
+            if (typeof rawArgs === 'string') {
+                // Malformed call: its identity is the raw string (see runToolWithHooks).
+                declared.push({
+                    toolName: String(toolCall.name),
+                    keyMaterial: rawArgs,
+                });
+                continue;
+            }
+            /*
+             * `resolveLoopKeyMaterial` catches a throwing `loopKey`, but not every
+             * throw: the field-list form reads `args[field]`, so a getter on the
+             * arguments object throws out of it uncaught. Declaration runs once for
+             * the whole batch, so letting that escape would fail the entire round —
+             * and the run — over one odd call, breaking the invariant that detection
+             * never affects a run except through its ladder actions. Skip just that
+             * call; the per-call checkpoint hits the same throw inside its own
+             * try/catch and applies the documented fallback chain there.
+             */
+            let resolution;
+            try {
+                resolution = resolveLoopKeyMaterial(isClientTool(tool) ? tool.function.loopKey : undefined, (toolCall.arguments ?? {}));
+            }
+            catch (error) {
+                console.warn(`[DoomLoop] could not resolve loop identity for "${toolCall.name}" while declaring the round; ` +
+                    'excluding it from the round set:', error);
+                continue;
+            }
+            /*
+             * Cache so the per-call checkpoint does not invoke `loopKey` a second
+             * time; keyed by call id. Ids are MODEL-emitted strings and nothing
+             * upstream enforces uniqueness, so a duplicate id must not alias one
+             * call's identity onto another: overwriting here meant the first call's
+             * checkpoint read the second call's key material, its true fingerprint
+             * was never recorded, and a model emitting `(id=X, read a), (id=X,
+             * read b_i)` each round evaded the per-call detector for `a` entirely
+             * (measured: zero detections across four such rounds). On a duplicate
+             * id the cache poisons that id instead: both calls fall through to
+             * per-call resolution at the checkpoint, costing at most a duplicate
+             * `loopKey` invocation for the colliding calls — correctness over the
+             * single-invocation economy, for protocol-malformed input only.
+             */
+            if (this.doomLoopRoundKeyMaterial.has(toolCall.id)) {
+                this.doomLoopRoundKeyMaterial.set(toolCall.id, DUPLICATE_CALL_ID);
+            }
+            else {
+                this.doomLoopRoundKeyMaterial.set(toolCall.id, resolution);
+            }
+            if (resolution.kind === 'exempt') {
+                continue;
+            }
+            declared.push({
+                toolName: String(toolCall.name),
+                keyMaterial: resolution.keyMaterial,
+            });
+        }
+        await monitor.declareRound(this.doomLoopRound, declared);
+    }
+    /**
+     * Evaluate one call against the doom-loop monitor, serialized on
+     * `doomLoopChain` so parallel executions record in the deterministic
+     * order their evaluations were ENQUEUED (the `.map()` over a round's
+     * calls runs synchronously to its first await, i.e. model-emission
+     * order) — not in hash-completion order.
+     *
+     * Applies the fallback invariant: detection must never take down or
+     * alter a run except via its defined actions. Unhashable key material
+     * (bigint, non-finite numbers, circular/too-deep structures from a
+     * computed loopKey) degrades to `fallbackKeyMaterial`; if THAT is also
+     * unhashable (parse-error path passes null), detection is skipped for
+     * the call and it proceeds normally.
+     *
+     * Returns the final decision for this call (`action: 'proceed'` when no
+     * rung fired or the call is exempt/skipped; `message` carries the
+     * verdict's explanation for block outputs). Side effects (steer queue,
+     * stop arm) are applied here so every caller shares them.
+     */
+    enqueueDoomLoopEvaluation(evaluation) {
+        const run = async () => {
+            const monitor = this.doomLoopMonitor;
+            if (!monitor) {
+                return {
+                    action: 'proceed',
+                };
+            }
+            let record;
+            try {
+                record = await monitor.recordToolCall(evaluation.toolName, evaluation.keyMaterial, this.doomLoopRound, {
+                    allowBlock: evaluation.allowBlock,
+                    detector: evaluation.detector,
+                });
+            }
+            catch (error) {
+                // Unhashable key material (bigint/NaN/circular/too-deep loopKey
+                // output). Fall back to the raw-arguments identity; if that also
+                // fails, skip detection for this call — never fail the call itself.
+                console.warn(`[DoomLoop] could not fingerprint call to "${evaluation.toolName}"; ` +
+                    `${evaluation.fallbackKeyMaterial !== null ? 'falling back to full arguments' : 'skipping detection for this call'}:`, error);
+                if (evaluation.fallbackKeyMaterial === null) {
+                    return {
+                        action: 'proceed',
+                    };
+                }
+                try {
+                    record = await monitor.recordToolCall(evaluation.toolName, evaluation.fallbackKeyMaterial, this.doomLoopRound, {
+                        allowBlock: evaluation.allowBlock,
+                        detector: evaluation.detector,
+                    });
+                }
+                catch (fallbackError) {
+                    console.warn(`[DoomLoop] fallback identity for "${evaluation.toolName}" also unhashable; skipping detection for this call:`, fallbackError);
+                    return {
+                        action: 'proceed',
+                    };
+                }
+            }
+            // Same (tool, fingerprint) already decided this round: reuse the
+            // decision — no second streak increment, no second hook emission.
+            const decisionKey = `${evaluation.toolName}\n${record.fingerprint}`;
+            if (record.duplicateInRound) {
+                return (this.doomLoopRoundDecisions.get(decisionKey) ?? {
+                    action: 'proceed',
+                });
+            }
+            if (!record.verdict) {
+                const decision = {
+                    action: 'proceed',
+                };
+                this.doomLoopRoundDecisions.set(decisionKey, decision);
+                return decision;
+            }
+            const action = await this.applyDoomLoopVerdict(record.verdict, evaluation.toolCall);
+            const decision = {
+                action,
+                message: record.verdict.message,
+            };
+            this.doomLoopRoundDecisions.set(decisionKey, decision);
+            this.applyDoomLoopSideEffects(action, record.verdict);
+            return decision;
+        };
+        // Serialize on the chain; keep the chain alive even if an evaluation
+        // throws unexpectedly (it should not — run() catches everything).
+        const evaluationPromise = this.doomLoopChain.then(run, run);
+        this.doomLoopChain = evaluationPromise.catch(() => undefined);
+        return evaluationPromise;
+    }
+    /**
+     * Doom-loop checkpoint for one tool call, run before PreToolUse/execution.
+     *
+     * Resolves the tool's `loopKey` declaration (function |
+     * false | absent — see {@link resolveLoopKeyMaterial}) and evaluates the
+     * call against the monitor. Ladder actions:
+     *
+     * - `observe` — hook already emitted, nothing else.
+     * - `steer`   — queue a corrective user message for the next model turn.
+     * - `block`   — return `blocked` so the caller synthesizes an error output
+     *   without executing. The model sees the explanation in the tool result.
+     * - `stop`    — arm `doomLoopStop`; ALSO blocks this call (executing a
+     *   call the detector just condemned, then stopping, would be
+     *   incoherent). The loop halts before the next model request.
+     */
+    async checkDoomLoopBeforeExecution(tool, toolCall) {
+        if (!this.doomLoopMonitor) {
+            return {
+                blocked: false,
+            };
+        }
+        // The parse-error guard in runToolWithHooks already rejected raw-string
+        // arguments, so what remains is the parsed record (or null/undefined for
+        // no-args calls — coerced to {} the same way the PreToolUse payload is).
+        const callArguments = (toolCall.arguments ?? {});
+        /*
+         * Reuse what `beginDoomLoopRound` resolved for this call when it declared
+         * the round. `loopKey` is user code — it may count, log, or return a fresh
+         * value each time — so it must run at most once per call. Resolving here
+         * as well would double-invoke it and, for a non-repeatable callback, make
+         * the declared identity and the recorded identity disagree.
+         */
+        const cached = this.doomLoopRoundKeyMaterial.get(toolCall.id);
+        let resolution;
+        if (cached !== undefined && cached !== DUPLICATE_CALL_ID) {
+            resolution = cached;
+        }
+        else {
+            /*
+             * Not declared (undeclared round, or the declaration skipped this call).
+             * `resolveLoopKeyMaterial` can throw despite catching `loopKey` itself —
+             * the field-list form reads `args[field]`, so a getter on the arguments
+             * throws out of it. Detection must never reject a call or fail a run
+             * except through a ladder action, so skip detection for this one call.
+             */
+            try {
+                resolution = resolveLoopKeyMaterial(isClientTool(tool) ? tool.function.loopKey : undefined, callArguments);
+            }
+            catch (error) {
+                console.warn(`[DoomLoop] could not resolve loop identity for "${toolCall.name}"; ` +
+                    'skipping detection for this call:', error);
+                return {
+                    blocked: false,
+                };
+            }
+        }
+        if (resolution.kind === 'exempt') {
+            return {
+                blocked: false,
+            };
+        }
+        if (resolution.kind === 'fallback') {
+            console.warn(`[DoomLoop] tool "${toolCall.name}": ${resolution.warning}`);
+        }
+        const decision = await this.enqueueDoomLoopEvaluation({
+            toolName: String(toolCall.name),
+            keyMaterial: resolution.keyMaterial,
+            fallbackKeyMaterial: resolution.keyMaterial === callArguments ? null : callArguments,
+            allowBlock: true,
+            detector: 'tool-fingerprint',
+            toolCall,
+        });
+        if (decision.action === 'block' || decision.action === 'stop') {
+            return {
+                blocked: true,
+                reason: decision.message ??
+                    `Doom loop suspected: tool "${toolCall.name}" is repeating identical calls. ` +
+                        'Repeating the call will not change the result. Take a different approach.',
+            };
+        }
+        return {
+            blocked: false,
+        };
+    }
+    /**
+     * Emit the DoomLoopDetected hook for a verdict and resolve the final
+     * action. Handlers may override per event (`overrideAction`), letting
+     * userland escalate or de-escalate without reconfiguring the ladder;
+     * the LAST override in the chain wins (matching PermissionRequest's
+     * last-wins convention). Non-blockable verdicts (text, server tools —
+     * the tokens are already emitted / the tool already ran) downgrade a
+     * 'block' override to 'observe'. An 'escalate' override is honored only
+     * when an escalation mechanism is configured with remaining budget;
+     * otherwise it downgrades to 'observe' (never silently to a stronger
+     * action).
+     */
+    async applyDoomLoopVerdict(verdict, toolCall) {
+        let action = verdict.action;
+        if (this.hooksManager) {
+            const emit = await this.hooksManager.emit('DoomLoopDetected', {
+                detector: verdict.detector,
+                action: verdict.action,
+                streak: verdict.streak,
+                fingerprint: verdict.fingerprint,
+                ...(verdict.toolName !== undefined && {
+                    toolName: verdict.toolName,
+                }),
+                ...(toolCall !== undefined &&
+                    isRecord(toolCall.arguments) && {
+                    toolInput: toolCall.arguments,
+                }),
+                message: verdict.message,
+            }, this.hookEmitContext(verdict.toolName));
+            for (const result of emit.results) {
+                if (result?.overrideAction) {
+                    action = result.overrideAction;
+                }
+            }
+        }
+        if (verdict.detector !== 'tool-fingerprint' && action === 'block') {
+            // Nothing to block for text/server-tool verdicts; observe instead of
+            // silently acting stronger/weaker than the handler intended.
+            action = 'observe';
+        }
+        if (action === 'escalate' && !(this.doomLoopMonitor?.canEscalate() ?? false)) {
+            // Ladder verdicts are already budget-gated by the monitor; this
+            // catches hook overrides requesting escalation without config/budget.
+            action = 'observe';
+        }
+        return action;
+    }
+    /**
+     * Apply the side effects of a resolved doom-loop action shared by every
+     * checkpoint: queue steer guidance, arm an escalation for the next
+     * request, or arm the stop verdict. 'block' has no shared side effect —
+     * the calling checkpoint synthesizes the blocked output itself.
+     */
+    applyDoomLoopSideEffects(action, verdict) {
+        if (action === 'steer') {
+            this.queueDoomLoopSteer(verdict.message);
+        }
+        else if (action === 'escalate') {
+            // Latch the FIRST escalation verdict for the next request; a second
+            // verdict in the same window (e.g. tool + text detectors both firing)
+            // must not double-spend the budget.
+            if (this.pendingDoomLoopEscalation === null) {
+                this.pendingDoomLoopEscalation = verdict;
+                // The model should know why its next turn looks different. Rides
+                // the persisted steer path so the transcript stays well-formed.
+                this.queueDoomLoopSteer(`${verdict.message} An escalated turn follows: use the additional guidance to change course.`);
+            }
+        }
+        else if (action === 'stop') {
+            this.doomLoopStop = verdict;
+        }
+    }
+    /**
+     * Consume a pending escalation into ONE-TURN request overrides:
+     *
+     * - `model` — replace the request's model for this dispatch only (the
+     *   base `resolvedRequest` is never mutated, so the following turn
+     *   reverts automatically).
+     * - `advisor` — append an `openrouter:advisor` server tool (transcript
+     *   forwarded, instructions describing the detected loop) and pin
+     *   `toolChoice` to it via `allowed_tools`/`required`, so the stuck model
+     *   must consult the advisor before doing anything else this turn.
+     *
+     * Burns one unit of the escalation budget (persisted via the monitor) at
+     * APPLICATION time — verdicts the engine never got to apply (run stopped,
+     * paused, or overridden) do not spend.
+     */
+    takeDoomLoopEscalationOverrides() {
+        const verdict = this.pendingDoomLoopEscalation;
+        const config = this.doomLoopEscalation;
+        if (!verdict || !config || !this.doomLoopMonitor?.canEscalate()) {
+            this.pendingDoomLoopEscalation = null;
+            return null;
+        }
+        this.pendingDoomLoopEscalation = null;
+        this.doomLoopMonitor.consumeEscalation();
+        const overrides = {};
+        if (config.model !== undefined) {
+            overrides['model'] = config.model;
+            // A single-model override must not be shadowed by a fallback list.
+            overrides['models'] = undefined;
+        }
+        if (config.advisor !== undefined && config.advisor !== false) {
+            const advisorParameters = {
+                forwardTranscript: true,
+                instructions: 'You are an escalation advisor. The executing model appears stuck in a loop: ' +
+                    `${verdict.message} Diagnose why its approach is failing and give concrete, ` +
+                    'specific instructions for a DIFFERENT approach. Do not restate the problem.',
+                ...(typeof config.advisor === 'object' ? config.advisor : {}),
+            };
+            const existingTools = Array.isArray(this.resolvedRequest?.['tools'])
+                ? this.resolvedRequest['tools']
+                : [];
+            overrides['tools'] = [
+                ...existingTools,
+                {
+                    type: 'openrouter:advisor',
+                    parameters: advisorParameters,
+                },
+            ];
+            // Force the consult: constrain this turn's tool surface to the
+            // advisor and require a call.
+            overrides['toolChoice'] = {
+                type: 'allowed_tools',
+                mode: 'required',
+                tools: [
+                    {
+                        type: 'openrouter:advisor',
+                    },
+                ],
+            };
+        }
+        return overrides;
+    }
+    /**
+     * Step-level doom-loop checkpoint on a fresh model response:
+     *
+     * 1. Text detectors — within-response token repetition + cross-step
+     *    identical-text streak.
+     * 2. Server-tool fingerprints — server tools (web_search_call etc.) never
+     *    pass through runToolWithHooks; their repetition is detected here,
+     *    post-execution, from the echoed call fields on the output item.
+     *    Post-execution ⇒ block is meaningless (allowBlock: false); the
+     *    actions are observe/steer/stop.
+     *
+     * Runs where the loop already inspects each fresh response, so scripted
+     * transcripts exercise it deterministically.
+     */
+    async checkDoomLoopForResponse(response) {
+        if (!this.doomLoopMonitor) {
+            return;
+        }
+        let verdict;
+        try {
+            verdict = await this.doomLoopMonitor.recordAssistantText(extractTextFromResponse(response));
+        }
+        catch (error) {
+            console.warn('[DoomLoop] text checkpoint failed; skipping for this response:', error);
+            verdict = undefined;
+        }
+        if (verdict) {
+            const action = await this.applyDoomLoopVerdict(verdict);
+            this.applyDoomLoopSideEffects(action, verdict);
+        }
+        // Server-tool repetition. The response's server-tool output items echo
+        // their call identity (action/query fields, item type as the tool name).
+        for (const item of response.output) {
+            if (!hasTypeProperty(item) || !isServerToolResultItem(item)) {
+                continue;
+            }
+            const identity = extractServerToolIdentity(item);
+            if (identity === null) {
+                continue;
+            }
+            await this.enqueueDoomLoopEvaluation({
+                toolName: `server:${item.type}`,
+                keyMaterial: identity,
+                fallbackKeyMaterial: null,
+                allowBlock: false,
+                detector: 'server-tool-fingerprint',
+            });
+        }
+    }
+    /**
+     * Queue steer guidance, deduplicating identical messages (one verdict can
+     * repeat across calls in a round; the model needs the guidance once).
+     */
+    queueDoomLoopSteer(message) {
+        if (!this.pendingDoomLoopSteer.includes(message)) {
+            this.pendingDoomLoopSteer.push(message);
+        }
+    }
+    /**
+     * Inject any queued doom-loop steer messages as a user message before the
+     * next model turn. Reuses the Stop-hook appendPrompt injection path, so
+     * state/messages advance observably. Called in-loop before each follow-up
+     * request AND before every pause-persist, so guidance queued right before
+     * a pause lands in the persisted conversation instead of being dropped.
+     */
+    async flushDoomLoopSteer() {
+        if (this.pendingDoomLoopSteer.length === 0) {
+            return;
+        }
+        const prompt = this.pendingDoomLoopSteer.join('\n');
+        this.pendingDoomLoopSteer = [];
+        await this.injectAppendPromptMessage(prompt);
+    }
+    /**
+     * Halt the run for an armed doom-loop stop verdict, keeping the persisted
+     * history well-formed: every executable `function_call` in the current
+     * response that has no output yet gets a synthesized halt-error output
+     * (persisted via the normal tool-result path), so a stateful resume never
+     * sends a dangling `function_call` (providers reject those with a 400).
+     *
+     * Used by every stop site: the pre-round break, the post-round break, the
+     * no-tools early return, the allow-final-response gate, and the approval-
+     * resume gate.
+     *
+     * @param resolvedCallIds - call ids that already have outputs this round.
+     */
+    async sealDoomLoopStop(currentResponse, resolvedCallIds) {
+        const verdict = this.doomLoopStop;
+        const toolCalls = extractToolCallsFromResponse(currentResponse);
+        const unresolved = toolCalls.filter((tc) => !resolvedCallIds?.has(tc.id));
+        if (unresolved.length > 0) {
+            const haltMessage = verdict
+                ? `Run halted by doom-loop detection: ${verdict.message}`
+                : 'Run halted by doom-loop detection.';
+            const haltOutputs = unresolved.map((tc) => ({
+                type: 'function_call_output',
+                id: `output_${tc.id}`,
+                callId: tc.id,
+                output: JSON.stringify({
+                    error: haltMessage,
+                }),
+            }));
+            await this.saveToolResultsToState(haltOutputs);
+        }
+    }
     /**
      * Build the per-emit context for lifecycle hook emits. Threads this run's
      * session identity into `context.sessionId` on every emit, so a
@@ -809,6 +1637,40 @@ export class ModelResult {
             sessionId: this.currentState?.id ?? '',
         };
     }
+    /**
+     * Emit PostToolUse / PostToolUseFailure for an async task at settlement —
+     * the point its final output actually exists. Round-synchronous tools
+     * emit these in runToolWithHooks; async invocations skip that emission
+     * (no output yet) and land here instead. `durationMs` is the task's
+     * start-to-settle wall clock (includes background-pool queue wait, which
+     * counts against the task's own timeout budget). Observation-only — a
+     * throwing hook must not break delivery.
+     */
+    async emitAsyncSettledHooks(task) {
+        if (!this.hooksManager) {
+            return;
+        }
+        try {
+            if (task.status === 'completed') {
+                await this.hooksManager.emit('PostToolUse', {
+                    toolName: task.name,
+                    toolInput: task.input ?? {},
+                    toolOutput: task.result,
+                    durationMs: task.durationMs,
+                }, this.hookEmitContext(task.name));
+            }
+            else {
+                await this.hooksManager.emit('PostToolUseFailure', {
+                    toolName: task.name,
+                    toolInput: task.input ?? {},
+                    error: new Error(task.error ?? `Task ${task.taskId} ${task.status}`),
+                }, this.hookEmitContext(task.name));
+            }
+        }
+        catch (error) {
+            console.warn('[AsyncTools] PostToolUse hook threw during async settlement:', error);
+        }
+    }
     /**
      * Emit SessionEnd exactly once, and only when a matching SessionStart
      * actually succeeded. Safe to call from multiple teardown paths.
@@ -821,28 +1683,41 @@ export class ModelResult {
         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,
-                    }),
-                },
+                totalUsage: this.snapshotSessionUsage(),
             }),
         }, this.hookEmitContext());
     }
+    /**
+     * Materialize the running session aggregate as an immutable
+     * `SessionUsageTotals`. `cost` is present only when at least one response
+     * reported it, matching the hook payload's optionality (a summed cost of
+     * `0` from cost-less responses would read as "free" rather than "unknown").
+     *
+     * Single source of truth for both `SessionEnd.totalUsage` and the public
+     * `getUsage()` accessor, so the two can never drift.
+     */
+    snapshotSessionUsage() {
+        return {
+            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,
+            }),
+        };
+    }
     /**
      * Emit PostModelCall for a completed model response and fold its usage
      * into the session aggregate. One emit per materialized response.
+     *
+     * Accumulation runs unconditionally — before the hooks short-circuit —
+     * because `getUsage()` surfaces these totals to callers who configured no
+     * hooks at all. Only the hook emit is gated on a `HooksManager`.
      */
     async emitPostModelCall(response, startedAt, turnType, turnNumber) {
-        if (!this.hooksManager) {
-            return;
-        }
         const usage = extractModelCallUsage(response.usage);
         this.sessionUsage.modelCalls++;
         if (usage) {
@@ -856,6 +1731,9 @@ export class ModelResult {
                 this.sessionUsage.hasCost = true;
             }
         }
+        if (!this.hooksManager) {
+            return;
+        }
         await this.hooksManager.emit('PostModelCall', {
             sessionId: this.currentState?.id ?? '',
             responseId: response.id,
@@ -927,36 +1805,56 @@ export class ModelResult {
     }
     /**
      * 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.
+     * executeToolsIfNeeded (the normal SessionEnd site). Materializes the
+     * parked model-call telemetry, 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;
-        }
+        // 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.)
+        // Runs even without a HooksManager: this is the only site that folds the
+        // no-tools streaming response into `sessionUsage`, which `getUsage()`
+        // reports to hook-less callers.
+        // 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 {
-            // 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));
+            if (this.pendingModelCall) {
+                if (this.finalResponse) {
+                    await this.emitPendingModelCallOnce(this.finalResponse);
+                }
+                else if (this.reusableStream?.isComplete) {
+                    // Sync backward scan of the retained buffer — not a consumer
+                    // replay, which would cost one microtask hop per buffered event
+                    // on every hook-less streaming teardown.
+                    await this.emitPendingModelCallOnce(extractCompletionFromBuffer(this.reusableStream));
+                }
+                else if (this.reusableStream) {
+                    // Consumers stop at the terminal event (streamTerminationEvents),
+                    // usually before the pump reads the source close that flips
+                    // `isComplete` — with a real network stream the close frame
+                    // arrives after `response.completed`. The terminal event is
+                    // already buffered in that window, so recover it rather than
+                    // dropping the parked telemetry. Stays silent (no emit, no
+                    // throw) when nothing terminal was buffered — e.g. an errored
+                    // mid-flight stream, where no materialized response exists.
+                    const buffered = tryExtractCompletionFromBuffer(this.reusableStream);
+                    if (buffered) {
+                        await this.emitPendingModelCallOnce(buffered);
                     }
                 }
             }
-            catch (telemetryError) {
-                console.warn('[PostModelCall] error during stream teardown:', telemetryError);
-            }
+        }
+        catch (telemetryError) {
+            console.warn('[PostModelCall] error during stream teardown:', telemetryError);
+        }
+        if (!this.hooksManager) {
+            return;
+        }
+        try {
             await this.emitSessionEndOnce(reason);
             await this.hooksManager.drain();
         }
@@ -1090,13 +1988,75 @@ export class ModelResult {
         };
     }
     /**
-     * Execute tools that can auto-execute (don't require approval) in parallel.
+     * Settle an async invocation on the approval/resume path, where results
+     * are accumulated as `UnsentToolResult`s rather than round outputs.
      *
-     * @param toolCalls - The tool calls to execute
-     * @param turnContext - The current turn context
-     * @returns Array of unsent tool results for later submission
+     * - background: degrade to synchronous execution — the approval flow is
+     *   already a discrete resume step, so there is no round to unblock; the
+     *   work is awaited and its (validated) value becomes the unsent result.
+     * - defer: the external task HAS been started by `start()`; record the
+     *   pending placeholder as the unsent result and track the task on
+     *   `pendingAsyncTools` so `resumeToolResults` can deliver the real
+     *   result later as an envelope.
      */
-    async executeAutoApproveTools(toolCalls, turnContext) {
+    async settleAsyncInvocationAsUnsent(tc, invocation) {
+        if (invocation.asyncMode === 'background') {
+            try {
+                const result = await invocation.run();
+                return createUnsentResult(tc.id, String(tc.name), result);
+            }
+            catch (error) {
+                return createRejectedResult(tc.id, String(tc.name), error instanceof Error ? error.message : String(error));
+            }
+        }
+        const registry = this.ensureAsyncToolRegistry();
+        const liveTask = registry.trackDeferred({
+            callId: tc.id,
+            taskId: invocation.taskId,
+            name: String(tc.name),
+            ...(invocation.pollAfterMs !== undefined && {
+                pollAfterMs: invocation.pollAfterMs,
+            }),
+            ...(invocation.expiresAt !== undefined && {
+                expiresAt: invocation.expiresAt,
+            }),
+        });
+        const task = {
+            callId: tc.id,
+            taskId: invocation.taskId,
+            name: String(tc.name),
+            mode: 'defer',
+            status: 'working',
+            startedAt: liveTask.startedAt,
+            ...(invocation.pollAfterMs !== undefined && {
+                pollAfterMs: invocation.pollAfterMs,
+            }),
+            ...(invocation.expiresAt !== undefined && {
+                expiresAt: invocation.expiresAt,
+            }),
+        };
+        if (this.currentState) {
+            this.currentState = updateState(this.currentState, {
+                pendingAsyncTools: [
+                    ...(this.currentState.pendingAsyncTools ?? []).filter((t) => t.callId !== tc.id),
+                    task,
+                ],
+            });
+        }
+        const placeholder = this.buildPendingPlaceholder(tc, invocation.taskId, invocation.ack, invocation.pollAfterMs);
+        return createUnsentResult(tc.id, String(tc.name), typeof placeholder.output === 'string' ? JSON.parse(placeholder.output) : placeholder.output);
+    }
+    /**
+     * Execute tools that can auto-execute (don't require approval) in parallel.
+     *
+     * @param toolCalls - The tool calls to execute
+     * @param turnContext - The current turn context
+     * @returns Array of unsent tool results for later submission
+     */
+    async executeAutoApproveTools(toolCalls, turnContext) {
+        // Auto-approved batch = one doom-loop round: identical parallel calls
+        // count once (see beginDoomLoopRound).
+        await this.beginDoomLoopRound(toolCalls);
         const toolCallPromises = toolCalls.map(async (tc) => {
             const tool = this.options.tools?.find((t) => isClientTool(t) && t.function.name === tc.name);
             if (!tool || !isAutoResolvableTool(tool)) {
@@ -1120,6 +2080,9 @@ export class ModelResult {
                 // HITL tool paused — no unsent result for this call in this round
                 return null;
             }
+            if (isAsyncToolInvocation(result)) {
+                return this.settleAsyncInvocationAsUnsent(tc, result);
+            }
             if (result.error) {
                 return createRejectedResult(tc.id, String(tc.name), result.error.message);
             }
@@ -1250,6 +2213,11 @@ export class ModelResult {
      */
     async persistHitlPause(currentResponse, pausedCalls) {
         this.finalResponse = currentResponse;
+        // Queued steer guidance is NOT injected here: the paused calls are
+        // dangling function_calls, and a user message between a function_call
+        // and its eventual output is invalid history. saveStateSafely persists
+        // the queue (doomLoop.pendingSteer); the resumed run delivers it at its
+        // next safe flush point.
         if (!this.stateAccessor) {
             return;
         }
@@ -1285,6 +2253,7 @@ export class ModelResult {
      */
     async persistClientToolsPause(currentResponse, unresolvedCalls) {
         this.finalResponse = currentResponse;
+        // Steer queue persists via saveStateSafely (see persistHitlPause).
         if (!this.stateAccessor || unresolvedCalls.length === 0) {
             return;
         }
@@ -1294,6 +2263,111 @@ export class ModelResult {
         };
         await this.saveStateSafely(stateUpdates);
     }
+    /**
+     * Persist state when one or more deferred tools (`tool.deferred`) started
+     * durable external tasks this round. The placeholder outputs are already
+     * persisted (the round is fully paired), so — unlike HITL/manual pauses —
+     * nothing dangles; the pause exists purely because the model's next turn
+     * should wait for the real results.
+     *
+     * Mirrors `persistHitlPause` in shape. Status `awaiting_async_tools` is
+     * distinct from `awaiting_client_tools`: the tool DID execute; only its
+     * result is pending. Resumption happens via the deferred tool's
+     * `.resolve()` / `.fail()` / `.cancel()` or `resumeToolResults()`.
+     */
+    async persistAsyncToolPause(currentResponse, deferredTasks) {
+        this.finalResponse = currentResponse;
+        if (!this.stateAccessor) {
+            return;
+        }
+        const existing = (this.currentState?.pendingAsyncTools ?? []).filter((t) => !deferredTasks.some((d) => d.callId === t.callId));
+        await this.saveStateSafely({
+            pendingAsyncTools: [
+                ...existing,
+                ...deferredTasks,
+            ],
+            status: 'awaiting_async_tools',
+        });
+    }
+    /**
+     * Harvest background tasks that settled since the last flush and inject
+     * their outcomes into the conversation as `tool_task_result` envelope
+     * messages (user role). Runs at the same safe point as
+     * `flushDoomLoopSteer()` — after a fully-paired round, before the next
+     * request — because injecting between a dangling `function_call` and its
+     * future output would be invalid history.
+     *
+     * A delivery is forward progress: the text-repetition streak is reset so a
+     * model saying "still waiting…" between deliveries is not condemned.
+     */
+    async flushAsyncToolDeliveries() {
+        const registry = this.asyncToolRegistry;
+        if (!registry) {
+            return false;
+        }
+        const settled = registry.takeSettled();
+        if (settled.length === 0) {
+            return false;
+        }
+        const envelopes = [];
+        for (const task of settled) {
+            this.broadcastAsyncSettled(task, 'injected');
+            // Emit the canonical tool.result event with the FINAL value so
+            // consumers watching only tool.result see real results exactly once.
+            if (task.status === 'completed') {
+                this.broadcastToolResult(task.callId, this.toolSourceByName(task.name), task.result);
+            }
+            // PostToolUse/PostToolUseFailure fire at SETTLEMENT for async tools —
+            // the observation-only audit surface (secret scanning, output review)
+            // must cover long-running results, which are exactly the ones that
+            // arrive from external processes.
+            await this.emitAsyncSettledHooks(task);
+            envelopes.push(JSON.stringify({
+                type: 'tool_task_result',
+                tool: task.name,
+                taskId: task.taskId,
+                callId: task.callId,
+                status: task.status,
+                ...(task.result !== undefined && {
+                    result: task.result,
+                }),
+                ...(task.error !== undefined && {
+                    error: task.error,
+                }),
+            }));
+            // Record settlement for the at-most-once guard. The pending entry is
+            // KEPT with its terminal status (not removed) — same policy as
+            // resumeToolResults — so a late external resolution by taskId OR
+            // callId resolves to ToolTaskAlreadySettledError, never "not found".
+            if (this.currentState) {
+                const terminalStatus = task.status === 'completed' || task.status === 'cancelled' ? task.status : 'failed';
+                this.currentState = updateState(this.currentState, {
+                    settledAsyncCallIds: [
+                        ...(this.currentState.settledAsyncCallIds ?? []),
+                        task.callId,
+                    ],
+                    ...(this.currentState.pendingAsyncTools !== undefined && {
+                        pendingAsyncTools: this.currentState.pendingAsyncTools.map((t) => t.callId === task.callId
+                            ? {
+                                ...t,
+                                status: terminalStatus,
+                            }
+                            : t),
+                    }),
+                });
+            }
+        }
+        // Instruction boundary: the injected message rides the user role (the
+        // only channel that can deliver a late result without a duplicate
+        // function_call_output), but its content is tool output — mark it so
+        // attacker-influenced result text does not read as user instructions.
+        await this.injectAppendPromptMessage(`${TASK_RESULT_BOUNDARY}\n${envelopes.join('\n')}`);
+        // Delivery is observable forward progress — clear the text streak so
+        // legitimate "waiting" phrasing between deliveries can't accumulate
+        // into a doom-loop stop.
+        this.doomLoopMonitor?.resetTextStreak();
+        return true;
+    }
     /**
      * Compute the `output` payload sent to the model for a successfully
      * settled tool execution. Routes through `toModelOutput` when the tool
@@ -1346,6 +2420,19 @@ export class ModelResult {
      * outcome consumed by `executeToolRound`'s aggregation loop.
      */
     async executeSingleToolCall(toolCall, turnContext) {
+        // Universal task-tool dispatch: ONE static tool ("task") handles every
+        // check/steer/result/cancel interaction with running tasks, addressed
+        // by taskId — the wire surface stays constant regardless of how many
+        // async tools are registered, while the handling stays tool-resident
+        // (the owning tool's `check` config). Engine-intercepted: bypasses
+        // gates, deadlines, and Pre/PostToolUse hooks (engine bookkeeping, not
+        // user work) and never reaches the doom-loop checkpoint. A
+        // PermissionRequest denial recorded for the call IS honored — cancel
+        // is destructive and steer reshapes a running task, so a policy layer
+        // that vetoed the call wins over the interception.
+        if (toolCall.name === TASK_TOOL_NAME && this.taskToolActive()) {
+            return this.consumeHookDenial(toolCall.id) ?? this.answerTaskToolCall(toolCall);
+        }
         const tool = this.options.tools?.find((t) => isClientTool(t) && t.function.name === toolCall.name);
         if (!tool || !isAutoResolvableTool(tool)) {
             return null;
@@ -1353,20 +2440,9 @@ export class ModelResult {
         // 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: 'hook_blocked',
-                output: {
-                    type: 'function_call_output',
-                    id: `output_${toolCall.id}`,
-                    callId: toolCall.id,
-                    output: JSON.stringify({
-                        error: denialReason,
-                    }),
-                },
-            };
+        const hookDenied = this.consumeHookDenial(toolCall.id);
+        if (hookDenied !== null) {
+            return hookDenied;
         }
         const preliminaryResultsForCall = [];
         const hasBroadcaster = this.toolEventBroadcaster || this.turnBroadcaster;
@@ -1377,41 +2453,198 @@ export class ModelResult {
                 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,
+        // Compose the per-call abort signal (run signal + tool/run timeout +
+        // per-call controller) and acquire the concurrency gates in fixed order
+        // (round gate first, then per-tool gate — fixed ordering is what makes
+        // multi-gate acquisition deadlock-free). Gate WAITING happens before the
+        // timeout race below, so queue wait counts against the deadline only
+        // for background tasks (which carry their own timeout in the registry).
+        //
+        // Background lifecycles skip the per-tool gate HERE: their body only
+        // runs later via runBackgroundWork, which acquires that gate for the
+        // body's true duration. Acquiring it on the round path too would let
+        // detached bodies holding all maxConcurrency slots block a later
+        // round's dispatch (thunk creation, no body work) for the full task
+        // duration — while it holds a round-gate slot, head-of-line-blocking
+        // every other call in the round.
+        const { controller, signal, timeoutMs } = this.composeToolSignal(String(toolCall.name), toolCall.id);
+        const isBackgroundLifecycle = isUnifiedTool(tool) && tool.function.lifecycle === 'background';
+        const releaseGates = await acquireAll([
+            this.roundGate ?? undefined,
+            isBackgroundLifecycle ? undefined : this.perToolGate(String(toolCall.name)),
+        ]);
+        try {
+            // 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.
+            //
+            // The whole hooked execution is raced against the tool deadline: on
+            // timeout the round stops waiting (the model gets a `tool_timeout`
+            // error output) and the body's signal is aborted. The abandoned body
+            // keeps running detached; awaiting it would reintroduce the hang
+            // run-cancellation (DEV-658) fixed.
+            // Unified-run affordances. The ToolTask is created later (when the
+            // call escapes the round in handleAsyncInvocation), so the log sink
+            // and inbox registration go through a mutable slot the task binds to
+            // on creation; entries logged before that are buffered.
+            const runBinding = this.createRunBinding(toolCall.id);
+            const executionPromise = this.runToolWithHooks(tool, toolCall, turnContext, onPreliminaryResult, {
+                signal,
+                callId: toolCall.id,
+                ...(this.currentState?.id !== undefined && {
+                    conversationId: this.currentState.id,
+                }),
+                client: this.options.client,
+                runExtras: buildRunExtras(tool, runBinding),
             });
-            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)
+            const executed = await this.raceToolDeadline(executionPromise, String(toolCall.name), timeoutMs, controller);
+            if (executed === 'timeout') {
+                return this.buildToolTimeoutOutcome(toolCall, tool, timeoutMs, preliminaryResultsForCall);
+            }
+            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,
+                };
+            }
+            if (isAsyncToolInvocation(result)) {
+                // Background/deferred: the round's aggregation loop turns this into
+                // a placeholder output (and, for background, tracks the work in the
+                // registry). The per-call controller stays alive with the task.
+                return {
+                    type: 'async',
+                    toolCall: executed.effectiveToolCall,
+                    tool,
+                    invocation: result,
+                    controller,
+                    timeoutMs,
+                    runBinding,
+                    preliminaryResultsForCall,
+                };
+            }
             return {
-                type: 'paused',
-                toolCall,
+                type: 'execution',
+                toolCall: executed.effectiveToolCall,
+                tool,
+                result,
+                preliminaryResultsForCall,
             };
         }
+        finally {
+            releaseGates();
+            // The inflight map only tracks round-synchronous executions; async
+            // background tasks hand their controller to the registry, which owns
+            // teardown from here (cancelTask / abortAll).
+            this.inflightToolControllers.delete(toolCall.id);
+        }
+    }
+    /**
+     * The `tool_timeout` execution outcome for a call whose deadline fired:
+     * the model receives an error output immediately (the abandoned body
+     * keeps running detached).
+     */
+    buildToolTimeoutOutcome(toolCall, tool, timeoutMs, preliminaryResultsForCall) {
+        const message = `Tool "${toolCall.name}" timed out after ${timeoutMs}ms`;
+        this.broadcastToolResult(toolCall.id, isMcpTool(tool) ? 'mcp' : 'client', {
+            error: message,
+        });
         return {
             type: 'execution',
-            toolCall: executed.effectiveToolCall,
+            toolCall,
             tool,
-            result,
+            result: {
+                result: null,
+                error: Object.assign(new Error(message), {
+                    code: 'tool_timeout',
+                }),
+            },
             preliminaryResultsForCall,
         };
     }
+    /**
+     * PermissionRequest-hook denial for a call, as a `hook_blocked` outcome —
+     * or null when the call was not denied. Consumes the entry so a later
+     * round with a reused id is not affected.
+     */
+    consumeHookDenial(callId) {
+        const denialReason = this.hookDeniedCalls.get(callId);
+        if (denialReason === undefined) {
+            return null;
+        }
+        this.hookDeniedCalls.delete(callId);
+        return {
+            type: 'hook_blocked',
+            output: {
+                type: 'function_call_output',
+                id: `output_${callId}`,
+                callId,
+                output: JSON.stringify({
+                    error: denialReason,
+                }),
+            },
+        };
+    }
+    /**
+     * Race a tool execution against its deadline. Returns `'timeout'` when the
+     * deadline fires first — the caller synthesizes the `tool_timeout` output —
+     * and aborts the body's controller so cooperative tools stop working. The
+     * timer is cleared on settle either way.
+     */
+    raceToolDeadline(execution, toolName, timeoutMs, controller) {
+        if (timeoutMs === undefined || timeoutMs <= 0) {
+            return execution;
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                controller.abort(new Error(`Tool "${toolName}" timed out after ${timeoutMs}ms`));
+                resolve('timeout');
+            }, timeoutMs);
+            if (typeof timer === 'object' && 'unref' in timer && typeof timer.unref === 'function') {
+                timer.unref();
+            }
+            execution.then((value) => {
+                clearTimeout(timer);
+                resolve(value);
+            }, (error) => {
+                clearTimeout(timer);
+                reject(error instanceof Error ? error : new Error(String(error)));
+            });
+        });
+    }
     async executeToolRound(toolCalls, turnContext) {
+        // One executed batch = one doom-loop round: identical parallel calls in
+        // this batch count as ONE piece of loop evidence and share a decision.
+        await this.beginDoomLoopRound(toolCalls);
         const toolCallPromises = toolCalls.map((toolCall) => this.executeSingleToolCall(toolCall, turnContext));
         const settledResults = await Promise.allSettled(toolCallPromises);
         const toolResults = [];
         const pausedCalls = [];
+        const deferredTasks = [];
+        // Start ALL async invocations before consuming any outcome: the work
+        // (and its grace window) begins in handleAsyncInvocation, so awaiting
+        // it inside the ordered loop below would serialize N background calls
+        // into (N-1)×graceMs of stagger. Kicked off here in parallel; the
+        // ordered loop awaits the per-call promise, so OUTPUT order stays call
+        // order (prompt-cache stability).
+        const asyncOutcomes = new Map();
+        for (let i = 0; i < settledResults.length; i++) {
+            const settled = settledResults[i];
+            if (settled?.status === 'fulfilled' && settled.value?.type === 'async') {
+                asyncOutcomes.set(i, this.handleAsyncInvocation(settled.value));
+            }
+        }
         for (let i = 0; i < settledResults.length; i++) {
             const settled = settledResults[i];
             const originalToolCall = toolCalls[i];
@@ -1461,29 +2694,601 @@ export class ModelResult {
                 pausedCalls.push(value.toolCall);
                 continue;
             }
-            const toolResult = (value.result.error
-                ? {
-                    error: value.result.error.message,
-                }
-                : value.result.result);
-            this.broadcastToolResult(value.toolCall.id, isMcpTool(value.tool) ? 'mcp' : 'client', toolResult, value.preliminaryResultsForCall.length > 0 ? value.preliminaryResultsForCall : undefined);
-            const outputForModel = await this.computeToolOutputForModel(value);
-            const executedOutput = {
-                type: 'function_call_output',
-                id: `output_${value.toolCall.id}`,
-                callId: value.toolCall.id,
-                output: outputForModel,
+            if (value.type === 'async') {
+                // Background / deferred: the call escapes the round. Its handling
+                // (grace-window race, registry tracking, placeholder synthesis)
+                // was started above in parallel with the round's other async
+                // calls; awaiting here keeps outputs in call order.
+                const asyncOutcome = await (asyncOutcomes.get(i) ?? this.handleAsyncInvocation(value));
+                toolResults.push(asyncOutcome.output);
+                this.turnBroadcaster?.push({
+                    type: 'tool.call_output',
+                    output: asyncOutcome.output,
+                    timestamp: Date.now(),
+                });
+                if (asyncOutcome.deferredTask) {
+                    deferredTasks.push(asyncOutcome.deferredTask);
+                }
+                continue;
+            }
+            const toolResult = (value.result.error
+                ? {
+                    error: value.result.error.message,
+                }
+                : value.result.result);
+            this.broadcastToolResult(value.toolCall.id, isMcpTool(value.tool) ? 'mcp' : 'client', toolResult, value.preliminaryResultsForCall.length > 0 ? value.preliminaryResultsForCall : undefined);
+            const outputForModel = await this.computeToolOutputForModel(value);
+            const executedOutput = {
+                type: 'function_call_output',
+                id: `output_${value.toolCall.id}`,
+                callId: value.toolCall.id,
+                output: outputForModel,
+            };
+            toolResults.push(executedOutput);
+            this.turnBroadcaster?.push({
+                type: 'tool.call_output',
+                output: executedOutput,
+                timestamp: Date.now(),
+            });
+        }
+        return {
+            toolResults,
+            pausedCalls,
+            deferredTasks,
+        };
+    }
+    /**
+     * Handle one async invocation from a round.
+     *
+     * Background: start the work under the background pool, race it against
+     * the grace window — settle in time and the call yields a plain
+     * synchronous output (no async machinery visible); otherwise emit the
+     * pending placeholder and let the registry track the task.
+     *
+     * Deferred: emit the placeholder and report the task for the pause path.
+     */
+    async handleAsyncInvocation(value) {
+        const { toolCall, tool, invocation, controller, runBinding } = value;
+        const registry = this.ensureAsyncToolRegistry();
+        const source = isMcpTool(tool) ? 'mcp' : 'client';
+        const logLimits = isUnifiedTool(tool) ? tool.function.logLimits : undefined;
+        if (invocation.asyncMode === 'defer') {
+            const collision = this.rejectDuplicateTaskId(toolCall, invocation.taskId, source);
+            if (collision) {
+                return collision;
+            }
+            const liveTask = registry.trackDeferred({
+                callId: toolCall.id,
+                taskId: invocation.taskId,
+                name: String(toolCall.name),
+                ...(invocation.expiresAt !== undefined && {
+                    expiresAt: invocation.expiresAt,
+                }),
+                ...(invocation.pollAfterMs !== undefined && {
+                    pollAfterMs: invocation.pollAfterMs,
+                }),
+            });
+            runBinding.bind(liveTask);
+            const task = {
+                callId: toolCall.id,
+                taskId: invocation.taskId,
+                name: String(toolCall.name),
+                mode: 'defer',
+                status: 'working',
+                startedAt: liveTask.startedAt,
+                ...(invocation.pollAfterMs !== undefined && {
+                    pollAfterMs: invocation.pollAfterMs,
+                }),
+                ...(invocation.expiresAt !== undefined && {
+                    expiresAt: invocation.expiresAt,
+                }),
+            };
+            this.broadcastAsyncStarted(toolCall, 'defer', invocation.taskId, invocation.ack);
+            return {
+                output: this.buildPendingPlaceholder(toolCall, invocation.taskId, invocation.ack, invocation.pollAfterMs),
+                deferredTask: task,
+            };
+        }
+        // Background: start the work under the background pool. The pool slot is
+        // held for the duration of the work (queue wait counts against the
+        // task's own timeout tracked by the registry).
+        const taskId = registry.generateTaskId();
+        const liveTask = new ToolTask({
+            taskId,
+            callId: toolCall.id,
+            toolName: String(toolCall.name),
+            mode: isAgentTool(tool) ? 'agent' : 'background',
+            controller,
+            ...(logLimits !== undefined && {
+                limits: logLimits,
+            }),
+            // Carried so PostToolUse/PostToolUseFailure can fire at settlement
+            // with the same payload shape as round-synchronous executions.
+            input: (toolCall.arguments ?? {}),
+        });
+        runBinding.bind(liveTask);
+        // Visible to steering / cancel / snapshots from the start — a large
+        // graceMs must not create a window where the running task cannot be
+        // reached (sendToTask queues into the inbox; cancelTask aborts the
+        // controller, which the grace race observes as an error settlement).
+        registry.register(liveTask);
+        const work = this.runBackgroundWork(String(toolCall.name), invocation.run, controller);
+        // Surface unhandled rejections nowhere — the registry's .then() below
+        // (or the grace race) is the sole consumer.
+        work.catch(() => undefined);
+        // Grace window: work settling in time yields a plain synchronous output.
+        const graceMs = invocation.graceMs;
+        if (graceMs > 0) {
+            // The timer is cleared when the work settles first (same discipline
+            // as raceToolDeadline) — it's unref'd, but a leaked timer is still a
+            // leaked timer.
+            let graceTimer;
+            const settled = await Promise.race([
+                work.then((result) => ({
+                    outcome: 'ok',
+                    result,
+                }), (error) => ({
+                    outcome: 'error',
+                    error,
+                })),
+                new Promise((resolve) => {
+                    graceTimer = setTimeout(() => resolve('pending'), graceMs);
+                    if (typeof graceTimer === 'object' &&
+                        'unref' in graceTimer &&
+                        typeof graceTimer.unref === 'function') {
+                        graceTimer.unref();
+                    }
+                }),
+            ]);
+            if (graceTimer !== undefined) {
+                clearTimeout(graceTimer);
+            }
+            if (settled !== 'pending') {
+                // Settled in-window: behave exactly like a regular tool. The call
+                // yields a synchronous output, so the task leaves the registry —
+                // including any settlement a racing cancelTask queued for it (the
+                // sync output already reports the outcome; an envelope on top
+                // would be a double delivery).
+                registry.untrack(toolCall.id);
+                if (settled.outcome === 'ok') {
+                    this.broadcastToolResult(toolCall.id, source, settled.result);
+                    const outputForModel = await this.computeToolOutputForModel({
+                        toolCall,
+                        tool,
+                        result: {
+                            result: settled.result,
+                        },
+                    });
+                    return {
+                        output: {
+                            type: 'function_call_output',
+                            id: `output_${toolCall.id}`,
+                            callId: toolCall.id,
+                            output: outputForModel,
+                        },
+                    };
+                }
+                const message = settled.error instanceof Error ? settled.error.message : String(settled.error);
+                this.broadcastToolResult(toolCall.id, source, {
+                    error: message,
+                });
+                return {
+                    output: {
+                        type: 'function_call_output',
+                        id: `output_${toolCall.id}`,
+                        callId: toolCall.id,
+                        output: JSON.stringify({
+                            error: message,
+                        }),
+                    },
+                };
+            }
+        }
+        // Outlived the grace window: placeholder now, deliver later. The
+        // registry owns the timeout from here (the per-call deadline raced in
+        // executeSingleToolCall only bounds the ROUND's wait; a background task
+        // gets its full budget).
+        registry.trackBackground(liveTask, work, value.timeoutMs !== undefined
+            ? {
+                timeoutMs: value.timeoutMs,
+            }
+            : undefined);
+        this.broadcastAsyncStarted(toolCall, liveTask.mode, taskId, invocation.ack);
+        return {
+            output: this.buildPendingPlaceholder(toolCall, taskId, invocation.ack),
+        };
+    }
+    /**
+     * Reject a `ctx.defer()` taskId already claimed by ANOTHER pending task.
+     * Task ids are the resolution key (resumeToolResults matches on them), so
+     * a duplicate would make one of the two calls unresolvable — the
+     * conversation would wait forever. Caller-supplied ids
+     * (`ctx.defer(ticket.id)`) carry no uniqueness guarantee; reject the
+     * collision at start time, when the tool can still see it.
+     * @returns the error output for the colliding call, or null when unique.
+     */
+    rejectDuplicateTaskId(toolCall, taskId, source) {
+        const duplicate = this.asyncToolRegistry?.getTask(taskId) ??
+            this.currentState?.pendingAsyncTools?.find((t) => t.taskId === taskId);
+        if (!duplicate || duplicate.callId === toolCall.id) {
+            return null;
+        }
+        const message = `Tool "${toolCall.name}": ctx.defer() taskId "${taskId}" is already in use by another pending task in this conversation (call ${duplicate.callId}). Task ids must be unique per conversation — include a per-call component (e.g. the ticket id plus your callId).`;
+        this.broadcastToolResult(toolCall.id, source, {
+            error: message,
+        });
+        return {
+            output: {
+                type: 'function_call_output',
+                id: `output_${toolCall.id}`,
+                callId: toolCall.id,
+                output: JSON.stringify({
+                    error: message,
+                }),
+            },
+        };
+    }
+    /**
+     * A mutable binding between a tool call's run context and its (created
+     * later) ToolTask. `ctx.log()` entries before the task exists are
+     * buffered; `ctx.onMessage()` registrations are forwarded on bind.
+     */
+    createRunBinding(_callId) {
+        let task = null;
+        const bufferedLogs = [];
+        let pendingHandler = null;
+        let pendingTranscriptSource = null;
+        return {
+            log: (entry) => {
+                if (task) {
+                    task.appendLog(entry, typeof entry === 'string' ? 'text' : 'event');
+                }
+                else {
+                    bufferedLogs.push(entry);
+                }
+            },
+            onMessage: (handler) => {
+                if (task) {
+                    task.onMessage(handler);
+                }
+                else {
+                    pendingHandler = handler;
+                }
+            },
+            setTranscriptSource: (source) => {
+                if (task) {
+                    task.transcriptSource = source;
+                }
+                else {
+                    pendingTranscriptSource = source;
+                }
+            },
+            bind: (bound) => {
+                task = bound;
+                for (const entry of bufferedLogs) {
+                    bound.appendLog(entry, typeof entry === 'string' ? 'text' : 'event');
+                }
+                bufferedLogs.length = 0;
+                if (pendingHandler) {
+                    bound.onMessage(pendingHandler);
+                    pendingHandler = null;
+                }
+                if (pendingTranscriptSource) {
+                    bound.transcriptSource = pendingTranscriptSource;
+                    pendingTranscriptSource = null;
+                }
+            },
+            task: () => task,
+        };
+    }
+    /**
+     * Run a background tool's work under the tool's own concurrency gate AND
+     * the background pool. The round path does not touch the per-tool gate
+     * for background lifecycles (the thunk had not run yet), so the gate is
+     * acquired here for the body's lifetime — `maxConcurrency` bounds
+     * executions of the BODY, wherever they run.
+     *
+     * Acquisition order: per-tool gate FIRST, then the pool. The narrow gate
+     * is where a saturated tool's excess calls queue — queuing them on the
+     * shared pool instead would let 16 waiters on one maxConcurrency:2 tool
+     * hold every global slot while only two bodies run, starving every other
+     * background tool. Order is deadlock-safe: only background bodies take
+     * the per-tool gate (the round path skips it for them), and every body
+     * acquires in this same fixed order.
+     *
+     * Queue wait counts against the task's own timeout (tracked by the
+     * registry); an abort observed before the slots free up short-circuits
+     * without running the body.
+     */
+    async runBackgroundWork(toolName, run, controller) {
+        const gate = this.perToolGate(toolName);
+        const releaseGate = gate ? await gate.acquire() : undefined;
+        const pool = this.backgroundPool;
+        const releasePool = pool ? await pool.acquire() : undefined;
+        try {
+            if (controller.signal.aborted) {
+                throw controller.signal.reason instanceof Error
+                    ? controller.signal.reason
+                    : new Error(String(controller.signal.reason ?? 'aborted'));
+            }
+            return await run();
+        }
+        finally {
+            releasePool?.();
+            releaseGate?.();
+        }
+    }
+    /** Broadcast a `tool.async_started` event on the turn broadcaster. */
+    broadcastAsyncStarted(toolCall, mode, taskId, ack) {
+        this.turnBroadcaster?.push({
+            type: 'tool.async_started',
+            toolCallId: toolCall.id,
+            toolName: String(toolCall.name),
+            taskId,
+            mode,
+            ...(ack !== undefined && {
+                ack,
+            }),
+            timestamp: Date.now(),
+        });
+    }
+    /** Broadcast a `tool.async_settled` event on the turn broadcaster. */
+    broadcastAsyncSettled(settled, delivery) {
+        this.turnBroadcaster?.push({
+            type: 'tool.async_settled',
+            toolCallId: settled.callId,
+            taskId: settled.taskId,
+            status: settled.status,
+            ...(settled.result !== undefined && {
+                result: settled.result,
+            }),
+            ...(settled.error !== undefined && {
+                error: settled.error,
+            }),
+            delivery,
+            timestamp: Date.now(),
+        });
+    }
+    /**
+     * Build the pending placeholder `function_call_output` for an async tool
+     * call. Pairs the `function_call` immediately (providers 400 on unpaired
+     * calls in follow-up history); the real result arrives later as a
+     * `tool_task_result` envelope. The note steers the model: with check-ins
+     * enabled it points at the universal `task` tool; with check-ins
+     * disabled it forbids re-calling entirely.
+     */
+    buildPendingPlaceholder(toolCall, taskId, ack, pollAfterMs) {
+        const checkinsEnabled = this.options.asyncTools?.checkins !== false;
+        const payload = {
+            status: 'pending',
+            taskId,
+            ...(pollAfterMs !== undefined && {
+                pollAfterMs,
+            }),
+            ...(checkinsEnabled && {
+                check: true,
+            }),
+        };
+        const directive = checkinsEnabled
+            ? `The result will be delivered to you automatically when ready. To check progress, steer, or cancel, call the task tool with { "taskId": "${taskId}" }. Keep working on other steps meanwhile.`
+            : 'The result will be delivered to you automatically when ready — do not call this tool again to check on it.';
+        if (typeof ack === 'string') {
+            payload['note'] = `${ack} ${directive}`;
+        }
+        else {
+            if (ack !== undefined && typeof ack === 'object') {
+                Object.assign(payload, ack);
+            }
+            payload['note'] = `Started. ${directive}`;
+        }
+        return {
+            type: 'function_call_output',
+            id: `output_${toolCall.id}`,
+            callId: toolCall.id,
+            output: JSON.stringify(payload),
+        };
+    }
+    /**
+     * True when the built-in task tool is active for this run. Mirrors
+     * `needsTaskTool` exactly: when a user tool claims the reserved name the
+     * built-in is not registered, so calls named "task" must NOT be
+     * intercepted — they belong to the user's tool.
+     */
+    taskToolActive() {
+        if (this.options.asyncTools?.checkins === false) {
+            return false;
+        }
+        const tools = this.options.tools ?? [];
+        if (hasTaskToolNameCollision(tools)) {
+            return false;
+        }
+        return tools.some((t) => isLongRunningTool(t));
+    }
+    /**
+     * Answer a call to the universal `task` tool: resolve the taskId to its
+     * live registry task (or persisted pendingAsyncTools entry, post-restart)
+     * and its OWNING tool, then dispatch by action:
+     *
+     * - `check` (default): the owning tool's `check.execute` when declared
+     *   (custom `params` validated against `check.schema`), else the SDK
+     *   default status / logs / transcript views.
+     * - `steer`: deliver `message` to the run body's inbox.
+     * - `result`: the final result if settled, else the status view.
+     * - `cancel`: cancel the task.
+     */
+    async answerTaskToolCall(toolCall) {
+        const taskTool = buildTaskToolStub();
+        const answer = (result, error) => {
+            if (error === undefined) {
+                this.broadcastToolResult(toolCall.id, 'client', result);
+            }
+            return {
+                type: 'execution',
+                toolCall,
+                tool: taskTool,
+                result: error
+                    ? {
+                        result: null,
+                        error,
+                    }
+                    : {
+                        result,
+                    },
+                preliminaryResultsForCall: [],
+            };
+        };
+        let input;
+        try {
+            input = validateToolInput(TaskToolInputSchema, toolCall.arguments ?? {});
+        }
+        catch (error) {
+            return answer(null, error instanceof Error ? error : new Error(String(error)));
+        }
+        const liveTask = this.asyncToolRegistry?.getTask(input.taskId);
+        const persisted = this.currentState?.pendingAsyncTools?.find((t) => t.taskId === input.taskId);
+        if (!liveTask && !persisted) {
+            return answer({
+                error: 'unknown_task',
+                taskId: input.taskId,
+                hint: 'No task with this id exists in this conversation. It may belong to another conversation, or its record was dropped.',
+            });
+        }
+        try {
+            switch (input.action ?? 'check') {
+                case 'cancel':
+                    return answer(this.taskToolCancel(input, liveTask));
+                case 'steer':
+                    return answer(...this.taskToolSteer(input, liveTask));
+                case 'result': {
+                    const settled = taskToolResultIfSettled(input, liveTask);
+                    if (settled !== null) {
+                        return answer(settled);
+                    }
+                    // Not settled: fall through to the status view.
+                    return answer(await this.taskToolCheck(input, liveTask, persisted));
+                }
+                default:
+                    return answer(await this.taskToolCheck(input, liveTask, persisted));
+            }
+        }
+        catch (error) {
+            return answer(null, error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    /** `task` tool, action=cancel. */
+    taskToolCancel(input, liveTask) {
+        const cancelled = liveTask
+            ? (this.asyncToolRegistry?.cancelTask(input.taskId, input.reason) ?? false)
+            : false;
+        return cancelled
+            ? {
+                taskId: input.taskId,
+                status: 'cancelled',
+            }
+            : {
+                taskId: input.taskId,
+                error: 'not_cancellable',
+                hint: liveTask
+                    ? 'The task has already settled.'
+                    : 'This task is owned by an external system — cancel it there (or via the tool’s .cancel() method).',
             };
-            toolResults.push(executedOutput);
-            this.turnBroadcaster?.push({
-                type: 'tool.call_output',
-                output: executedOutput,
-                timestamp: Date.now(),
-            });
+    }
+    /** `task` tool, action=steer. Returns [result, error?] for `answer`. */
+    taskToolSteer(input, liveTask) {
+        if (typeof input.message !== 'string' || input.message.length === 0) {
+            return [
+                null,
+                new Error("action 'steer' requires a non-empty `message`"),
+            ];
+        }
+        if (!liveTask || liveTask.mode === 'defer') {
+            return [
+                {
+                    taskId: input.taskId,
+                    error: 'not_steerable',
+                    hint: 'This task runs in an external system — steer it there.',
+                },
+            ];
+        }
+        liveTask.send(input.message);
+        return [
+            {
+                taskId: input.taskId,
+                steered: true,
+            },
+        ];
+    }
+    /**
+     * `task` tool, action=check (and the status-view fallback for `result`
+     * on an unsettled task): the owning tool's `check.execute` when
+     * declared, else the SDK default views — live-task-backed when the task
+     * is in this process, persisted-state-backed post-restart.
+     */
+    async taskToolCheck(input, liveTask, persisted) {
+        const owningToolName = liveTask?.toolName ?? persisted?.name ?? '';
+        const owningTool = this.options.tools?.find((t) => isClientTool(t) && t.function.name === owningToolName);
+        const config = owningTool && isUnifiedTool(owningTool) ? owningTool.function.check : undefined;
+        const { schema, execute } = resolveCheckConfig(config);
+        const maxTranscriptChars = this.options.asyncTools?.maxTranscriptChars ?? 20000;
+        // Custom params for the owning tool's handler are validated against
+        // its check.schema when both are present.
+        let customParams = input.params ?? {};
+        if (schema && input.params !== undefined) {
+            customParams = validateToolInput(schema, input.params);
+        }
+        if (liveTask) {
+            const handle = this.buildTaskHandle(liveTask, maxTranscriptChars);
+            const checkTurnContext = {
+                numberOfTurns: this.allToolExecutionRounds.length + 1,
+                toolCallStatus: liveTask.status,
+                accumulatedYieldedEvents: liveTask.accumulatedYieldedEvents,
+                task: handle,
+            };
+            return execute
+                ? await Promise.resolve(execute(customParams, checkTurnContext))
+                : defaultCheckResult({
+                    view: input.view,
+                    tail: input.tail,
+                }, checkTurnContext, {
+                    maxTranscriptChars,
+                });
         }
+        // Cross-process / post-restart: only persisted status survives. A
+        // custom check.execute still runs, with a state-backed context (no
+        // live task handle — `turnContext.task` is absent here). Handlers
+        // written against `task.statusView()` with optional chaining return
+        // undefined in this situation; fall back to the persisted status view
+        // rather than answering the model with nothing.
+        const checkTurnContext = {
+            numberOfTurns: this.allToolExecutionRounds.length + 1,
+            toolCallStatus: persisted.status,
+            accumulatedYieldedEvents: persisted.lastLog
+                ? [
+                    persisted.lastLog.text,
+                ]
+                : [],
+        };
+        const customResult = execute
+            ? await Promise.resolve(execute(customParams, checkTurnContext))
+            : undefined;
+        return (customResult ??
+            persistedTaskCheckResult({
+                view: input.view,
+            }, persisted));
+    }
+    /** Build the narrow ToolTaskHandle façade for check.execute handlers. */
+    buildTaskHandle(task, maxTranscriptChars) {
+        const registry = this.asyncToolRegistry;
         return {
-            toolResults,
-            pausedCalls,
+            taskId: task.taskId,
+            toolName: task.toolName,
+            mode: task.mode,
+            status: () => task.status,
+            statusView: () => task.toStatusView(),
+            tailLogs: (n) => task.tailLogs(n),
+            transcript: (maxChars) => task.renderTranscript(maxChars ?? maxTranscriptChars),
+            send: (message) => task.send(message),
+            cancel: (reason) => registry?.cancelTask(task.taskId, reason) ?? false,
         };
     }
     /**
@@ -1494,7 +3299,7 @@ export class ModelResult {
      */
     async resolveAsyncFunctionsForTurn(turnContext) {
         if (hasAsyncFunctions(this.options.request)) {
-            const resolved = await resolveAsyncFunctions(this.options.request, turnContext);
+            const resolved = await this.resolveRequestForContext(turnContext);
             // Preserve accumulated input from previous turns
             const preservedInput = this.resolvedRequest?.input;
             const preservedStream = this.resolvedRequest?.stream;
@@ -1550,26 +3355,231 @@ export class ModelResult {
         if (!this.resolvedRequest) {
             throw new Error('Request not initialized');
         }
-        // Update resolvedRequest.input with accumulated conversation for next turn
+        // Update resolvedRequest.input with accumulated conversation for next turn.
         this.resolvedRequest = {
             ...this.resolvedRequest,
             input: newInput,
         };
+        // A forced tool choice (`required` or a specific tool) has served its
+        // purpose once a tool round has executed; keeping it on follow-up turns
+        // would forbid the model from ever answering in text, looping it through
+        // tool calls until the step budget runs out (DEV-785). Relax it to `auto`
+        // so the model can either call another tool or synthesize its answer.
+        this.resolvedRequest = this.applyForcedToolChoicePolicy(this.resolvedRequest);
+        // Escalation recovery: one-turn overrides (model swap / forced advisor
+        // consult) applied to THIS dispatch only — `resolvedRequest` above keeps
+        // the configured model/tools, so the next turn reverts automatically.
+        const escalationOverrides = this.takeDoomLoopEscalationOverrides();
         const newRequest = {
             ...this.resolvedRequest,
+            ...(escalationOverrides ?? {}),
             stream: true,
         };
+        this.beginToolChoiceDispatch(newRequest.toolChoice);
         const startedAt = performance.now();
         const newResult = await betaResponsesSend(this.options.client, {
             responsesRequest: newRequest,
-        }, this.options.options);
+        }, this.dispatchRequestOptions());
         if (!newResult.ok) {
             throw newResult.error;
         }
         const response = await this.materializeResponse(newResult.value, turnNumber);
+        this.commitToolChoiceDispatch(responseHasToolCalls(response));
         await this.emitPostModelCall(response, startedAt, 'tool_round', turnNumber);
         return response;
     }
+    /**
+     * Append a response's output items to the accumulated request input,
+     * exactly as `makeFollowupRequest` does before adding tool results. Used
+     * by the end-of-run drain, where envelope messages must land AFTER the
+     * final assistant output in the request.
+     */
+    accumulateResponseIntoInput(response) {
+        if (!this.resolvedRequest) {
+            return;
+        }
+        const originalInput = this.resolvedRequest.input;
+        const normalizedOriginalInput = Array.isArray(originalInput)
+            ? originalInput
+            : originalInput
+                ? [
+                    {
+                        role: 'user',
+                        content: originalInput,
+                    },
+                ]
+                : [];
+        this.resolvedRequest = {
+            ...this.resolvedRequest,
+            input: [
+                ...normalizedOriginalInput,
+                ...(Array.isArray(response.output)
+                    ? response.output
+                    : [
+                        response.output,
+                    ]),
+            ],
+        };
+    }
+    /**
+     * End-of-run handling for async background tasks still in flight (or
+     * settled but unharvested) when the loop is about to finalize.
+     *
+     * - `'drain'` (default): wait for tasks (bounded by `drainTimeoutMs`),
+     *   inject their results, and give the model up to `maxDrainTurns` extra
+     *   `toolChoice: 'none'` turns so the final answer incorporates them.
+     * - `'detach'`: return immediately; still-working tasks are marked
+     *   `orphaned` on persisted state and their eventual results are dropped.
+     * - `'cancel'`: abort in-flight tasks and finish.
+     *
+     * @returns the (possibly replaced) final response.
+     */
+    async handleRunEndAsyncTasks(currentResponse) {
+        const registry = this.asyncToolRegistry;
+        if (!registry || (!registry.hasInFlight() && !registry.hasUnharvestedSettled())) {
+            return currentResponse;
+        }
+        const config = this.options.asyncTools;
+        const mode = config?.onRunEnd ?? 'drain';
+        if (mode === 'cancel') {
+            registry.abortAll('Run ended (onRunEnd: cancel)');
+            await this.dropSettledTasks();
+            return currentResponse;
+        }
+        if (mode === 'detach') {
+            await this.detachWorkingTasks();
+            return currentResponse;
+        }
+        // 'drain': deliver late results and let the model incorporate them.
+        // Drain turns use the retry path (toolChoice forced to 'none' when tools
+        // are present) so a drain turn cannot open a fresh tool round — it
+        // exists purely to fold the delivered results into the final answer.
+        // ONE deadline spans the whole drain phase: drainTimeoutMs bounds total
+        // WAITING (documented contract), not per-turn waiting — maxDrainTurns
+        // bounds the extra model turns, not the wait.
+        const drainTimeoutMs = config?.drainTimeoutMs ?? 30000;
+        const maxDrainTurns = config?.maxDrainTurns ?? 2;
+        const drainDeadline = Date.now() + drainTimeoutMs;
+        let response = currentResponse;
+        for (let drainTurn = 0; drainTurn < maxDrainTurns; drainTurn++) {
+            if (!registry.hasUnharvestedSettled() && registry.hasInFlight()) {
+                const remaining = drainDeadline - Date.now();
+                if (remaining <= 0) {
+                    break;
+                }
+                await registry.drain(remaining);
+            }
+            // Accumulate the current final output BEFORE injecting so the
+            // envelope lands after the assistant's last message in the request.
+            this.accumulateResponseIntoInput(response);
+            // Queued steering (queueUserMessage / sendToTask) flushes here too —
+            // a drain turn is a model dispatch, and guidance queued while the
+            // last tool round was already finishing would otherwise be dropped.
+            await this.flushDoomLoopSteer();
+            const delivered = await this.flushAsyncToolDeliveries();
+            if (!delivered) {
+                // Drain timed out with nothing new settled — stop waiting.
+                break;
+            }
+            const turnNumber = this.allToolExecutionRounds.length + 1 + drainTurn;
+            response = await this.retryCurrentRequest(turnNumber);
+            await this.saveResponseToState(response);
+            if (!registry.hasInFlight() && !registry.hasUnharvestedSettled()) {
+                break;
+            }
+        }
+        // Drain budget exhausted with work still in flight: cut it loose.
+        if (registry.hasInFlight()) {
+            registry.abortAll('Async tool drain budget exhausted at run end');
+            await this.dropSettledTasks();
+        }
+        return response;
+    }
+    /**
+     * Broadcast every unharvested settlement as dropped (no in-run delivery),
+     * mirror the terminal status onto persisted `pendingAsyncTools`, and
+     * append a terminal `tool_task_result` envelope to persisted history.
+     *
+     * The status mirror prevents a stuck resume: an entry persisted as
+     * `working` for a task that only ever settles in-memory (abortAll at
+     * drain exhaustion / run cancel) would pin a later cross-process resume
+     * to `awaiting_async_tools` forever. The envelope keeps the pending
+     * placeholder's "the result will be delivered" promise honest for
+     * PERSISTED conversations: the run is over (no more model dispatch), but
+     * the terminal outcome rides along on the next `callModel({ state })`
+     * instead of vanishing.
+     */
+    async dropSettledTasks() {
+        const registry = this.asyncToolRegistry;
+        if (!registry) {
+            return;
+        }
+        const settled = registry.takeSettled();
+        for (const task of settled) {
+            this.broadcastAsyncSettled(task, 'dropped');
+        }
+        if (settled.length === 0 || !this.stateAccessor || !this.currentState) {
+            return;
+        }
+        const terminalByCallId = new Map(settled.map((t) => [
+            t.callId,
+            t.status === 'completed' || t.status === 'cancelled' ? t.status : 'failed',
+        ]));
+        const envelopes = settled.map((t) => JSON.stringify({
+            type: 'tool_task_result',
+            tool: t.name,
+            taskId: t.taskId,
+            callId: t.callId,
+            status: t.status,
+            ...(t.result !== undefined && {
+                result: t.result,
+            }),
+            ...(t.error !== undefined && {
+                error: t.error,
+            }),
+        }));
+        await this.saveStateSafely({
+            messages: appendToMessages(this.currentState.messages, [
+                {
+                    role: 'user',
+                    content: `${TASK_RESULT_BOUNDARY}\n${envelopes.join('\n')}`,
+                },
+            ]),
+            ...(this.currentState.pendingAsyncTools?.length && {
+                pendingAsyncTools: this.currentState.pendingAsyncTools.map((entry) => {
+                    const terminal = terminalByCallId.get(entry.callId);
+                    return terminal !== undefined
+                        ? {
+                            ...entry,
+                            status: terminal,
+                        }
+                        : entry;
+                }),
+            }),
+        });
+    }
+    /**
+     * `onRunEnd: 'detach'`: mark still-working tasks orphaned on persisted
+     * state (their eventual results are dropped) and drop unharvested
+     * settlements.
+     */
+    async detachWorkingTasks() {
+        const registry = this.asyncToolRegistry;
+        if (!registry) {
+            return;
+        }
+        const orphaned = registry.markWorkingAsOrphaned();
+        await this.dropSettledTasks();
+        if (orphaned.length > 0 && this.stateAccessor && this.currentState) {
+            const existing = (this.currentState.pendingAsyncTools ?? []).filter((t) => !orphaned.some((o) => o.callId === t.callId));
+            await this.saveStateSafely({
+                pendingAsyncTools: [
+                    ...existing,
+                    ...orphaned,
+                ],
+            });
+        }
+    }
     /**
      * 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
@@ -1632,7 +3642,7 @@ export class ModelResult {
         const startedAt = performance.now();
         const result = await betaResponsesSend(this.options.client, {
             responsesRequest: finalRequest,
-        }, this.options.options);
+        }, this.dispatchRequestOptions());
         if (!result.ok) {
             throw result.error;
         }
@@ -1643,19 +3653,40 @@ export class ModelResult {
     /**
      * Validate the final response has required fields.
      *
+     * Message prefixes (`Invalid final response: missing required fields`,
+     * `Invalid final response: empty or invalid output`) are load-bearing —
+     * callers and tests match on them. Detail is appended after an em dash;
+     * never reword the prefixes.
+     *
+     * The detail exists because the bare "empty or invalid output" message was
+     * routinely misread as "the model returned a tool call and validation
+     * rejected it" (issue #45). It does not: this is a pure array-length check,
+     * so a `function_call`-only output passes. Naming the actual defect —
+     * empty array vs. wrong type — stops that misdiagnosis at the error string.
+     *
      * @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, allowEmptyOutput = false) {
         if (!response?.id || !response?.output) {
-            throw new Error('Invalid final response: missing required fields');
+            const missing = [];
+            if (!response?.id) {
+                missing.push('id');
+            }
+            if (!response?.output) {
+                missing.push('output');
+            }
+            throw new Error(`Invalid final response: missing required fields: ${missing.join(', ')}`);
         }
         if (!Array.isArray(response.output) || response.output.length === 0) {
             if (allowEmptyOutput) {
                 return;
             }
-            throw new Error('Invalid final response: empty or invalid output');
+            const detail = Array.isArray(response.output)
+                ? `output array is empty (length 0) for response "${response.id}". The model returned no output items. This can happen when the provider returns an empty final turn; see the strictFinalResponse/allowFinalResponse options`
+                : `output is not an array (got ${describeNonRecord(response.output)}) for response "${response.id}"`;
+            throw new Error(`Invalid final response: empty or invalid output — ${detail}`);
         }
     }
     /**
@@ -1684,7 +3715,7 @@ export class ModelResult {
         const startedAt = performance.now();
         const newResult = await betaResponsesSend(this.options.client, {
             responsesRequest: newRequest,
-        }, this.options.options);
+        }, this.dispatchRequestOptions());
         if (!newResult.ok) {
             throw newResult.error;
         }
@@ -1692,6 +3723,47 @@ export class ModelResult {
         await this.emitPostModelCall(response, startedAt, 'retry', turnNumber);
         return response;
     }
+    /**
+     * Build the RequestOptions for one API dispatch, composing the run-level
+     * cancellation signal (`options.signal`) with the caller's RequestOptions.
+     *
+     * The SDK only auto-wires `timeoutMs` into an abort signal when NO signal
+     * is present on the options — a supplied signal silently disables the
+     * timeout. Composing here keeps both: each request is bounded by
+     * whichever of {run signal, caller signal, per-request timeout} fires
+     * first. MUST be called once per dispatch — `AbortSignal.timeout()`
+     * starts counting at creation, so a cached composite would burn its
+     * budget across turns instead of per request.
+     *
+     * Also the per-request fail-fast checkpoint: an already-aborted run
+     * signal throws its abort reason here, before any network I/O.
+     */
+    dispatchRequestOptions() {
+        const base = this.options.options;
+        const runSignal = this.options.signal;
+        if (!runSignal) {
+            return base;
+        }
+        runSignal.throwIfAborted();
+        const signals = [
+            runSignal,
+        ];
+        const callerSignal = base?.signal ?? base?.fetchOptions?.signal;
+        if (callerSignal) {
+            signals.push(callerSignal);
+        }
+        // Re-create the timeout the SDK would have wired had no signal been
+        // present. Per-request option wins over the client-level default,
+        // mirroring betaResponsesSend's own precedence.
+        const timeoutMs = base?.timeoutMs ?? this.options.client._options.timeoutMs;
+        if (typeof timeoutMs === 'number' && timeoutMs > 0) {
+            signals.push(AbortSignal.timeout(timeoutMs));
+        }
+        return {
+            ...base,
+            signal: signals.length === 1 ? runSignal : AbortSignal.any(signals),
+        };
+    }
     /**
      * Resolve async functions in the request for a given turn context.
      * Extracts non-function fields and resolves any async parameter functions.
@@ -1701,15 +3773,106 @@ export class ModelResult {
      */
     async resolveRequestForContext(context) {
         if (hasAsyncFunctions(this.options.request)) {
-            return resolveAsyncFunctions(this.options.request, context);
+            const resolved = await resolveAsyncFunctions(this.options.request, context);
+            return this.applyResolvedForcedToolChoicePolicy(resolved);
         }
         // 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;
+        const { stopWhen: _, state: _s, requireApproval: _r, approveToolCalls: _a, rejectToolCalls: _rj, context: _c, onTurnStart: _ots, onTurnEnd: _ote, allowFinalResponse: _afr, strictFinalResponse: _sfr, hooks: _h, doomLoop: _dl, signal: _sig, toolTimeoutMs: _ttm, toolConcurrency: _tc, asyncTools: _at, ...rest } = this.options.request;
+        return this.applyResolvedForcedToolChoicePolicy(rest);
+    }
+    /**
+     * Record the freshly-resolved caller choice before deriving its wire value.
+     * An unforced turn clears the consumed key, re-arming the same forced value
+     * if it appears again later. A different forced key re-arms immediately.
+     */
+    applyResolvedForcedToolChoicePolicy(request) {
+        this.configuredToolChoice = request.toolChoice;
+        this.configuredForcedToolChoiceKey = forcedToolChoiceKey(request.toolChoice);
+        if (this.configuredForcedToolChoiceKey === null) {
+            this.preparedToolChoiceCommit =
+                this.activeConsumedForcedToolChoiceKey === null
+                    ? null
+                    : {
+                        type: 'clear',
+                    };
+        }
+        else {
+            this.preparedToolChoiceCommit =
+                this.configuredForcedToolChoiceKey === this.activeConsumedForcedToolChoiceKey
+                    ? null
+                    : {
+                        type: 'consume',
+                        key: this.configuredForcedToolChoiceKey,
+                    };
+        }
+        return this.applyForcedToolChoicePolicy(request);
+    }
+    /**
+     * Derive the caller-configured tool choice for the active logical run.
+     * Engine-owned one-turn overrides (`none` for finalization, or a pinned
+     * doom-loop advisor) are applied after this helper and therefore still win.
+     */
+    applyForcedToolChoicePolicy(request) {
+        const toolChoice = this.configuredForcedToolChoiceKey !== null &&
+            this.configuredForcedToolChoiceKey === this.activeConsumedForcedToolChoiceKey
+            ? relaxForcedToolChoice(this.configuredToolChoice)
+            : this.configuredToolChoice;
+        this.preparedEffectiveToolChoice = toolChoice;
+        return toolChoice === request.toolChoice
+            ? request
+            : {
+                ...request,
+                toolChoice,
+            };
+    }
+    /**
+     * Bind the prepared caller-policy transition to the actual wire request.
+     * Engine-owned overrides (for example a forced advisor consult) deliberately
+     * produce a different semantic key and therefore cannot commit caller state.
+     */
+    beginToolChoiceDispatch(actualToolChoice) {
+        this.dispatchedCallerToolChoice =
+            canonicalizeKeyMaterial(actualToolChoice ?? null) ===
+                canonicalizeKeyMaterial(this.preparedEffectiveToolChoice ?? null);
+        this.dispatchedToolChoiceCommit = this.dispatchedCallerToolChoice
+            ? this.preparedToolChoiceCommit
+            : null;
+    }
+    /**
+     * Commit only after the prepared caller choice reached the wire and a
+     * response was materialized. A pause before dispatch leaves persisted state
+     * untouched; a forced choice is consumed only when that response called a
+     * tool.
+     */
+    commitToolChoiceDispatch(hasToolCalls) {
+        const callerChoiceDispatched = this.dispatchedCallerToolChoice;
+        const commit = this.dispatchedToolChoiceCommit;
+        this.dispatchedCallerToolChoice = false;
+        this.dispatchedToolChoiceCommit = null;
+        if (!callerChoiceDispatched) {
+            return;
+        }
+        this.preparedToolChoiceCommit = null;
+        if (commit?.type === 'clear') {
+            this.activeConsumedForcedToolChoiceKey = null;
+        }
+        else if (commit?.type === 'consume' && hasToolCalls) {
+            this.activeConsumedForcedToolChoiceKey = commit.key;
+        }
+    }
+    /** Clear all runtime and persisted policy state for a terminal run exit. */
+    resetForcedToolChoicePolicy() {
+        this.activeConsumedForcedToolChoiceKey = null;
+        this.configuredForcedToolChoiceKey = null;
+        this.configuredToolChoice = undefined;
+        this.preparedEffectiveToolChoice = undefined;
+        this.preparedToolChoiceCommit = null;
+        this.dispatchedToolChoiceCommit = null;
+        this.dispatchedCallerToolChoice = false;
     }
     /**
      * Apply `onResponseReceived` hooks to the freshly-supplied input items
@@ -1791,6 +3954,72 @@ export class ModelResult {
         if (updates) {
             this.currentState = updateState(this.currentState, updates);
         }
+        // Persist only the consumed semantic key, never the callback or a copied
+        // effective toolChoice. Dynamic values are re-resolved on every turn.
+        if (this.activeConsumedForcedToolChoiceKey !== null) {
+            this.currentState = {
+                ...this.currentState,
+                consumedForcedToolChoiceKey: this.activeConsumedForcedToolChoiceKey,
+            };
+        }
+        else if (this.currentState.consumedForcedToolChoiceKey !== undefined) {
+            const nextState = {
+                ...this.currentState,
+            };
+            delete nextState.consumedForcedToolChoiceKey;
+            this.currentState = nextState;
+        }
+        // Piggyback the doom-loop detector snapshot on every persist so loop
+        // memory survives serialize → resume (a resumed doom loop is still a
+        // doom loop — provided the resuming call passes `doomLoop` again).
+        // Plain bounded JSON; absent when detection is off. The engine-owned
+        // fields ride along: `stopVerdict` keeps a condemned run condemned
+        // across decision-only resumes; `pendingSteer` carries queued guidance
+        // that had no flush opportunity before a pause.
+        if (this.doomLoopMonitor) {
+            const doomLoopState = {
+                ...this.doomLoopMonitor.getState(),
+                ...(this.doomLoopStop !== null && {
+                    stopVerdict: this.doomLoopStop,
+                }),
+                ...(this.pendingDoomLoopSteer.length > 0 && {
+                    pendingSteer: [
+                        ...this.pendingDoomLoopSteer,
+                    ],
+                }),
+            };
+            this.currentState = {
+                ...this.currentState,
+                doomLoop: doomLoopState,
+            };
+        }
+        // Mirror each live task's lastLog onto its persisted pendingAsyncTools
+        // entry (bounded ~200 chars) — the one piece of progress that survives
+        // a restart, surfaced by post-restart check calls. Debounced naturally:
+        // this runs only when state is being saved anyway, never per log entry.
+        if (this.asyncToolRegistry && this.currentState.pendingAsyncTools?.length) {
+            const registry = this.asyncToolRegistry;
+            this.currentState = {
+                ...this.currentState,
+                pendingAsyncTools: this.currentState.pendingAsyncTools.map((entry) => {
+                    const live = registry.findByCallId(entry.callId);
+                    const lastLog = live?.lastLog;
+                    if (!lastLog) {
+                        return entry;
+                    }
+                    const text = typeof lastLog.data === 'string'
+                        ? lastLog.data
+                        : (JSON.stringify(lastLog.data) ?? String(lastLog.data));
+                    return {
+                        ...entry,
+                        lastLog: {
+                            at: lastLog.at,
+                            text: text.length > 200 ? `${text.slice(0, 200)}…` : text,
+                        },
+                    };
+                }),
+            };
+        }
         try {
             await this.stateAccessor.save(this.currentState);
         }
@@ -1831,6 +4060,34 @@ export class ModelResult {
                 const loadedState = await this.stateAccessor.load();
                 if (loadedState) {
                     this.currentState = loadedState;
+                    this.activeConsumedForcedToolChoiceKey = loadedState.consumedForcedToolChoiceKey ?? null;
+                    // Rehydrate doom-loop state so a resumed run continues where it
+                    // left off: streak counters always; the queued steer guidance;
+                    // and the stop verdict under the condemnation rule below.
+                    if (this.doomLoopMonitor && loadedState.doomLoop !== undefined) {
+                        this.doomLoopMonitor.restore(loadedState.doomLoop);
+                        const persisted = loadedState.doomLoop;
+                        if (Array.isArray(persisted.pendingSteer)) {
+                            for (const message of persisted.pendingSteer) {
+                                if (typeof message === 'string') {
+                                    this.queueDoomLoopSteer(message);
+                                }
+                            }
+                        }
+                        // Condemnation rule: a doom-stopped conversation STAYS stopped
+                        // across decision-only resumes (approveToolCalls /
+                        // rejectToolCalls — approving a call is not new conversation).
+                        // A fresh conversational turn (a plain callModel on the same
+                        // state, no decisions) clears the verdict: operator input is
+                        // new information. Streaks are kept either way, so renewed
+                        // repetition re-condemns quickly.
+                        if (persisted.stopVerdict) {
+                            const isDecisionResume = this.approvedToolCalls.length > 0 || this.rejectedToolCalls.length > 0;
+                            if (isDecisionResume) {
+                                this.doomLoopStop = persisted.stopVerdict;
+                            }
+                        }
+                    }
                     // Check if we're resuming from awaiting_approval or awaiting_hitl
                     // with decisions. `awaiting_hitl` reuses `processApprovalDecisions`
                     // because the resume mechanism is identical — the caller supplies
@@ -1871,13 +4128,18 @@ export class ModelResult {
                     }
                     // 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.
+                    // that request failed. `awaiting_async_tools` resumes the same way:
+                    // the pending-task bookkeeping was already updated by
+                    // resumeToolResults (or remains pending for tasks not yet resolved),
+                    // and the placeholder outputs are in history, so a fresh request is
+                    // valid.
                     this.resumingFromClientTools = loadedState.status === 'awaiting_client_tools';
+                    this.resumingFromAsyncTools = loadedState.status === 'awaiting_async_tools';
                 }
                 else {
                     this.currentState = createInitialState();
                 }
-                if (!this.resumingFromClientTools) {
+                if (!this.resumingFromClientTools && !this.resumingFromAsyncTools) {
                     await this.saveStateSafely({
                         status: 'in_progress',
                     });
@@ -2003,9 +4265,10 @@ export class ModelResult {
                 turnNumber: 0,
             };
             // Make the API request
+            this.beginToolChoiceDispatch(request.toolChoice);
             const apiResult = await betaResponsesSend(this.options.client, {
                 responsesRequest: request,
-            }, this.options.options);
+            }, this.dispatchRequestOptions());
             if (!apiResult.ok) {
                 throw apiResult.error;
             }
@@ -2051,6 +4314,16 @@ 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();
+        // The approved batch is one doom-loop round: N approved duplicates of
+        // the same call count once (the sequential loop below still evaluates
+        // in order; restored streaks from the persisted state carry forward).
+        // Declared from the approved calls only — a pending call the user did not
+        // approve is not part of this round.
+        await this.beginDoomLoopRound([
+            ...this.approvedToolCalls,
+        ]
+            .map((callId) => pendingCalls.find((tc) => tc.id === callId))
+            .filter((tc) => tc !== undefined));
         // Process approvals - execute the approved tools. Route through
         // runToolWithHooks so PreToolUse/PostToolUse fire even on this path.
         for (const callId of this.approvedToolCalls) {
@@ -2083,6 +4356,10 @@ export class ModelResult {
                 hitlPausedIds.add(callId);
                 continue;
             }
+            if (isAsyncToolInvocation(result)) {
+                unsentResults.push(await this.settleAsyncInvocationAsUnsent(toolCall, result));
+                continue;
+            }
             if (result.error) {
                 unsentResults.push(createRejectedResult(callId, String(toolCall.name), result.error.message));
             }
@@ -2131,6 +4408,11 @@ export class ModelResult {
         if (unsentResults.length > 0) {
             stateUpdates.unsentToolResults = unsentResults;
         }
+        if (nextStatus === 'in_progress' && this.doomLoopStop) {
+            // This approval continuation is terminal: no model request follows, so
+            // a later fresh run must not inherit its consumed caller choice.
+            this.resetForcedToolChoicePolicy();
+        }
         await this.saveStateSafely(stateUpdates);
         // Clear optional properties if they should be empty
         const propsToClear = [];
@@ -2144,10 +4426,22 @@ export class ModelResult {
             this.clearOptionalStateProperties(propsToClear);
             await this.saveStateSafely();
         }
-        // If we are paused (for approval or for HITL), stop here
+        // If we are paused (for approval or for HITL), stop here. Queued steer
+        // guidance rides doomLoop.pendingSteer in the state persisted above;
+        // the resumed run delivers it at its next safe flush point (injecting a
+        // user message between dangling function_calls and their future
+        // outputs would be invalid history).
         if (nextStatus !== 'in_progress') {
             return;
         }
+        // A doom-stop armed while executing the approved calls (the restored
+        // streak crossed the stop rung): halt WITHOUT the unsent-results model
+        // request. The executed outputs are already persisted as unsent; the
+        // condemned call got a blocked output. Session teardown reports the
+        // doom reason via the armed verdict (see executeToolsIfNeeded).
+        if (this.doomLoopStop) {
+            return;
+        }
         // Otherwise, continue with tool execution using unsent results
         await this.continueWithUnsentResults();
     }
@@ -2203,9 +4497,10 @@ export class ModelResult {
             turnNumber: turnContext.numberOfTurns,
         };
         // Make the API request
+        this.beginToolChoiceDispatch(request.toolChoice);
         const apiResult = await betaResponsesSend(this.options.client, {
             responsesRequest: request,
-        }, this.options.options);
+        }, this.dispatchRequestOptions());
         if (!apiResult.ok) {
             throw apiResult.error;
         }
@@ -2247,13 +4542,35 @@ export class ModelResult {
                         this.currentState?.status === 'awaiting_hitl')) {
                     return;
                 }
+                // A doom-stop armed while executing approved calls on resume:
+                // processApprovalDecisions already skipped the unsent-results model
+                // request; the executed outputs are persisted as unsent for a later
+                // (fresh-input) resume. Halt here — like a pause, no stream exists.
+                if (this.isResumingFromApproval && this.doomLoopStop) {
+                    sessionEndReason = 'doom_loop';
+                    this.resetForcedToolChoicePolicy();
+                    await this.saveStateSafely();
+                    return;
+                }
                 // Get initial response
                 let currentResponse = await this.getInitialResponse();
+                // toolChoice constrains model output, so a forced requirement is
+                // satisfied as soon as this turn emits a tool call. Record it before
+                // any approval/HITL/client/async pause can persist the run.
+                const hasToolCalls = responseHasToolCalls(currentResponse);
+                this.commitToolChoiceDispatch(hasToolCalls);
                 // Save initial response to state
                 await this.saveResponseToState(currentResponse);
+                // Doom-loop text checkpoint for the initial response (within-response
+                // token repetition + cross-step streak seed).
+                await this.checkDoomLoopForResponse(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) {
+                    // A text verdict on the initial response may have armed a stop —
+                    // report the run as doom-stopped, not as a normal completion.
+                    if (this.doomLoopStop) {
+                        sessionEndReason = 'doom_loop';
+                    }
                     // No tool work: keep hard throw on empty/invalid final output.
                     this.validateFinalResponse(currentResponse);
                     this.finalResponse = currentResponse;
@@ -2282,11 +4599,27 @@ export class ModelResult {
                 // runStopHook for the cap.
                 let forceResumeCount = 0;
                 while (true) {
+                    // Run-level cancellation: fail the loop at the turn boundary with
+                    // the abort reason. In-flight requests are aborted independently
+                    // by the composed dispatch signal (dispatchRequestOptions); this
+                    // check covers cancellation between requests (during tool
+                    // execution or hook work).
+                    this.options.signal?.throwIfAborted();
                     // Check for external interruption
                     if (await this.checkForInterruption(currentResponse)) {
                         sessionEndReason = 'user';
                         return;
                     }
+                    // A doom-loop 'stop' verdict from the previous response's text
+                    // halts the run before any further spend. Seal first: this break
+                    // fires BEFORE this response's tool calls execute, so they need
+                    // synthesized halt outputs or the persisted history would carry
+                    // dangling function_calls (providers 400 on resume).
+                    if (this.doomLoopStop) {
+                        await this.sealDoomLoopStop(currentResponse);
+                        sessionEndReason = 'doom_loop';
+                        break;
+                    }
                     // Check stop conditions
                     if (await this.shouldStopExecution()) {
                         // Emit the Stop hook -- handlers can force resume or inject a
@@ -2331,7 +4664,7 @@ export class ModelResult {
                     // Resolve async functions for this turn
                     await this.resolveAsyncFunctionsForTurn(turnContext);
                     // Execute tools
-                    const { toolResults, pausedCalls } = await this.executeToolRound(currentToolCalls, turnContext);
+                    const { toolResults, pausedCalls, deferredTasks = [], } = 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.
@@ -2384,6 +4717,15 @@ export class ModelResult {
                         await this.persistHitlPause(currentResponse, pausedCalls);
                         return;
                     }
+                    // Deferred tools started durable external tasks this round: pause.
+                    // Unlike HITL, the round is fully paired (placeholder outputs were
+                    // persisted above), so the resumed conversation history is valid;
+                    // the pause exists so the model's next turn can incorporate the
+                    // real results supplied via .resolve()/resumeToolResults().
+                    if (deferredTasks.length > 0) {
+                        await this.persistAsyncToolPause(currentResponse, deferredTasks);
+                        return;
+                    }
                     // 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
@@ -2403,6 +4745,27 @@ export class ModelResult {
                         await this.persistClientToolsPause(currentResponse, unresolvedToolCalls);
                         return;
                     }
+                    // A doom-loop 'stop' verdict armed during this round halts the run
+                    // before the next model request. Seal defensively: the condemned
+                    // call already got a blocked error output, but a TEXT stop armed
+                    // by a concurrent checkpoint could leave other calls unresolved.
+                    // No final text-coercion request is made: the point of 'stop' is
+                    // to cut spend on a run that is demonstrably not progressing.
+                    if (this.doomLoopStop) {
+                        await this.sealDoomLoopStop(currentResponse, new Set(toolResults.map((r) => r.callId)));
+                        sessionEndReason = 'doom_loop';
+                        break;
+                    }
+                    // Inject any queued doom-loop steer guidance so the very next
+                    // request carries it. It lands in the input before this round's
+                    // call/output items (the injection point predates the follow-up
+                    // accumulation) — semantically fine, the guidance names the
+                    // repeated pattern explicitly.
+                    await this.flushDoomLoopSteer();
+                    // Inject any background-tool results that settled since the last
+                    // flush. Same safe point as the steer flush: the round is fully
+                    // paired, so a user-role envelope here is valid history.
+                    await this.flushAsyncToolDeliveries();
                     // Apply nextTurnParams
                     await this.applyNextTurnParams(currentToolCalls);
                     currentResponse = await this.makeFollowupRequest(currentResponse, toolResults, turnNumber);
@@ -2412,6 +4775,8 @@ export class ModelResult {
                     await this.options.onTurnEnd?.(turnContext, currentResponse);
                     // Save new response to state
                     await this.saveResponseToState(currentResponse);
+                    // Doom-loop text checkpoint for the fresh response.
+                    await this.checkDoomLoopForResponse(currentResponse);
                     currentRound++;
                 }
                 // If stopWhen broke the loop while the model was still emitting tool
@@ -2434,7 +4799,7 @@ export class ModelResult {
                     };
                     await this.options.onTurnStart?.(turnContext);
                     await this.resolveAsyncFunctionsForTurn(turnContext);
-                    const { toolResults, pausedCalls } = await this.executeToolRound(pendingToolCalls, turnContext);
+                    const { toolResults, pausedCalls, deferredTasks: finalDeferredTasks = [], } = 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
@@ -2455,30 +4820,49 @@ export class ModelResult {
                         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,
-                        ...stubOutputs,
-                    ];
-                    currentResponse = await this.makeFinalResponseRequest(currentResponse, requestOutputs, allowFinalResponse, turnNumber);
-                    await this.options.onTurnEnd?.(turnContext, currentResponse);
-                    await this.saveResponseToState(currentResponse);
+                    if (finalDeferredTasks.length > 0) {
+                        // Deferred tasks started on the halted turn — persist the pause
+                        // and skip the final text-coercion request; the resumed run
+                        // produces the final answer with the real results in hand.
+                        await this.persistAsyncToolPause(currentResponse, finalDeferredTasks);
+                        return;
+                    }
+                    // A doom-stop armed while executing the halted turn's pending
+                    // calls: seal and skip the final text-coercion request — the
+                    // design contract is "no further model requests after stop".
+                    if (this.doomLoopStop) {
+                        await this.sealDoomLoopStop(currentResponse, new Set(toolResults.map((r) => r.callId)));
+                        sessionEndReason = 'doom_loop';
+                    }
+                    else {
+                        // 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,
+                            ...stubOutputs,
+                        ];
+                        currentResponse = await this.makeFinalResponseRequest(currentResponse, requestOutputs, allowFinalResponse, turnNumber);
+                        await this.options.onTurnEnd?.(turnContext, currentResponse);
+                        await this.saveResponseToState(currentResponse);
+                    }
                 }
+                // Background tasks still in flight (or settled but undelivered) as
+                // the loop finalizes: drain / detach / cancel per asyncTools config.
+                currentResponse = await this.handleRunEndAsyncTasks(currentResponse);
                 // 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
@@ -2502,6 +4886,9 @@ export class ModelResult {
             }
             catch (error) {
                 sessionEndReason = 'error';
+                // A failing (or aborted) run must not leave tool bodies or
+                // background tasks running against a dead conversation.
+                this.abortAllToolWork(error instanceof Error ? error.message : String(error));
                 throw error;
             }
             finally {
@@ -2552,6 +4939,10 @@ export class ModelResult {
      * Get the complete response object including usage information.
      * This will consume the stream until completion and execute any tools.
      * Returns the full OpenResponsesResult with usage data (inputTokens, outputTokens, cachedTokens, etc.)
+     *
+     * Note: in a multi-round tool loop this is the **final** round's response
+     * only — its `usage` block covers that one generation, not the run. For
+     * aggregate totals across every model call, use `getUsage()`.
      */
     async getResponse() {
         await this.executeToolsIfNeeded();
@@ -2640,6 +5031,17 @@ export class ModelResult {
      * - file_search_call: File search operations
      * - image_generation_call: Image generation operations
      * - function_call_output: Results from executed tools
+     *
+     * This stream carries **output items only** — no usage or response-level
+     * metadata. The `response.completed` events (which hold each round's usage
+     * block) are not surfaced here, and `getResponse()` afterwards returns only
+     * the *final* round's response, so a multi-round tool loop's `tool_calls`
+     * generations are not accounted for by either. For usage, reach for:
+     * - `getUsage()` — aggregate token/cost totals across every round
+     * - the `PostModelCall` hook — one emit per model call, with
+     *   `turnType`/`turnNumber` and that call's own `usage`
+     * - `getFullResponsesStream()` — raw events including each round's
+     *   `response.completed`, and therefore its per-round usage block
      */
     getItemsStream() {
         // Build the allowed-item-type scope from the tools actually passed to
@@ -3062,23 +5464,82 @@ export class ModelResult {
         }
     }
     /**
-     * Cancel the underlying stream and all consumers
+     * Cancel the underlying stream and all consumers, and abort in-flight
+     * tool executions and background tasks (their `ctx.signal` fires).
+     *
+     * Note: prior releases only cancelled the stream; aborting tool work is
+     * new with async tool support.
      */
     async cancel() {
+        this.abortAllToolWork('Cancelled via ModelResult.cancel()');
         if (this.reusableStream) {
             await this.reusableStream.cancel();
         }
     }
+    /**
+     * Snapshot of every async tool task tracked by this run (background and
+     * deferred), including settled ones.
+     */
+    getAsyncTasks() {
+        return this.asyncToolRegistry?.snapshot() ?? [];
+    }
+    /**
+     * Cancel one in-process async task by its task id. Background tasks abort
+     * their `ctx.signal`; the model receives a `status: 'cancelled'` envelope
+     * at the next delivery point so it is not left waiting forever.
+     *
+     * For deferred tasks in a paused (possibly other-process) conversation,
+     * use the deferred tool's `.cancel()` method instead.
+     *
+     * @returns true when a working task was found and cancelled.
+     */
+    cancelTask(taskId, reason) {
+        return this.asyncToolRegistry?.cancelTask(taskId, reason) ?? false;
+    }
+    /**
+     * Send a steering message to a running in-process task. Delivered to the
+     * run body's `ctx.onMessage` handler (queued until one registers). Agent
+     * tools (`tool.agent()`) auto-forward messages into the child
+     * conversation as user messages at the child's next turn boundary.
+     *
+     * Throws for deferred tasks — their work runs in an external system;
+     * steer it there.
+     *
+     * @returns true when a working task received (or queued) the message.
+     */
+    sendToTask(taskId, message) {
+        return this.asyncToolRegistry?.sendToTask(taskId, message) ?? false;
+    }
+    /**
+     * Queue a user-role message for injection into this run's conversation at
+     * the next safe turn boundary (the same mechanism doom-loop steer
+     * guidance uses — never between a dangling `function_call` and its
+     * output). The primary consumer is `tool.agent()`, which forwards
+     * steering messages into child conversations through this.
+     *
+     * Delivery requires a next dispatch: boundaries are post-tool-round
+     * follow-ups, pause-persists, and end-of-run drain turns. A message
+     * queued while the run is composing its FINAL text response (no further
+     * dispatch of any kind) has no boundary left and is not delivered —
+     * steer while the run still has work in flight.
+     */
+    queueUserMessage(text) {
+        this.queueDoomLoopSteer(text);
+    }
     // =========================================================================
     // Multi-Turn Conversation State Methods
     // =========================================================================
     /**
      * Check if the conversation requires human/client input to continue.
-     * Returns true when the conversation is paused waiting for caller-supplied
-     * 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.
+     * Returns true when the conversation is paused waiting on the CALLER —
+     * approval/rejection (`awaiting_approval`), HITL tool resume
+     * (`awaiting_hitl`), client-executed manual tools
+     * (`awaiting_client_tools`), or an external async task resolution
+     * (`awaiting_async_tools`, cleared via the deferred tool's `.resolve()` /
+     * `.fail()` / `.cancel()` or `resumeToolResults()` — NOT via
+     * `approveToolCalls`). Also returns true whenever `pendingToolCalls` is
+     * populated regardless of status. To branch on the pause KIND, read
+     * `(await getState()).status` instead.
      */
     async requiresApproval() {
         await this.initStreamGuarded({
@@ -3087,7 +5548,8 @@ export class ModelResult {
         const status = this.currentState?.status;
         if (status === 'awaiting_approval' ||
             status === 'awaiting_hitl' ||
-            status === 'awaiting_client_tools') {
+            status === 'awaiting_client_tools' ||
+            status === 'awaiting_async_tools') {
             return true;
         }
         // Also check if pendingToolCalls is populated
@@ -3126,5 +5588,139 @@ export class ModelResult {
         }
         return this.currentState;
     }
+    /**
+     * The doom-loop verdict that stopped this run, or null when the run was
+     * not stopped by doom-loop detection (including when detection is off).
+     * Resolves after the tool loop settles. For per-event observation use the
+     * `DoomLoopDetected` hook.
+     */
+    async getDoomLoopVerdict() {
+        await this.initStreamGuarded({
+            requireStream: false,
+        });
+        if (!this.isResumingFromApproval) {
+            await this.executeToolsIfNeeded();
+        }
+        return this.doomLoopStop;
+    }
+    /**
+     * Aggregate token/cost usage across **every** model call this run made —
+     * the initial request, each tool-round follow-up, the empty-final retry,
+     * the `allowFinalResponse` final turn, and approval-resume requests.
+     *
+     * This is the pull-based counterpart to the `SessionEnd.totalUsage` hook
+     * payload (same `SessionUsageTotals` shape, same numbers) and exists
+     * because `getResponse()` returns only the **final** round's response: in a
+     * multi-round tool loop the `tool_calls` generations' tokens are otherwise
+     * unreachable, and `getItemsStream()` carries output items only — no
+     * `response.completed` usage block.
+     *
+     * Gates on run completion the same way `getResponse()` does, so totals are
+     * final whether you await it directly, after `getResponse()`, or after
+     * consuming any of the streaming getters — except on an approval-resumed
+     * run, where reading usage never advances the tool loop: the resume
+     * request's own generation is awaited and counted, but no further rounds
+     * are driven, so totals can be mid-run. Await `getResponse()`/`getText()`
+     * first for final totals there. On a run that paused (approval / HITL) or
+     * failed, it returns the totals accrued so far — `modelCalls: 0` with
+     * zeroed tokens when no model call ever completed.
+     *
+     * Unlike `getResponse()`, this never rejects: a failed run still consumed
+     * tokens, and cost accounting typically runs in a `finally`/`catch` where a
+     * second throw would mask the run's original error. Await the run itself
+     * (e.g. `getResponse()`) if you need to observe the failure.
+     *
+     * `cost` is present only when the server reported cost accounting for at
+     * least one call; a `0` would be indistinguishable from "free".
+     *
+     * For per-call granularity use the `PostModelCall` hook (one emit per model
+     * call, with `turnType`/`turnNumber`) or `getFullResponsesStream()`, whose
+     * `response.completed` events carry each round's own usage block.
+     */
+    async getUsage() {
+        try {
+            await this.initStreamGuarded({
+                requireStream: false,
+            });
+            if (!this.isResumingFromApproval) {
+                await this.executeToolsIfNeeded();
+            }
+            else if (this.pendingModelCall && this.reusableStream) {
+                // The resume dispatch returned a live event stream whose telemetry
+                // is still parked (the non-streaming branch folds usage in
+                // immediately — see continueWithUnsentResults). Consuming the
+                // reusable stream is a passive observation: it buffers events
+                // without executing tools or mutating conversation state, so the
+                // resume generation is counted without advancing the loop.
+                await this.emitPendingModelCallOnce(await consumeStreamForCompletion(this.reusableStream));
+            }
+        }
+        catch (error) {
+            // Intentionally swallowed — see the "never rejects" note above. The
+            // aggregate below still reports whatever calls completed before the
+            // failure; the warn leaves a diagnostic thread for the swallowed cause.
+            console.warn('[getUsage] run failed; reporting totals accrued so far:', error);
+        }
+        return this.snapshotSessionUsage();
+    }
+}
+/**
+ * The unified-run affordances (`ctx.defer` for deferred tools, `ctx.log`,
+ * `ctx.onMessage`, the transcript-source slot) threaded into a tool's run
+ * context via `runExtras`.
+ */
+function buildRunExtras(tool, runBinding) {
+    return {
+        ...(isUnifiedTool(tool) &&
+            tool.function.lifecycle === 'deferred' && {
+            defer: (taskId, options) => ({
+                __deferred: true,
+                taskId,
+                ...(options ?? {}),
+            }),
+        }),
+        log: runBinding.log,
+        onMessage: runBinding.onMessage,
+        // Live getter through the binding — the ToolTask (and its id) is only
+        // created when the call escapes the round, after this object is built.
+        get taskId() {
+            return runBinding.task()?.taskId;
+        },
+        // Transcript slot only — deliberately NOT `task`: TurnContext.task is
+        // the ToolTaskHandle facade (check calls only) and a run body must not
+        // see a transcript-only object under that name.
+        taskTranscript: {
+            set transcriptSource(source) {
+                runBinding.setTranscriptSource(source);
+            },
+            get transcriptSource() {
+                return runBinding.task()?.transcriptSource;
+            },
+        },
+    };
+}
+/**
+ * `task` tool, action=result on a SETTLED live task: the final result
+ * (completed) or terminal status + error. Null when the task is not
+ * settled in-process — the caller falls back to the status view.
+ */
+function taskToolResultIfSettled(input, liveTask) {
+    if (liveTask?.status === 'completed') {
+        return {
+            taskId: input.taskId,
+            status: 'completed',
+            result: liveTask.result,
+        };
+    }
+    if (liveTask && liveTask.status !== 'working') {
+        return {
+            taskId: input.taskId,
+            status: liveTask.status,
+            ...(liveTask.error !== undefined && {
+                error: liveTask.error,
+            }),
+        };
+    }
+    return null;
 }
 //# sourceMappingURL=model-result.js.map