agentfootprint 9.112.2 → 9.114.0

package/dist/esm/core/agent/stages/toolCalls.js

@@ -9,7 +9,10 @@
  *     payload so footprintjs captures a checkpoint.
  *   • `resume` runs after the consumer supplies the human's answer.
  *     Treats that answer as the paused tool's result, appends to
- *     history, then continues the ReAct iteration loop.
+ *     history, then continues the ReAct iteration loop. Calls the model
+ *     batched AFTER the paused one were never dispatched; every resume
+ *     path settles them with one fixed sentence each, a bracket and a
+ *     count, and runs none of them ("── The batch settlement (9.113.0)").
  *
  * Dispatch resolution order (9.92.0 — DISPATCH FOLLOWS THE OFFER):
  *   0. A name on THIS epoch's wire resolves to the party whose contract the
@@ -72,9 +75,10 @@ import { agentToolDispatch } from '../toolDispatch.js';
 import { runToolChain, runToolAfterChain } from '../middleware/runChain.js';
 import { recordDecisions } from '../middleware/ledger.js';
 import { ownsReservedArgument, splitFindings } from '../findings/reserved.js';
-import { knownResults } from '../findings/offer.js';
+import { isResultMessage, knownResults } from '../findings/offer.js';
 import { basisRowFrom, foldLedger, recordFindings, standingRowsFrom, } from '../findings/ledger.js';
 import { contingentRowsOf, groundedArgumentValues, hasSetAsideStanding, } from '../findings/contingent.js';
+import { withUnsettledRows } from '../findings/unsettled.js';
 import { evidenceFromHistory, exemptFromRun, } from '../evidence/evidenceIndex.js';
 import { noteRepeatedCall, repeatedCallLedgers } from '../repeatedCall.js';
 import { formatToolArgIssues, validateToolArgs, } from '../toolArgsValidation.js';
