@qduc/term2 0.13.0 → 0.15.0

package/dist/services/agent-runtime/application-run-loop.js

@@ -5,13 +5,15 @@ import { isZodToolParameterSchema } from '../../tools/types.js';
 import { normalizeToolParameters } from '../../lib/tool-invoke.js';
 import { isCancellationError, isHarnessInvariantError } from '../../lib/harness-invariant-error.js';
 import { ApprovalLedger } from './tool-invocation-context.js';
+import { RunBudget, isRunBudgetInteraction, } from './run-budget.js';
 import { addTokenUsage, normalizeUsage } from '../../utils/ai/token-usage.js';
 import { computeModelCost } from '../../services/cost/model-cost.js';
 import { getCatalogPricingVersion, getModelPricing } from '../../services/cost/pricing.js';
 import { GenerationDeadline, GenerationGuard, GenerationGuardError, } from './generation-guard.js';
 /**
- * Raised when a run exceeds its `maxTurns` budget. The loop owns turn counting
- * — the SDK-era `callModelInputFilter` hook is deliberately not reintroduced.
+ * Compatibility error for legacy callers without a staged run budget. The loop
+ * owns turn counting — the SDK-era `callModelInputFilter` hook is deliberately
+ * not reintroduced.
  */
 export class MaxTurnsExceededError extends Error {
     maxTurns;
@@ -65,6 +67,8 @@ class EventQueue {
  * turns and silently drop later turns' records.
  */
 let nextCostRequestSeq = 0;
+let nextToolBatchSeq = 0;
+const DEFAULT_MAX_PARALLEL_TOOL_CALLS = 3;
 /**
  * Small provider-neutral agent loop. It owns model-turn sequencing and tool
  * execution; providers only implement `StreamedModelTurn`.
@@ -74,6 +78,7 @@ export class ApplicationRunLoop {
     #contextCompactionSessionState;
     #activeAbortController = null;
     #runInFlight = false;
+    #segmentGeneration = 0;
     /**
      * Set when a segment ends holding approvals, meaning the turn is pausing
      * rather than finishing. Injections offered during the pause wait here for
@@ -93,6 +98,8 @@ export class ApplicationRunLoop {
      */
     #turnOpen = false;
     #pendingSteers = [];
+    /** The run whose budget an out-of-band grant applies to, held across a pause. */
+    #activeRunBudgetState;
     constructor(deps) {
         this.#deps = deps;
         this.#contextCompactionSessionState = deps.contextCompactionSessionState ?? { disabled: false };
@@ -134,6 +141,38 @@ export class ApplicationRunLoop {
         this.#activeAbortController?.abort();
         this.#activeAbortController = null;
     }
+    /**
+     * Grant one finite continuation extension to the current logical run.
+     *
+     * The interactive prompt calls this before resuming because it has to show
+     * the human a refusal rather than a silent stop. The grant is recorded so the
+     * matching `approve` does not charge a second one.
+     */
+    grantRunBudgetExtension(grantedBy = 'human') {
+        const state = this.#activeRunBudgetState;
+        if (!state?.runBudget)
+            return { granted: false, extensionsGranted: 0 };
+        const grant = state.runBudget.grantExtension(grantedBy);
+        if (grant.granted)
+            state.runBudgetGrantConsumed = true;
+        return grant;
+    }
+    /**
+     * Charge this interaction's extension unless a caller already took it.
+     *
+     * An ungranted arrival here means nobody was prompted — the continuation
+     * applier, non-interactive mode, `--auto-approve`. That is a parent-class
+     * grant, so it is capped and eventually refuses.
+     */
+    #takeRunBudgetGrant(state) {
+        if (state.runBudgetGrantConsumed) {
+            state.runBudgetGrantConsumed = false;
+            return true;
+        }
+        if (!state.runBudget)
+            return true;
+        return state.runBudget.grantExtension('parent').granted;
+    }
     /**
      * Hand the running turn a user message to send with its next model request.
      *
@@ -250,7 +289,9 @@ export class ApplicationRunLoop {
             history: normalizeHistory(input),
             // A response ID is usable only after its provider origin is recorded.
             // This also makes old callers that omit providerId fail closed.
-            responseId: options.providerId && options.supportsConversationChaining === true
+            responseId: options.disableChainingForAttempt !== true &&
+                options.providerId &&
+                options.supportsConversationChaining === true
                 ? options.previousResponseId ?? undefined
                 : undefined,
             pendingApprovals: [],
@@ -260,6 +301,7 @@ export class ApplicationRunLoop {
                 ? options.providerId
                 : undefined,
             requestPreparation: options.requestPreparation,
+            disableChainingForAttempt: options.disableChainingForAttempt === true,
             sessionId: options.sessionId,
             turnId: options.turnId,
             hookScope: options.hookScope,
@@ -267,12 +309,36 @@ export class ApplicationRunLoop {
             approvals: options.approvals ?? new ApprovalLedger(),
             turnCount: 0,
             maxTurns: options.maxTurns,
+            ...(options.runBudget
+                ? {
+                    runBudget: new RunBudget(options.runBudget),
+                    onRunBudgetEvent: options.onRunBudgetEvent,
+                    wrapUpOnCriticalRunBudget: options.wrapUpOnCriticalRunBudget,
+                    runBudgetEscalation: options.runBudget.escalation,
+                }
+                : {}),
+            automaticCompactionsThisRun: 0,
         };
         state.approve = (interruption) => {
+            if (isRunBudgetInteraction(interruption)) {
+                // Continuing past an exhausted envelope must cost a finite extension no
+                // matter which surface answered. A caller that already took the grant
+                // (the interactive prompt, which needs the outcome before resuming)
+                // marks it consumed; every other path — the continuation applier,
+                // non-interactive, --auto-approve — lands here ungranted and takes it
+                // now. Without this, an auto-approved 'y' would resume with every stage
+                // still latched and never check in again.
+                state.runBudgetInteractionDecision = this.#takeRunBudgetGrant(state) ? 'continue' : 'stop';
+                return;
+            }
             state.approvalDecision = 'approved';
             state.approvalDecisionCallId = getInterruptionCallId(interruption);
         };
         state.reject = (interruption, approvalOptions) => {
+            if (isRunBudgetInteraction(interruption)) {
+                state.runBudgetInteractionDecision = 'stop';
+                return;
+            }
             state.approvalDecision = 'rejected';
             state.approvalDecisionCallId = getInterruptionCallId(interruption);
             state.approvalMessage = approvalOptions?.message;
@@ -298,6 +364,15 @@ export class ApplicationRunLoop {
         // Handles created before cost accounting existed have no record list.
         if (!state.costRecords)
             state.costRecords = [];
+        if (!state.runBudget && options.runBudget) {
+            state.runBudget = new RunBudget(options.runBudget);
+        }
+        if (options.runBudget)
+            state.runBudgetEscalation = options.runBudget.escalation;
+        if (options.onRunBudgetEvent)
+            state.onRunBudgetEvent = options.onRunBudgetEvent;
+        if (options.wrapUpOnCriticalRunBudget)
+            state.wrapUpOnCriticalRunBudget = true;
         // Response IDs are provider-owned. A handle from before provenance was
         // recorded, a missing providerId, or a provider switch must never forward
         // its opaque ID. In particular, do not use previousResponseId as a
@@ -336,6 +411,11 @@ export class ApplicationRunLoop {
         // root closure for callers that do not provide one again.
         if (options.requestPreparation)
             state.requestPreparation = options.requestPreparation;
+        if (options.disableChainingForAttempt === true) {
+            state.disableChainingForAttempt = true;
+            state.responseId = undefined;
+            state.responseProviderId = undefined;
+        }
         if (options.sessionId !== undefined)
             state.sessionId = options.sessionId;
         if (options.turnId !== undefined)
@@ -346,10 +426,12 @@ export class ApplicationRunLoop {
     }
     #run(state, options) {
         const queue = new EventQueue();
+        const segmentGeneration = ++this.#segmentGeneration;
         this.abortSegment();
         const controller = new AbortController();
         this.#activeAbortController = controller;
         this.#runInFlight = true;
+        state.runBudget?.resume();
         // This segment is running, so the turn is no longer paused between them.
         this.#turnPaused = false;
         if (options.signal) {
@@ -368,6 +450,15 @@ export class ApplicationRunLoop {
             get turn() {
                 return { count: state.turnCount, max: state.maxTurns };
             },
+            get budget() {
+                return state.runBudget
+                    ? {
+                        takeSoftEvidence: () => state.runBudget?.takeSoftEvidence(),
+                        takeStallEvidence: () => state.runBudget?.takeStallEvidence(),
+                        remainingPolicy: () => state.runBudget?.remainingPolicy(),
+                    }
+                    : undefined;
+            },
         };
         const output = [];
         const stream = createAgentStream({
@@ -397,6 +488,9 @@ export class ApplicationRunLoop {
             throw error;
         })
             .finally(() => {
+            state.runBudget?.pause();
+            if (segmentGeneration !== this.#segmentGeneration)
+                return;
             if (this.#activeAbortController === controller)
                 this.#activeAbortController = null;
             this.#runInFlight = false;
@@ -406,10 +500,13 @@ export class ApplicationRunLoop {
             // that ends with nothing outstanding has truly finished the turn, and
             // then anything still waiting has to be sent as its own turn instead.
             const pendingApprovals = state.pendingApprovals?.length ?? 0;
+            const pendingBudgetInteraction = state.pendingRunBudgetInteraction !== undefined;
             const cancelled = stream.cancelled === true;
-            this.#turnPaused = pendingApprovals > 0 && !cancelled && exitError === undefined;
+            this.#turnPaused = (pendingApprovals > 0 || pendingBudgetInteraction) && !cancelled && exitError === undefined;
             if (this.#turnPaused)
                 return;
+            if (this.#activeRunBudgetState === state)
+                this.#activeRunBudgetState = undefined;
             // A declared turn outlives its segments — this one may be about to be
             // retried, or resumed past a post-execute gate. Its owner says when it
             // is over.
@@ -417,17 +514,33 @@ export class ApplicationRunLoop {
                 return;
             this.#releasePendingSteers({
                 pendingApprovals,
+                pendingBudgetInteraction,
                 cancelled,
                 error: exitError instanceof Error ? exitError.name : exitError ? String(exitError) : undefined,
                 turnCount: state.turnCount,
             });
         });
+        this.#activeRunBudgetState = state.runBudget ? state : undefined;
         return stream;
     }
     async #execute(state, stream, queue, options, toolContext, requestAbortController) {
         while (true) {
             if (options.signal?.aborted)
                 throw Object.assign(new Error('Operation aborted'), { name: 'AbortError' });
+            if (state.pendingRunBudgetInteraction) {
+                if (state.runBudgetInteractionDecision === 'stop') {
+                    state.pendingRunBudgetInteraction = undefined;
+                    state.runBudgetInteractionDecision = undefined;
+                    return finish(stream, state, queue);
+                }
+                if (state.runBudgetInteractionDecision === 'continue') {
+                    state.pendingRunBudgetInteraction = undefined;
+                    state.runBudgetInteractionDecision = undefined;
+                }
+                else {
+                    return this.#pauseForRunBudgetInteraction(state, stream, queue);
+                }
+            }
             state.pendingApprovals ??= state.pendingApproval ? [state.pendingApproval] : [];
             if (state.pendingApprovals.length > 0 && state.approvalDecision) {
                 const selectedIndex = state.approvalDecisionCallId
@@ -445,27 +558,20 @@ export class ApplicationRunLoop {
                 else {
                     state.approvals.rejectTool({ toolName: pending.toolName, callId: pending.callId }, { message: state.approvalMessage });
                 }
-                const rawResult = approved
-                    ? await this.#invokeTool(pending.definition, pending.params, toolContext, pending.callId, state)
-                    : state.approvalMessage ?? 'rejected';
-                const result = typeof rawResult === 'string' ? rawResult : JSON.stringify(rawResult);
-                const resultItem = {
-                    type: 'function_call_result',
-                    callId: pending.callId,
-                    name: pending.toolName,
-                    output: result,
-                };
-                state.history.push(resultItem);
-                state.input.push({ type: 'tool_result', id: pending.callId, output: result });
-                outputPush(stream, queue, { type: 'item', item: resultItem });
+                pending.plan.status = 'ready';
+                if (!approved)
+                    pending.plan.output = state.approvalMessage ?? 'rejected';
                 state.pendingApprovals.splice(pendingIndex, 1);
                 state.pendingApproval = state.pendingApprovals[0];
                 state.approvalDecision = undefined;
                 state.approvalDecisionCallId = undefined;
                 state.approvalMessage = undefined;
+                await this.#settleToolPlan(state, stream, queue, toolContext);
                 stream.interruptions = state.pendingApprovals.map((item) => item.interruption);
-                if (state.pendingApprovals.length > 0)
+                if (state.pendingApprovals.length > 0) {
+                    this.#turnPaused = true;
                     return finish(stream, state, queue);
+                }
                 // Nothing is outstanding, so this segment is terminal — see
                 // `stopAfterApprovalResolution`. Stopping here rather than at the
                 // request boundary below is what keeps the just-recorded tool result
@@ -473,32 +579,115 @@ export class ApplicationRunLoop {
                 if (options.stopAfterApprovalResolution)
                     return finish(stream, state, queue);
             }
+            // A budget interaction can park a response after its tool calls are
+            // recorded but before any body runs. Resume those retained calls only
+            // after processing an ordinary approval decision for that same plan.
+            if (state.toolPlan) {
+                await this.#settleToolPlan(state, stream, queue, toolContext);
+                if (state.pendingApprovals?.length) {
+                    stream.interruptions = state.pendingApprovals.map((item) => item.interruption);
+                    this.#turnPaused = true;
+                    return finish(stream, state, queue);
+                }
+            }
             // The request boundary: every tool result of the previous round is in
             // history, and the next request has not been built. A user message
             // admitted here reaches the model in sequence, mid-turn.
-            this.#admitPendingSteers(state, stream, queue);
-            state.turnCount += 1;
-            if (state.maxTurns !== undefined && state.turnCount > state.maxTurns) {
-                throw new MaxTurnsExceededError(state.maxTurns);
+            if (!state.requestBoundaryReady) {
+                this.#admitPendingSteers(state, stream, queue);
+                this.#evaluateRunBudget(state, stream, queue);
+                if (state.pendingRunBudgetInteraction)
+                    return this.#pauseForRunBudgetInteraction(state, stream, queue);
+                if (options.boundaryCompaction) {
+                    const compactionStartedAt = Date.now();
+                    const compaction = await options.boundaryCompaction.compact({
+                        history: state.history,
+                        automaticCompactionsThisRun: state.automaticCompactionsThisRun ?? 0,
+                        signal: options.signal,
+                        onStarted: (provider) => outputPush(stream, queue, { type: 'context_compaction_started', provider, strategy: 'local' }),
+                    });
+                    if (compaction.kind === 'compacted') {
+                        state.history.splice(0, state.history.length, ...compaction.history);
+                        state.input.splice(0, state.input.length, ...normalizeApplicationInput(compaction.modelInput));
+                        state.responseId = undefined;
+                        state.responseProviderId = undefined;
+                        if (compaction.costRecords?.length) {
+                            state.costRecords ??= [];
+                            state.costRecords.push(...compaction.costRecords);
+                        }
+                        state.automaticCompactionsThisRun = (state.automaticCompactionsThisRun ?? 0) + 1;
+                        outputPush(stream, queue, {
+                            type: 'context_compaction_completed',
+                            provider: state.currentProviderId ?? 'unknown',
+                            strategy: 'local',
+                            durationMs: Math.max(0, Date.now() - compactionStartedAt),
+                        });
+                    }
+                    else if (compaction.kind === 'failed') {
+                        outputPush(stream, queue, {
+                            type: 'context_compaction_failed',
+                            provider: compaction.provider,
+                            strategy: 'local',
+                            durationMs: Math.max(0, Date.now() - compactionStartedAt),
+                        });
+                    }
+                    // Summarization is an asynchronous part of this same request
+                    // boundary. Admit anything that arrived while it was in flight after
+                    // applying a replacement, so the steer cannot be overwritten by the
+                    // checkpoint or miss a terminal model request.
+                    this.#admitPendingSteers(state, stream, queue);
+                    this.#evaluateRunBudget(state, stream, queue);
+                    if (state.pendingRunBudgetInteraction)
+                        return this.#pauseForRunBudgetInteraction(state, stream, queue);
+                }
+                state.turnCount += 1;
+                this.#evaluateRunBudget(state, stream, queue);
+                if (state.pendingRunBudgetInteraction) {
+                    state.requestBoundaryReady = true;
+                    return this.#pauseForRunBudgetInteraction(state, stream, queue);
+                }
+                // Retain the legacy error only for callers that have not adopted staged
+                // budgets. A configured run budget turns the same count into critical
+                // evidence and lets the decision surface choose what happens next.
+                if (!state.runBudget && state.maxTurns !== undefined && state.turnCount > state.maxTurns) {
+                    throw new MaxTurnsExceededError(state.maxTurns);
+                }
+            }
+            else {
+                state.requestBoundaryReady = undefined;
             }
             const model = await this.#deps.resolveModel(state.agent.model);
             let sawToolCall = false;
+            const streamedToolCalls = [];
             let completion;
             let pendingNativeReasoning;
             // Stable process-unique request id, allocated immediately before dispatch
             // so a cost record can be settled exactly once (success or failure).
             const requestId = this.#nextRequestId();
+            const criticalWrapUp = state.criticalWrapUpPending === true && state.criticalWrapUpDispatched !== true;
+            if (criticalWrapUp)
+                state.criticalWrapUpDispatched = true;
+            const disableChaining = state.disableChainingForAttempt === true;
+            if (disableChaining) {
+                state.disableChainingForAttempt = false;
+                state.responseId = undefined;
+                state.responseProviderId = undefined;
+            }
             const request = {
-                instructions: state.agent.instructions,
+                instructions: criticalWrapUp
+                    ? `${state.agent.instructions}\n\nBudget containment is terminal. Do not call tools. In this one final response, summarize what you completed, the evidence you have, and what remains.`
+                    : state.agent.instructions,
                 ...(state.supportsConversationChaining &&
+                    !disableChaining &&
                     state.responseId &&
                     state.responseProviderId !== undefined &&
                     state.responseProviderId === state.currentProviderId
                     ? { previousResponseId: state.responseId }
                     : {}),
+                ...(disableChaining ? { disableChaining: true } : {}),
                 input: state.input,
-                tools: toModelTools(state.agent.tools),
-                applicationTools: state.agent.tools,
+                tools: toModelTools(criticalWrapUp ? [] : state.agent.tools),
+                applicationTools: criticalWrapUp ? [] : state.agent.tools,
                 ...(state.agent.modelSettings?.temperature !== undefined
                     ? { temperature: state.agent.modelSettings.temperature }
                     : {}),
@@ -527,7 +716,7 @@ export class ApplicationRunLoop {
                 ...options.generationGuard,
             });
             const consume = async () => {
-                const deadline = new GenerationDeadline(generationGuard.requestDeadlineMs, () => requestAbortController.abort());
+                const deadline = new GenerationDeadline(generationGuard.requestDeadlineMs, () => requestAbortController.abort(), () => generationGuard.progress);
                 let iterator;
                 let iteratorFinished = false;
                 try {
@@ -572,7 +761,7 @@ export class ApplicationRunLoop {
                             generationGuard.observeToolCall(event.arguments);
                             pendingNativeReasoning = commitPendingNativeReasoning(state, stream, queue, pendingNativeReasoning);
                             sawToolCall = true;
-                            await this.#handleToolCall(state, stream, queue, event, toolContext);
+                            streamedToolCalls.push(event);
                         }
                     }
                 }
@@ -610,10 +799,27 @@ export class ApplicationRunLoop {
                 // persistence and replay, and a cost event must never become a
                 // restored history item.
                 queue.push({ type: 'cost_update', record });
+                this.#evaluateRunBudget(state, stream, queue);
                 throw error;
             }
-            if (!completion)
-                throw new Error('Application model turn ended without completion');
+            if (!completion) {
+                // A few application-owned model fixtures (and legacy adapters) end a
+                // tool-call stream immediately after the call and use the next request
+                // as the continuation boundary. Preserve that contract while routing
+                // the calls through the same ordered dispatcher. An empty stream still
+                // fails closed as an incomplete model turn.
+                if (streamedToolCalls.length === 0)
+                    throw new Error('Application model turn ended without completion');
+                if (criticalWrapUp)
+                    return finish(stream, state, queue);
+                await this.#dispatchToolCalls(state, stream, queue, streamedToolCalls, toolContext);
+                if (state.pendingApprovals && state.pendingApprovals.length > 0) {
+                    stream.interruptions = state.pendingApprovals.map((item) => item.interruption);
+                    this.#turnPaused = true;
+                    return finish(stream, state, queue);
+                }
+                continue;
+            }
             // Commit the authoritative terminal state before handling terminal-only
             // tool calls. Approval may pause immediately after this point, and the
             // continuation must still carry the response that produced the calls.
@@ -675,11 +881,18 @@ export class ApplicationRunLoop {
                 providerUsd: completion.costUsd,
             });
             queue.push({ type: 'cost_update', record });
+            // Cost and usage arrive in the same completion metadata, so surface both
+            // live. The footer is a per-request indicator: emit this request's own
+            // usage, never the run accumulator in `state.usage`.
+            if (normalizedCompletionUsage)
+                queue.push({ type: 'usage_update', usage: normalizedCompletionUsage });
+            this.#evaluateRunBudget(state, stream, queue);
             stream.lastResponseId = completion.responseId;
             stream.rawResponses?.push(completion);
             // Some provider adapters report function calls only in the terminal
             // completion rather than as separate stream events. Their reasoning may
             // likewise be terminal-only, so associate it before replaying calls.
+            const toolCalls = [...streamedToolCalls];
             if (!sawToolCall) {
                 for (const item of completion.output) {
                     if (item.type === 'reasoning')
@@ -690,7 +903,7 @@ export class ApplicationRunLoop {
                         continue;
                     pendingNativeReasoning = commitPendingNativeReasoning(state, stream, queue, pendingNativeReasoning);
                     sawToolCall = true;
-                    await this.#handleToolCall(state, stream, queue, item, toolContext);
+                    toolCalls.push(item);
                 }
             }
             // A native reasoning item belongs to the completed assistant turn even
@@ -730,108 +943,192 @@ export class ApplicationRunLoop {
                 outputPush(stream, queue, { type: 'item', item });
                 state.input.push({ type: 'message', role: 'assistant', content: [{ type: 'text', text: assistantText }] });
             }
+            // Tool calls are dispatched only after the reasoning, provider-opaque,
+            // and assistant-text items from the same completion are committed. A
+            // response that carries both prose and a tool call must serialize as
+            // text -> function_call -> function_call_result; dispatching first left
+            // the text stranded after its own tool result, where the assistant
+            // message merger glued it onto the *next* turn's tool call and every
+            // request ended with a bare assistant message. Models read that as a
+            // turn truncated mid-sentence and restart instead of progressing.
+            if (!state.criticalWrapUpPending && toolCalls.length > 0) {
+                await this.#dispatchToolCalls(state, stream, queue, toolCalls, toolContext);
+            }
+            // A critical subagent gets exactly this final tool-free model call.
+            if (criticalWrapUp)
+                return finish(stream, state, queue);
+            if (state.pendingRunBudgetInteraction && toolCalls.length > 0) {
+                return this.#pauseForRunBudgetInteraction(state, stream, queue);
+            }
             if (state.pendingApprovals.length > 0) {
                 stream.interruptions = state.pendingApprovals.map((item) => item.interruption);
+                this.#turnPaused = true;
                 return finish(stream, state, queue);
             }
-            if (!sawToolCall)
+            if (!sawToolCall) {
+                // Evidence discovered when a response has already completed needs no
+                // human boundary: there is no later request or tool to block.
+                state.pendingRunBudgetInteraction = undefined;
                 return finish(stream, state, queue);
+            }
         }
     }
-    async #handleToolCall(state, stream, queue, event, toolContext) {
-        const definition = state.agent.tools.find((tool) => tool.name === event.name);
-        const args = parseArguments(event.arguments);
-        const callItem = {
-            type: 'function_call',
-            callId: event.id,
-            name: event.name,
-            arguments: event.arguments,
-        };
-        state.history.push(callItem);
-        state.input.push({ type: 'tool_call', id: event.id, name: event.name, arguments: event.arguments });
-        outputPush(stream, queue, { type: 'item', item: callItem });
-        if (!definition) {
-            const output = `Unknown tool: ${event.name}`;
-            const resultItem = {
-                type: 'function_call_result',
+    async #dispatchToolCalls(state, stream, queue, events, toolContext) {
+        const plan = events.map((event) => {
+            const definition = state.agent.tools.find((tool) => tool.name === event.name);
+            const callItem = {
+                type: 'function_call',
                 callId: event.id,
                 name: event.name,
-                output,
+                arguments: event.arguments,
             };
-            state.history.push(resultItem);
-            state.input.push({ type: 'tool_result', id: event.id, output });
-            outputPush(stream, queue, { type: 'item', item: resultItem });
-            return;
-        }
-        // Keep the raw-model invocation contract: normalization repairs the
-        // accepted object shape but intentionally does not Zod-parse it, which
-        // would apply schema defaults before execute. web_fetch relies on its
-        // executor fallbacks on the strict JSON-schema path.
-        const params = normalizeToolParameters(args, definition.parameters);
-        // Consult this run's ledger before prompting: a decision already taken
-        // (in the parent run and replayed in, or earlier in this run) must not
-        // prompt again. This is what makes approval replay observable.
-        const alreadyDecided = state.approvals.isToolApproved({ toolName: event.name, callId: event.id });
-        if (alreadyDecided === false) {
-            const message = state.approvals.getRejectionMessage(event.name, event.id) ?? 'Tool execution was not approved.';
-            const resultItem = {
-                type: 'function_call_result',
-                callId: event.id,
-                name: event.name,
-                output: message,
+            state.history.push(callItem);
+            state.input.push({ type: 'tool_call', id: event.id, name: event.name, arguments: event.arguments });
+            outputPush(stream, queue, { type: 'item', item: callItem });
+            return {
+                event,
+                definition,
+                parallelSafe: false,
+                status: 'ready',
             };
-            state.history.push(resultItem);
-            state.input.push({ type: 'tool_result', id: event.id, output: message });
-            outputPush(stream, queue, { type: 'item', item: resultItem });
-            return;
-        }
-        if (alreadyDecided === true) {
-            const result = await this.#invokeTool(definition, params, toolContext, event.id, state);
-            const output = typeof result === 'string' ? result : JSON.stringify(result);
-            const resultItem = {
-                type: 'function_call_result',
-                callId: event.id,
+        });
+        state.toolPlan = plan;
+        for (const entry of plan) {
+            const { event, definition } = entry;
+            if (!definition) {
+                entry.output = `Unknown tool: ${event.name}`;
+                continue;
+            }
+            // Keep the raw-model invocation contract: normalization repairs the
+            // accepted object shape but intentionally does not Zod-parse it, which
+            // would apply schema defaults before execute. web_fetch relies on its
+            // executor fallbacks on the strict JSON-schema path.
+            entry.params = normalizeToolParameters(parseArguments(event.arguments), definition.parameters);
+            const stallEvent = state.runBudget?.observeToolCall({
                 name: event.name,
-                output,
-            };
-            state.history.push(resultItem);
-            state.input.push({ type: 'tool_result', id: event.id, output });
-            outputPush(stream, queue, { type: 'item', item: resultItem });
-            return;
-        }
-        if (await definition.needsApproval(params, toolContext)) {
-            const pending = {
-                callId: event.id,
-                toolName: event.name,
                 argumentsText: event.arguments,
-                interruption: {
-                    type: 'tool_approval_item',
-                    rawItem: { type: 'function_call', callId: event.id, name: event.name, arguments: event.arguments },
+                effect: definition.effect,
+            });
+            if (stallEvent) {
+                this.#emitRunBudgetEvent(state, stallEvent, 'Tool stall evidence', stream, queue);
+            }
+            // Consult this run's ledger before prompting: a decision already taken
+            // (in the parent run and replayed in, or earlier in this run) must not
+            // prompt again. This is what makes approval replay observable.
+            const alreadyDecided = state.approvals.isToolApproved({ toolName: event.name, callId: event.id });
+            if (alreadyDecided === false) {
+                entry.output = state.approvals.getRejectionMessage(event.name, event.id) ?? 'Tool execution was not approved.';
+                continue;
+            }
+            if (alreadyDecided !== true && (await definition.needsApproval(entry.params, toolContext))) {
+                entry.status = 'approval_pending';
+                const pending = {
                     callId: event.id,
-                    name: event.name,
-                    arguments: event.arguments,
-                },
-                definition,
-                params,
-            };
-            state.pendingApprovals ??= [];
-            if (!state.pendingApproval)
-                state.pendingApproval = pending;
-            state.pendingApprovals.push(pending);
-            stream.interruptions = state.pendingApprovals.map((item) => item.interruption);
+                    toolName: event.name,
+                    argumentsText: event.arguments,
+                    interruption: {
+                        type: 'tool_approval_item',
+                        rawItem: { type: 'function_call', callId: event.id, name: event.name, arguments: event.arguments },
+                        callId: event.id,
+                        name: event.name,
+                        arguments: event.arguments,
+                    },
+                    definition,
+                    params: entry.params,
+                    plan: entry,
+                };
+                state.pendingApprovals ??= [];
+                state.pendingApprovals.push(pending);
+                continue;
+            }
+            entry.parallelSafe = await isParallelSafe(definition, entry.params, toolContext);
+        }
+        state.pendingApproval = state.pendingApprovals?.[0];
+        stream.interruptions = (state.pendingApprovals ?? []).map((item) => item.interruption);
+        this.#deps.logDiagnostic?.('tool parallel eligibility', {
+            decisions: plan.map((entry) => ({
+                callId: entry.event.id,
+                toolName: entry.event.name,
+                parallelSafe: entry.parallelSafe,
+                approvalPending: entry.status === 'approval_pending',
+            })),
+        });
+        // A main-agent budget escalation is a real boundary: retain the planned
+        // calls, but do not execute one more tool while human judgement is pending.
+        if (!state.pendingRunBudgetInteraction) {
+            await this.#settleToolPlan(state, stream, queue, toolContext);
+        }
+    }
+    async #settleToolPlan(state, stream, queue, toolContext) {
+        const plan = state.toolPlan;
+        if (!plan)
             return;
+        const maxParallelToolCalls = Math.max(1, Math.floor(this.#deps.resolveMaxParallelToolCalls?.() ?? DEFAULT_MAX_PARALLEL_TOOL_CALLS));
+        while (true) {
+            const firstPending = plan.find((entry) => entry.status !== 'completed');
+            if (!firstPending) {
+                state.toolPlan = undefined;
+                return;
+            }
+            if (firstPending.status === 'approval_pending')
+                return;
+            const group = [];
+            for (const entry of plan) {
+                if (entry.status === 'completed')
+                    continue;
+                if (entry.status === 'approval_pending')
+                    break;
+                if (group.length > 0 && (!entry.parallelSafe || !group[0].parallelSafe || group.length >= maxParallelToolCalls))
+                    break;
+                group.push(entry);
+                if (!entry.parallelSafe)
+                    break;
+            }
+            const batchId = `tool-batch-${++nextToolBatchSeq}`;
+            this.#deps.logDiagnostic?.('tool batch dispatched', {
+                batchId,
+                callIds: group.map((entry) => entry.event.id),
+                parallel: group.length > 1,
+                maxParallelToolCalls,
+                dispatchOrder: group.map((entry) => entry.event.id),
+            });
+            if (group.length > 1) {
+                const results = await Promise.allSettled(group.map((entry) => this.#invokePlannedTool(entry, toolContext, state)));
+                const rejected = results.find((result) => result.status === 'rejected');
+                if (rejected)
+                    throw rejected.reason;
+                for (const [index, result] of results.entries()) {
+                    this.#appendToolResult(state, stream, queue, group[index], result.value);
+                }
+            }
+            else {
+                const result = await this.#invokePlannedTool(group[0], toolContext, state);
+                this.#appendToolResult(state, stream, queue, group[0], result);
+            }
+            this.#deps.logDiagnostic?.('tool batch settled', {
+                batchId,
+                settlementOrder: group.map((entry) => entry.event.id),
+            });
         }
-        const result = await this.#invokeTool(definition, params, toolContext, event.id, state);
+    }
+    async #invokePlannedTool(entry, toolContext, state) {
+        entry.status = 'completed';
+        if (entry.output !== undefined)
+            return entry.output;
+        return this.#invokeTool(entry.definition, entry.params, toolContext, entry.event.id, state);
+    }
+    #appendToolResult(state, stream, queue, entry, result) {
         const output = typeof result === 'string' ? result : JSON.stringify(result);
         const resultItem = {
             type: 'function_call_result',
-            callId: event.id,
-            name: event.name,
+            callId: entry.event.id,
+            name: entry.event.name,
             output,
         };
         state.history.push(resultItem);
-        state.input.push({ type: 'tool_result', id: event.id, output });
+        state.input.push({ type: 'tool_result', id: entry.event.id, output });
         outputPush(stream, queue, { type: 'item', item: resultItem });
+        this.#evaluateRunBudget(state, stream, queue);
     }
     /**
      * A tool that throws must not take the run down with it.
@@ -864,6 +1161,9 @@ export class ApplicationRunLoop {
             attempt,
             scope: state?.hookScope ?? 'root',
         };
+        // Dispatch mark must run before execute so a mid-tool stream failure can
+        // settle the ledger as unknown rather than aborted.
+        this.#deps.getOnToolDispatch?.()?.(callId);
         await this.#notifyToolLifecycle(() => this.#deps.toolLifecycle?.before(lifecycleContext));
         try {
             const result = await definition.execute(params, toolContext, { toolCall: { callId } });
@@ -876,15 +1176,6 @@ export class ApplicationRunLoop {
                 throw error;
             }
             const message = error instanceof Error ? error.message : String(error);
-            // Feeding the same failure back forever is its own failure mode: some
-            // errors no argument can fix. Repeat the identical result once, then say
-            // so plainly rather than inviting a third identical attempt.
-            const repeated = state ? countRepeatedFailure(state, definition.name, params, message) : 1;
-            if (repeated > MAX_IDENTICAL_TOOL_FAILURES) {
-                const result = `Error: ${message}\n\nThis exact call has now failed ${repeated} times with the same error. Do not call ${definition.name} with these arguments again — either change your approach or report the problem to the user.`;
-                await this.#notifyToolLifecycle(() => this.#deps.toolLifecycle?.error(lifecycleContext, error, Date.now() - startedAt, true));
-                return result;
-            }
             const result = `Error: ${message}`;
             await this.#notifyToolLifecycle(() => this.#deps.toolLifecycle?.error(lifecycleContext, error, Date.now() - startedAt, true));
             return result;
@@ -909,6 +1200,49 @@ export class ApplicationRunLoop {
         state.costRecords = [...(state.costRecords ?? []), record];
         return record;
     }
+    #evaluateRunBudget(state, stream, queue) {
+        if (!state.runBudget)
+            return;
+        for (const event of state.runBudget.evaluate({
+            turns: state.turnCount,
+            costRecords: state.costRecords ?? [],
+        })) {
+            this.#emitRunBudgetEvent(state, event, 'Run budget evidence', stream, queue);
+        }
+    }
+    #emitRunBudgetEvent(state, event, message, stream, queue) {
+        if (event.type === 'budget_stage' && event.stage === 'critical' && state.wrapUpOnCriticalRunBudget) {
+            state.criticalWrapUpPending = true;
+        }
+        if (!state.wrapUpOnCriticalRunBudget &&
+            !state.pendingRunBudgetInteraction &&
+            state.runBudgetEscalation !== 'warn' &&
+            this.#requiresHumanBudgetDecision(event)) {
+            state.pendingRunBudgetInteraction = { type: 'run_budget_interaction', event };
+            state.runBudgetGrantConsumed = false;
+        }
+        if (stream && queue)
+            outputPush(stream, queue, { type: 'run_budget', evidence: event });
+        try {
+            state.onRunBudgetEvent?.(event);
+        }
+        catch {
+            // Evidence observers are delivery adapters, not budget owners.
+            this.#deps.logDiagnostic?.('Run budget event observer failed', { type: event.type });
+        }
+        this.#deps.logDiagnostic?.(message, event);
+    }
+    #requiresHumanBudgetDecision(event) {
+        return event.type === 'tool_stall' || (event.type === 'budget_stage' && event.stage !== 'soft');
+    }
+    #pauseForRunBudgetInteraction(state, stream, queue) {
+        const interaction = state.pendingRunBudgetInteraction;
+        if (!interaction)
+            return finish(stream, state, queue);
+        stream.interruptions = [interaction];
+        this.#turnPaused = true;
+        return finish(stream, state, queue);
+    }
     async #notifyToolLifecycle(operation) {
         if (!operation)
             return;
@@ -921,27 +1255,6 @@ export class ApplicationRunLoop {
         }
     }
 }
-/**
- * How many times an identical failing call is fed back before the loop stops
- * inviting retries. One repeat is worth allowing: a transient failure resolves,
- * and a model given the error often corrects on its second attempt.
- */
-const MAX_IDENTICAL_TOOL_FAILURES = 2;
-function countRepeatedFailure(state, toolName, params, message) {
-    let key;
-    try {
-        key = JSON.stringify([toolName, params, message]);
-    }
-    catch {
-        // Unserializable params cannot be compared for identity; treat every such
-        // failure as distinct rather than collapsing unrelated calls together.
-        return 1;
-    }
-    state.toolFailureCounts ??= new Map();
-    const count = (state.toolFailureCounts.get(key) ?? 0) + 1;
-    state.toolFailureCounts.set(key, count);
-    return count;
-}
 function outputPush(stream, queue, item) {
     stream.output.push(item);
     if (stream.newItems !== stream.output)
@@ -967,6 +1280,15 @@ function finish(stream, state, queue) {
  * Chat-Completions continuation field. Generic reasoning remains display-only
  * so providers with different native formats are not given a foreign field.
  */
+/**
+ * True when any lane namespace in the metadata carries an `encrypted_content`
+ * blob — the shape every Responses adapter produces, whichever vendor it is.
+ */
+function hasNamespacedEncryptedReasoning(metadata) {
+    if (!metadata)
+        return false;
+    return Object.values(metadata).some((value) => asRecord(value)?.encrypted_content !== undefined);
+}
 function appendNativeReasoning(current, event) {
     const nativeReasoning = event.providerMetadata?.reasoning_content;
     if (typeof nativeReasoning === 'string') {
@@ -983,8 +1305,10 @@ function appendNativeReasoning(current, event) {
     }
     // Responses providers return encrypted reasoning only on their terminal
     // output. Their metadata is namespaced, so retain it without turning it into
-    // the Chat-Completions-only reasoning_content convention.
-    if (asRecord(event.providerMetadata?.codex) || asRecord(event.providerMetadata?.openai)) {
+    // the Chat-Completions-only reasoning_content convention. Match on the
+    // namespaced shape rather than an allowlist of lane names: an allowlist
+    // silently drops the reasoning of every Responses lane added later.
+    if (hasNamespacedEncryptedReasoning(event.providerMetadata)) {
         return {
             ...(event.id ? { id: event.id } : current?.id ? { id: current.id } : {}),
             text: event.text,
@@ -1043,6 +1367,17 @@ function parseArguments(value) {
         return {};
     }
 }
+async function isParallelSafe(definition, params, context) {
+    if (typeof definition.parallelSafe === 'function') {
+        try {
+            return await definition.parallelSafe(params, context);
+        }
+        catch {
+            return false;
+        }
+    }
+    return definition.parallelSafe === true;
+}
 function getInterruptionCallId(value) {
     if (typeof value !== 'object' || value === null)
         return undefined;