@@ -448,6 +452,127 @@ function argsForPausedCall(scope, toolCallId, peel = false) {
 function appendBatchResult(scope, entry) {
     scope.toolResults = [...(scope.toolResults ?? []), entry];
 }
+/**
+ * THE PAUSED BATCH (9.113.0) — the turn that proposed the paused call, and
+ * the calls on it that a pause left un-dispatched.
+ *
+ * The batch loop in `execute` dispatches a turn's calls one at a time, in the
+ * order the model proposed them, and every pause RETURNS from inside it: the
+ * checkpoint is taken on call k, and calls k+1..N were never reached — no
+ * gate judged them, no tool ran, no bracket opened. The resume paths used to
+ * answer call k and stop, so the next request carried N `tool_use` blocks and
+ * fewer `tool_result`s (a provider builds results only from `role: 'tool'`
+ * messages), and `iteration_end` counted one call.
+ *
+ * READ FROM `history`, NEVER CARRIED. Every pause site commits
+ * `scope.history = newHistory` before it returns, so the assistant turn that
+ * proposed the batch is on the checkpoint — and it is the very message a
+ * provider turns into the `tool_use` blocks the settlement must answer. It is
+ * therefore the one owner of "which calls does the next request carry", and
+ * the checkpoint gains no key: a checkpoint written before this release
+ * settles the same way. The window never removes the turn holding the paused
+ * call (`../window/turns.ts` · `refusalFor`, its `paused-tool` arm).
+ *
+ * The LATEST turn proposing the id is the paused one — the pause site commits
+ * that turn last, and a provider may reuse an id across turns. No such turn:
+ * `size: 0` and nothing to settle, the only answer a missing turn supports.
+ *
+ * A call after the paused one that history ALREADY answers — a `role: 'tool'`
+ * message for its id after that turn — is not un-dispatched, whoever wrote
+ * the answer. No library door writes one before the resume; a checkpoint is
+ * data, though, and an app may have patched results into a stored one.
+ * Settling such a call again would put a second result for its id on the
+ * next request, a shape a provider rejects.
+ */
+export function pausedBatchOf(history, pausedToolCallId) {
+    for (let i = history.length - 1; i >= 0; i--) {
+        const message = history[i];
+        if (message?.role !== 'assistant')
+            continue;
+        const proposed = message.toolCalls ?? [];
+        const at = proposed.findIndex((call) => call.id === pausedToolCallId);
+        if (at < 0)
+            continue;
+        const answered = new Set(history.slice(i + 1).flatMap((m) => (m.role === 'tool' ? [m.toolCallId] : [])));
+        return {
+            size: proposed.length,
+            undispatched: proposed.slice(at + 1).filter((call) => !answered.has(call.id)),
+        };
+    }
+    return { size: 0, undispatched: [] };
+}
+// LENS · tool-result · persistent-history
+// reads: toolName ← the un-dispatched call on the paused turn (`pausedBatchOf`); paused ← scope.pausedToolName + scope.pausedToolCallId, the checkpoint's own carriers
+// law: may omit, never deny; every clause anchored to the call it was composed on; names no destination.
+/**
+ * What a call the paused batch never dispatched gets back (9.113.0) — ONE
+ * fixed sentence, on all four resume paths.
+ *
+ * Every clause is a past fact about one finished event, anchored by name: the
+ * call this result answers ("that call"), the call the run paused on (by id
+ * and by tool), and the resume. It names no destination. The design page's draft
+ * (`docs/design/2026-09-honest-answer-ledger.md`, § 5.5, "The batch
+ * settlement") ended "propose it again if still needed" — an instruction about a LATER call,
+ * re-read on every call after this one, the tool-less wrap-up included.
+ * Whether the call is still needed is the model's to judge from the facts;
+ * the surfaces recomposed per request (the tool list, the system prompt) own
+ * the present tense. Precedents: the 9.86.1 resumed-call refusal in this file
+ * ("was not executed on that call, and the resumed dispatch had no second
+ * checkpoint…") and `../selfCallNotice.ts` · `selfCallNotice`.
+ *
+ * "The run paused ON call …", never "call … paused the run": on two of the
+ * four doors the pause was a gate's, not the call's — a middleware's `ask`, a
+ * credential's consent need — and on all four the run paused AT that call.
+ *
+ * The sentence is for the MODEL. The same fact as data rides the settled
+ * message as `LLMMessage.notDispatched` and both of its brackets as
+ * `notDispatched` (`notDispatchedMarker`), and a reader asking "did this call
+ * run?" reads that — never this text.
+ *
+ * Exported for the producer registry (`test/modelFacingSurfaces.test.ts`).
+ */
+export function notDispatchedResult(toolName, paused) {
+    return (`Tool '${toolName}' was not executed on that call: the run paused on call ` +
+        `'${paused.toolCallId}' to '${paused.toolName}', earlier in the same batch, and resumed ` +
+        `without executing the calls that followed it in that batch.`);
+}
+/**
+ * The same fact as DATA (9.113.0) — the ONE composer of the settlement's
+ * marker, `{ pausedCall: { toolCallId, toolName } }`. The settled call's
+ * history message (`LLMMessage.notDispatched`) and both of its brackets
+ * (`ToolStartPayload.notDispatched`, `ToolEndPayload.notDispatched`) each take
+ * a fresh copy from here, so the three carriers can never disagree and no
+ * reader holds an object another reader holds.
+ */
+function notDispatchedMarker(paused) {
+    return { pausedCall: { toolCallId: paused.toolCallId, toolName: paused.toolName } };
+}
+/**
+ * The empty-lookup check's PRODUCER CORPUS (9.77.0) — every `role: 'tool'`
+ * RESULT in `history` from a tool the judged one names in `argumentsFrom`,
+ * as the run served it. The caller hands the history the judged call was
+ * served (the call itself is pushed after it), so a producer called earlier in
+ * the same batch is already in it — which is right: the model can only have
+ * taken a value from a result it had already been served.
+ *
+ * A message the batch settlement wrote (9.113.0) is no result: its ground
+ * never ran, so it produced nothing to take a value from. Read off the marker
+ * (`../findings/offer.ts` · `isResultMessage`), never the sentence.
+ *
+ * Exported for its unit test (`test/integrity/emptyLookup.test.ts`).
+ */
+export function producerCorpusOf(history, argumentsFrom) {
+    const produced = [];
+    for (const message of history) {
+        if (!isResultMessage(message))
+            continue;
+        const name = message.toolName;
+        if (typeof name !== 'string' || !argumentsFrom.includes(name))
+            continue;
+        produced.push({ toolName: name, text: message.content });
+    }
+    return produced;
+}
 /**
  * The judge's turn on ONE landed result (9.104.0) — called at the five
  * places a result joins the batch (the execute loop and the four resume
@@ -710,6 +835,13 @@ export function buildToolCallsHandler(deps) {
                     checked,
                     ...(notChecked.length > 0 && { notChecked }),
                     ...(cannotCover.length > 0 && { cannotCover }),
+                    // The suggestion, as declared (9.113.0): the sentence, and the
+                    // typed tool as a copy (`tryInsteadToolOfAbsence`). The EVENT only:
+                    // it is advice about a call not yet made, not ground the answer
+                    // stands on, so the tracked row below and the block composed from
+                    // it never carry it.
+                    ...(facts.tryInstead !== undefined && { tryInstead: facts.tryInstead }),
+                    ...(facts.tryInsteadTool !== undefined && { tryInsteadTool: facts.tryInsteadTool }),
                 });
             }
             else {
@@ -777,20 +909,9 @@ export function buildToolCallsHandler(deps) {
             ledger?.note('empty-lookup', 'write', 'not-applicable');
             return;
         }
-        // The producer corpus: every earlier `role: 'tool'` message from a tool
-        // THIS tool declares as one of its grounds. `history` here excludes the
-        // call being judged (it is pushed after), and a producer called earlier
-        // in the same batch is already in it — which is right: the model can only
-        // have taken a value from a result it had already been served.
-        const produced = [];
-        for (const message of history) {
-            if (message.role !== 'tool')
-                continue;
-            const name = message.toolName;
-            if (typeof name !== 'string' || !argumentsFrom.includes(name))
-                continue;
-            produced.push({ toolName: name, text: message.content });
-        }
+        // The producer corpus: the earlier RESULTS from a tool THIS tool declares
+        // as one of its grounds — never a settled message (`producerCorpusOf`).
+        const produced = producerCorpusOf(history, argumentsFrom);
         const { findings, disposition } = emptyLookupOf({
             toolName: call.toolName,
             toolCallId: call.toolCallId,
@@ -805,6 +926,45 @@ export function buildToolCallsHandler(deps) {
         ledger?.note('empty-lookup', 'write', disposition, disposition === 'checked-fail' ? Date.now() : undefined);
         fileIntegrityFindings(scope, findings, call.iteration);
     };
+    /**
+     * A lookup that pauses still declares what it looked at (9.114.0) — the
+     * RAISE-SITE reader of `InputRequestDeclaration.absence`.
+     *
+     * A tool that found nothing and raised `requestInput` about the miss used
+     * to leave no record of it: `declareCoverage` reads a RETURNED value, and
+     * the pause branch returns the checkpoint before any of its call sites.
+     * The app could not file it either — the declaration's `context` rides to
+     * the model on resume, never to the record. So the raise site files it,
+     * through the same two readers a returned absence meets: `declareCoverage`
+     * (the one recognizer, `tools.absent`, the `coverageDeclared` row — the
+     * bytes a returned `absent(…)` files) and the empty-lookup write seam, with
+     * the envelope as the tool's own answer — it ran, nothing errored, nothing
+     * denied it, and no ceiling judged a result the model was never served.
+     *
+     * The delivered status `declareCoverage` returns is dropped on purpose: a
+     * paused call is not settled, so there is no `tool_end` for it to ride.
+     * Nothing on resume reads the field (the served result there is the
+     * person's `InputResponseResult`), so the rows are filed once, here.
+     *
+     * CONTAINED the way the returned path contains it. The recognizer reads an
+     * envelope minted elsewhere without repairing it, so its lists can be
+     * something `declareCoverage` cannot copy (`checked: [null]`,
+     * `not_checked: 5`). Returned, that throw lands in the dispatch `try` and
+     * errors the call; here it would land in the `catch` and fail the run. So
+     * the copy is caught here instead, and the error text comes back: the
+     * caller errors the call with it and does not pause. That is what the same
+     * value returned would do. `undefined` means filed.
+     */
+    const declareRaisedAbsence = (scope, call, args, absence, history) => {
+        try {
+            declareCoverage(scope, call, absence);
+        }
+        catch (err) {
+            return err instanceof Error ? err.message : String(err);
+        }
+        noticeEmptyLookup(scope, call, args, absence, history, true);
+        return undefined;
+    };
     /**
      * The semantic envelope (9.53.0) — recognized at the SAME execute
      * boundaries as coverage and the ceiling (one implementation, every door),
@@ -1999,6 +2159,68 @@ export function buildToolCallsHandler(deps) {
         recordDecisions(scope, verdict.decisions);
         return verdict.kind === 'deny' ? verdict.reason : verdict.result;
     };
+    const settleBatch = (answered, paused) => {
+        const batch = pausedBatchOf(answered, paused.toolCallId);
+        if (batch.undispatched.length === 0)
+            return { history: answered, settled: [], size: batch.size, paused };
+        const settled = batch.undispatched.map((call) => ({
+            call,
+            result: notDispatchedResult(call.name, paused),
+        }));
+        return {
+            history: [
+                ...answered,
+                ...settled.map(({ call, result }) => ({
+                    role: 'tool',
+                    content: result,
+                    toolCallId: call.id,
+                    toolName: call.name,
+                    notDispatched: notDispatchedMarker(paused),
+                })),
+            ],
+            settled,
+            size: batch.size,
+            paused,
+        };
+    };
+    /**
+     * Each settled sibling's bracket, after the paused call's own `tool_end` —
+     * the ONE site that stamps `notDispatched` on the stream: `tool_start` with
+     * the args the call would have run with (the batch loop's peel, so
+     * `_findings` never shows on a bracket), then `tool_end` carrying the
+     * sentence and `durationMs: 0`. Both carry the marker the history message
+     * carries (`notDispatchedMarker`), and no other bracket in the library ever
+     * does.
+     *
+     * No `error`. It says a call FAILED — the tool threw, or the call itself
+     * could not run as written (an args rejection, a `wants` block, a consent
+     * the tool needed and did not get, an unknown name). A settled call did not
+     * fail: the library decided not to dispatch it, as it does for a call a
+     * permission policy denies or halts, and those brackets carry no `error`
+     * either. Stamped here, it would register a tool failure in every
+     * error-rate reader (a span status, a dashboard, an alert) on every
+     * mid-batch pause, and say a second, false thing beside the marker, which
+     * is the one owner of why there is no result (`src/core/README.md` · "One
+     * owner of 'never dispatched' — in history and on the stream", the reader
+     * table). No `status` either: that field is the TOOL's own word.
+     */
+    const bracketSettled = (scope, settlement) => {
+        for (const { call, result } of settlement.settled) {
+            typedEmit(scope, 'agentfootprint.stream.tool_start', {
+                toolName: call.name,
+                toolCallId: call.id,
+                args: peelCall(call).args,
+                parallelCount: settlement.size,
+                notDispatched: notDispatchedMarker(settlement.paused),
+            });
+            typedEmit(scope, 'agentfootprint.stream.tool_end', {
+                toolCallId: call.id,
+                result,
+                durationMs: 0,
+                notDispatched: notDispatchedMarker(settlement.paused),
+            });
+        }
+    };
     // Resolve a tool's declared credential (declare-and-push) and execute it,
     // emitting the same credential.* events as the main loop. Used by the
     // check-in RESUME path when a human APPROVES — the tool never ran at pause
@@ -2324,15 +2546,24 @@ export function buildToolCallsHandler(deps) {
             // came from (9.102.0; before, only the last batch resolved and an
             // offered older id filed as `unknownId`). Read through the same
             // per-call peel the loop below applies (a tool that owns the name
-            // declares nothing). Gated: unarmed, not one line runs.
+            // declares nothing). A ruled-out standing whose result THIS door
+            // recorded as an absence (`declareCoverage`'s rows on
+            // `coverageDeclared`, never a second reading of a return) AND the
+            // model was served as one (the served string — the door records the
+            // return before the after-tool chain, the ceiling and placement act,
+            // so a denied, refused or ticketed result files nothing) gets its
+            // `unsettled-by-absence` row immediately after it, in the same write,
+            // worded from what was served (9.113.0, `findings/unsettled.ts`; the
+            // key is read only for such a standing); the standing rows pass
+            // through untouched. Gated: unarmed, not one line runs.
             if (deps.findings === true) {
                 const known = knownResults([...(scope.history ?? [])], [...(scope.toolResults ?? [])]);
-                recordFindings(scope, toolCalls.flatMap((tc) => {
+                recordFindings(scope, withUnsettledRows(toolCalls.flatMap((tc) => {
                     const declared = peelCall(tc).findings;
                     return declared?.previous !== undefined
                         ? standingRowsFrom(known, declared, { toolCallId: tc.id }, iteration)
                         : [];
-                }));
+                }), known, () => [...(scope.coverageDeclared ?? [])]));
             }
             scope.toolResults = [];
             // ── THE TOWERS AT DISPATCH (9.110.0) — one corpus per batch ────────
@@ -3065,6 +3296,9 @@ export function buildToolCallsHandler(deps) {
                             await endCall(tc.id);
                         }
                         catch (err) {
+                            // Set when a raise declared a miss the door could not file:
+                            // the call then errors with this text and does not pause.
+                            let raisedMissError;
                             if (isPauseRequest(err)) {
                                 // The typed half of the question (9.24.0): a tool that raised
                                 // `askHuman({ question, component })` nominated a screen
@@ -3082,51 +3316,90 @@ export function buildToolCallsHandler(deps) {
                                         await assertComponentDeliverable(scope, tc.name, rawComponent, `askHuman in tool '${tc.name}'`);
                                     }
                                 }
-                                // A pause has NOT settled this call — it is waiting for a
-                                // person, and the resources it opened are what the resume
-                                // needs. No `'call'` teardown here, deliberately.
-                                //
-                                // Commit partial state so resume() can find history intact.
-                                scope.history = newHistory;
-                                scope.pausedToolCallId = tc.id;
-                                scope.pausedToolName = tc.name;
-                                scope.pausedToolStartMs = startMs;
-                                // The args the tool WAS RUNNING WITH (post-transform), for the
-                                // after-tool moment on the far side of the pause (8.13.0) —
-                                // the same reason the three sibling pauses carry theirs.
-                                scope.pausedToolArgs = callArgs;
                                 const declaration = typeof err.data === 'object' && err.data !== null
                                     ? err.data.inputRequest
                                     : undefined;
-                                const awaitingInput = declaration === undefined
-                                    ? undefined
-                                    : stampInputRequest(validateInputDeclaration(declaration), `${deps.currentRun?.().runId ?? scope.turnStartMs}:${tc.id}`, {
-                                        originalRequest: scope.userMessage,
-                                        toolCallId: tc.id,
-                                        ...(scope.currentSkillId !== undefined && {
-                                            skillId: scope.currentSkillId,
-                                        }),
-                                        ...(scope.turnRoute?.offered !== undefined && {
-                                            offeredSkillIds: [...scope.turnRoute.offered],
-                                        }),
-                                    });
-                                // Returning a defined value triggers footprintjs pause —
-                                // the returned object becomes the checkpoint's pauseData.
-                                return {
-                                    toolCallId: tc.id,
-                                    toolName: tc.name,
-                                    ...(awaitingInput !== undefined
-                                        ? { question: awaitingInput.question, awaitingInput }
-                                        : typeof err.data === 'object' && err.data !== null
-                                            ? err.data
-                                            : { data: err.data }),
+                                // A lookup that pauses still declares what it looked at
+                                // (9.114.0): the miss it is asking about is filed HERE, the
+                                // raise site, FIRST — the one moment the declaration's
+                                // `absence` is read. So a declaration that CARRIES one is
+                                // judged before anything is written for the pause, and a miss
+                                // the door cannot file errors the call below, as the same value
+                                // returned would, with nothing written for a pause. A MALFORMED
+                                // declaration still leaves the committed record it always left,
+                                // whether or not it carried `absence`: its error leaves the
+                                // stage only after the pause writes are made, so a hand-raised
+                                // request (a `pauseHere`/`askHuman` that never went through
+                                // `requestInput`) fails with the in-flight batch on the record.
+                                // `null` is the field omitted (`inputRequest.ts` ·
+                                // `validateInputDeclaration`).
+                                //
+                                // The pause writes: partial state, so resume() can find the
+                                // history intact.
+                                const writePause = () => {
+                                    scope.history = newHistory;
+                                    scope.pausedToolCallId = tc.id;
+                                    scope.pausedToolName = tc.name;
+                                    scope.pausedToolStartMs = startMs;
+                                    // The args the tool WAS RUNNING WITH (post-transform), for
+                                    // the after-tool moment on the far side of the pause
+                                    // (8.13.0) — the same reason the three sibling pauses carry
+                                    // theirs.
+                                    scope.pausedToolArgs = callArgs;
                                 };
+                                const carriesAbsence = typeof declaration === 'object' &&
+                                    declaration !== null &&
+                                    declaration.absence != null;
+                                let declared;
+                                if (carriesAbsence) {
+                                    try {
+                                        declared = validateInputDeclaration(declaration);
+                                    }
+                                    catch (invalid) {
+                                        writePause();
+                                        throw invalid;
+                                    }
+                                }
+                                raisedMissError =
+                                    declared?.absence === undefined
+                                        ? undefined
+                                        : declareRaisedAbsence(scope, { toolName: tc.name, toolCallId: tc.id, iteration }, callArgs, declared.absence, newHistory);
+                                if (raisedMissError === undefined) {
+                                    // A pause has NOT settled this call — it is waiting for a
+                                    // person, and the resources it opened are what the resume
+                                    // needs. No `'call'` teardown here, deliberately.
+                                    writePause();
+                                    const awaitingInput = declaration === undefined
+                                        ? undefined
+                                        : stampInputRequest(declared ?? validateInputDeclaration(declaration), `${deps.currentRun?.().runId ?? scope.turnStartMs}:${tc.id}`, {
+                                            originalRequest: scope.userMessage,
+                                            toolCallId: tc.id,
+                                            ...(scope.currentSkillId !== undefined && {
+                                                skillId: scope.currentSkillId,
+                                            }),
+                                            ...(scope.turnRoute?.offered !== undefined && {
+                                                offeredSkillIds: [...scope.turnRoute.offered],
+                                            }),
+                                        });
+                                    // Returning a defined value triggers footprintjs pause —
+                                    // the returned object becomes the checkpoint's pauseData.
+                                    return {
+                                        toolCallId: tc.id,
+                                        toolName: tc.name,
+                                        ...(awaitingInput !== undefined
+                                            ? { question: awaitingInput.question, awaitingInput }
+                                            : typeof err.data === 'object' && err.data !== null
+                                                ? err.data
+                                                : { data: err.data }),
+                                    };
+                                }
                             }
                             // A tool that threw still RAN, and may have opened the thing it
-                            // was about to close.
+                            // was about to close. A raise whose miss could not be filed is
+                            // settled here too — the returned path's error, not a pause.
                             await endCall(tc.id);
                             error = true;
-                            result = err instanceof Error ? err.message : String(err);
+                            result = raisedMissError ?? (err instanceof Error ? err.message : String(err));
                         }
                     }
                 }
@@ -3904,10 +4177,13 @@ export function buildToolCallsHandler(deps) {
                     askResultStr += applyToolEffects(scope, { toolName, toolCallId, iteration }, resumeEnvelope, askTransition);
                     emitTransitionConflict(scope, iteration, askTransition);
                 }
-                const askHistory = [
+                // The batch settlement (9.113.0): the answered call's result, then the
+                // siblings the pause left un-dispatched, each settled — never run.
+                const askSettlement = settleBatch([
                     ...scope.history,
                     { role: 'tool', content: askResultStr, toolCallId, toolName },
-                ];
+                ], { toolName, toolCallId });
+                const askHistory = askSettlement.history;
                 scope.history = askHistory;
                 scope.lastToolResult = {
                     toolName,
@@ -3928,10 +4204,14 @@ export function buildToolCallsHandler(deps) {
                     ...(error === true && { error: true }),
                     ...(resumeEnvelope?.status !== undefined && { status: resumeEnvelope.status }),
                 });
+                bracketSettled(scope, askSettlement);
                 typedEmit(scope, 'agentfootprint.agent.iteration_end', {
                     turnIndex: 0,
                     iterIndex: iteration,
-                    toolCallCount: 1,
+                    // The brackets THIS leg closed: the answered call's, plus one per
+                    // settled sibling. The calls before the paused one closed theirs on
+                    // the leg that paused, which ended in a checkpoint, not here.
+                    toolCallCount: 1 + askSettlement.settled.length,
                     history: askHistory,
                 });
                 scope.iteration = iteration + 1;
@@ -4048,10 +4328,12 @@ export function buildToolCallsHandler(deps) {
                     decisionResultStr += applyToolEffects(scope, { toolName, toolCallId, iteration }, resumeEnvelope, decisionTransition);
                     emitTransitionConflict(scope, iteration, decisionTransition);
                 }
-                const decisionHistory = [
+                // The batch settlement (9.113.0) — the ask path's twin.
+                const decisionSettlement = settleBatch([
                     ...scope.history,
                     { role: 'tool', content: decisionResultStr, toolCallId, toolName },
-                ];
+                ], { toolName, toolCallId });
+                const decisionHistory = decisionSettlement.history;
                 scope.history = decisionHistory;
                 // Drives `on-tool-return` triggers, same as the execute path.
                 scope.lastToolResult = {
@@ -4073,10 +4355,12 @@ export function buildToolCallsHandler(deps) {
                     ...(error === true && { error: true }),
                     ...(resumeEnvelope?.status !== undefined && { status: resumeEnvelope.status }),
                 });
+                bracketSettled(scope, decisionSettlement);
                 typedEmit(scope, 'agentfootprint.agent.iteration_end', {
                     turnIndex: 0,
                     iterIndex: iteration,
-                    toolCallCount: 1,
+                    // The brackets this leg closed — see the ask path's twin.
+                    toolCallCount: 1 + decisionSettlement.settled.length,
                     history: decisionHistory,
                 });
                 scope.iteration = iteration + 1;
@@ -4158,10 +4442,12 @@ export function buildToolCallsHandler(deps) {
                     consentResultStr += applyToolEffects(scope, { toolName, toolCallId, iteration }, consentEnvelope, consentTransition);
                     emitTransitionConflict(scope, iteration, consentTransition);
                 }
-                const consentHistory = [
+                // The batch settlement (9.113.0) — the ask path's twin.
+                const consentSettlement = settleBatch([
                     ...scope.history,
                     { role: 'tool', content: consentResultStr, toolCallId, toolName },
-                ];
+                ], { toolName, toolCallId });
+                const consentHistory = consentSettlement.history;
                 scope.history = consentHistory;
                 scope.lastToolResult = {
                     toolName,
@@ -4182,10 +4468,12 @@ export function buildToolCallsHandler(deps) {
                     ...(error === true && { error: true }),
                     ...(consentEnvelope?.status !== undefined && { status: consentEnvelope.status }),
                 });
+                bracketSettled(scope, consentSettlement);
                 typedEmit(scope, 'agentfootprint.agent.iteration_end', {
                     turnIndex: 0,
                     iterIndex: iteration,
-                    toolCallCount: 1,
+                    // The brackets this leg closed — see the ask path's twin.
+                    toolCallCount: 1 + consentSettlement.settled.length,
                     history: consentHistory,
                 });
                 scope.iteration = iteration + 1;
@@ -4263,7 +4551,10 @@ export function buildToolCallsHandler(deps) {
             if (deps.stepPlanFor) {
                 resultStr += applyStepReturn(scope, { toolName, toolCallId, iteration });
             }
-            const newHistory = [
+            // The batch settlement (9.113.0) — the door a `requestInput` answer
+            // comes back through, and the one most likely to meet a batch: a tool
+            // that asks a person mid-lookup, batched with the lookups after it.
+            const pauseSettlement = settleBatch([
                 ...scope.history,
                 {
                     role: 'tool',
@@ -4271,7 +4562,8 @@ export function buildToolCallsHandler(deps) {
                     toolCallId,
                     toolName,
                 },
-            ];
+            ], { toolName, toolCallId });
+            const newHistory = pauseSettlement.history;
             scope.history = newHistory;
             // Drives `on-tool-return` triggers, same as every other dispatch path.
             scope.lastToolResult = { toolName, result: resultStr };
@@ -4287,10 +4579,12 @@ export function buildToolCallsHandler(deps) {
                 result: pauseCapped.result,
                 durationMs: Date.now() - startMs,
             });
+            bracketSettled(scope, pauseSettlement);
             typedEmit(scope, 'agentfootprint.agent.iteration_end', {
                 turnIndex: 0,
                 iterIndex: iteration,
-                toolCallCount: 1,
+                // The brackets this leg closed — see the ask path's twin.
+                toolCallCount: 1 + pauseSettlement.settled.length,
                 // Plain local array — see the matching note on the execute path.
                 history: newHistory,
             });