agentfootprint 7.17.0 → 7.19.0

package/dist/core/agent/stages/seed.js

@@ -20,100 +20,145 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildSeedStage = void 0;
 const typedEmit_js_1 = require("../../../recorders/core/typedEmit.js");
+const runChain_js_1 = require("../middleware/runChain.js");
+const ledger_js_1 = require("../middleware/ledger.js");
 /**
  * Build the seed stage function for an Agent instance. Captures both
  * the chart-build-time constants and the per-run mutable accessors
  * via the deps object.
  */
 function buildSeedStage(deps) {
-    return (scope) => {
-        const args = scope.$getArgs();
-        scope.userMessage = args.message;
-        // If `resumeOnError(...)` set the side channel, restore the
-        // checkpointed conversation history. The next iteration sees
-        // the prior messages and continues from the failure point.
-        // Always clear the field after reading so subsequent runs
-        // (without resumeOnError) start fresh.
-        const resumeHistory = deps.consumePendingResumeHistory();
-        if (resumeHistory && resumeHistory.length > 0) {
-            scope.history = [...resumeHistory];
-        }
-        else {
-            scope.history = [{ role: 'user', content: args.message }];
-        }
-        // Default identity uses the runId so multi-run isolation works
-        // without consumer changes; explicit identity (multi-tenant)
-        // overrides via `agent.run({ identity })`.
-        scope.runIdentity = args.identity ?? {
-            conversationId: deps.getCurrentRunId() ?? 'default',
+    const chain = deps.messageMiddleware ?? [];
+    // No chain → the same synchronous function this stage has always been.
+    // Not an optimisation: an agent without middleware must produce the same
+    // stage shape, the same committed keys and the same request bytes as before.
+    if (chain.length === 0) {
+        return (scope) => {
+            seedFrom(scope, scope.$getArgs().message, deps);
         };
-        scope.newMessages = [];
-        scope.turnNumber = 1;
-        // Permissive default — explicit cap will land when PricingTable
-        // gets a context-window field. Memory pickByBudget treats anything
-        // ≥ minimumTokens as "fits", so this just enables the budget path.
-        scope.contextTokensRemaining = 32_000;
-        scope.iteration = 1;
-        scope.maxIterations = deps.maxIterations;
-        scope.finalContent = '';
-        scope.totalInputTokens = 0;
-        scope.totalOutputTokens = 0;
-        scope.turnStartMs = Date.now();
-        scope.systemPromptInjections = [];
-        scope.messagesInjections = [];
-        scope.toolsInjections = [];
-        scope.llmLatestContent = '';
-        scope.llmLatestToolCalls = [];
-        // v2.14 — initialize thinking blocks. Empty array means "no thinking
-        // this iteration"; the NormalizeThinking sub-subflow overwrites
-        // this AFTER each CallLLM when a ThinkingHandler is configured.
-        scope.thinkingBlocks = [];
-        scope.pausedToolCallId = '';
-        scope.pausedToolName = '';
-        scope.pausedToolStartMs = 0;
-        scope.cumTokensInput = 0;
-        scope.cumTokensOutput = 0;
-        scope.cumEstimatedUsd = 0;
-        scope.costBudgetHit = false;
-        scope.activeInjections = [];
-        scope.activatedInjectionIds = [];
-        scope.dynamicToolSchemas = deps.toolSchemas;
-        // Cache layer state (v2.6) — initialized to inert defaults.
-        // CacheDecision subflow populates `cacheMarkers` per iteration;
-        // UpdateSkillHistory + CacheGate consume `cachingDisabled`,
-        // `recentHitRate`, `skillHistory`. Empty defaults mean the
-        // CacheGate falls through to 'apply-markers' on iter 1 (no
-        // history yet → no churn detected; recentHitRate undefined →
-        // hit-rate floor doesn't fire).
-        scope.cacheMarkers = [];
-        scope.cachingDisabled = deps.cachingDisabled;
-        scope.recentHitRate = undefined;
-        scope.skillHistory = [];
-        // Skill-graph cursor — reset per turn so each new user message re-enters the
-        // graph through the entry router (cold start). The Injection Engine advances
-        // it each iteration; undefined for agents without a skillGraph().
-        scope.currentSkillId = undefined;
-        // `.configure()` — resolved ONCE here (seed runs exactly once per run)
-        // and written to scope, which means the run's commit log records the
-        // model and instructions the run actually used. A run that changed its
-        // own model without committing that fact would produce a trace that
-        // reads as if the built-in default answered.
-        //
-        // Only what the resolver actually returned is written: an agent with no
-        // `.configure()`, or one whose resolver returned `{}`, commits nothing
-        // extra and behaves exactly as before.
-        if (deps.resolveRunConfig) {
-            const resolved = deps.resolveRunConfig(args);
-            if (resolved?.model !== undefined)
-                scope.resolvedModel = resolved.model;
-            if (resolved?.instructions !== undefined)
-                scope.resolvedInstructions = resolved.instructions;
-        }
-        (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.agent.turn_start', {
-            turnIndex: 0,
-            userPrompt: args.message,
+    }
+    return async (scope) => {
+        const args = scope.$getArgs();
+        const verdict = await (0, runChain_js_1.runMessageChain)(chain, {
+            phase: 'input',
+            content: args.message,
+            history: [],
+            // The input boundary runs before iteration 1 exists.
+            iteration: 0,
+            ...(args.identity && { identity: args.identity }),
         });
+        (0, ledger_js_1.recordDecisions)(scope, verdict.decisions);
+        if (verdict.kind === 'deny') {
+            // Seed the run anyway, with the content as it stood when it was
+            // refused, then stop. Committing it costs nothing (a refusal is a fact
+            // about a run, and hiding what was refused would make the record
+            // useless), and a fully-seeded state means `resumeOnError` and every
+            // recorder see the shape they expect rather than a half-built one.
+            seedFrom(scope, verdict.content, deps);
+            scope.messageDeniedReason = verdict.reason;
+            scope.messageDeniedPhase = 'input';
+            scope.messageDeniedBy = verdict.middleware;
+            // Stops the chart here: no injections, no slots, no LLM call. The
+            // boundary turns these flags into a MessageDeniedError.
+            scope.$break(`message denied at input: ${verdict.reason}`);
+            return;
+        }
+        seedFrom(scope, verdict.content, deps);
     };
 }
 exports.buildSeedStage = buildSeedStage;
+/**
+ * Initialise every mutable field of `AgentState` from `message` + the run
+ * args. Split out so the message the run proceeds with can come either
+ * straight from the caller or from the `'input'` middleware chain — one
+ * initialiser, so the two paths cannot drift.
+ */
+function seedFrom(scope, message, deps) {
+    const args = scope.$getArgs();
+    scope.userMessage = message;
+    // If `resumeOnError(...)` set the side channel, restore the
+    // checkpointed conversation history. The next iteration sees
+    // the prior messages and continues from the failure point.
+    // Always clear the field after reading so subsequent runs
+    // (without resumeOnError) start fresh.
+    const resumeHistory = deps.consumePendingResumeHistory();
+    if (resumeHistory && resumeHistory.length > 0) {
+        scope.history = [...resumeHistory];
+    }
+    else {
+        scope.history = [{ role: 'user', content: message }];
+    }
+    // Default identity uses the runId so multi-run isolation works
+    // without consumer changes; explicit identity (multi-tenant)
+    // overrides via `agent.run({ identity })`.
+    scope.runIdentity = args.identity ?? {
+        conversationId: deps.getCurrentRunId() ?? 'default',
+    };
+    scope.newMessages = [];
+    scope.turnNumber = 1;
+    // Permissive default — explicit cap will land when PricingTable
+    // gets a context-window field. Memory pickByBudget treats anything
+    // ≥ minimumTokens as "fits", so this just enables the budget path.
+    scope.contextTokensRemaining = 32_000;
+    scope.iteration = 1;
+    scope.maxIterations = deps.maxIterations;
+    scope.finalContent = '';
+    scope.totalInputTokens = 0;
+    scope.totalOutputTokens = 0;
+    scope.turnStartMs = Date.now();
+    scope.systemPromptInjections = [];
+    scope.messagesInjections = [];
+    scope.toolsInjections = [];
+    scope.llmLatestContent = '';
+    scope.llmLatestToolCalls = [];
+    // v2.14 — initialize thinking blocks. Empty array means "no thinking
+    // this iteration"; the NormalizeThinking sub-subflow overwrites
+    // this AFTER each CallLLM when a ThinkingHandler is configured.
+    scope.thinkingBlocks = [];
+    scope.pausedToolCallId = '';
+    scope.pausedToolName = '';
+    scope.pausedToolStartMs = 0;
+    scope.cumTokensInput = 0;
+    scope.cumTokensOutput = 0;
+    scope.cumEstimatedUsd = 0;
+    scope.costBudgetHit = false;
+    scope.activeInjections = [];
+    scope.activatedInjectionIds = [];
+    scope.dynamicToolSchemas = deps.toolSchemas;
+    // Cache layer state (v2.6) — initialized to inert defaults.
+    // CacheDecision subflow populates `cacheMarkers` per iteration;
+    // UpdateSkillHistory + CacheGate consume `cachingDisabled`,
+    // `recentHitRate`, `skillHistory`. Empty defaults mean the
+    // CacheGate falls through to 'apply-markers' on iter 1 (no
+    // history yet → no churn detected; recentHitRate undefined →
+    // hit-rate floor doesn't fire).
+    scope.cacheMarkers = [];
+    scope.cachingDisabled = deps.cachingDisabled;
+    scope.recentHitRate = undefined;
+    scope.skillHistory = [];
+    // Skill-graph cursor — reset per turn so each new user message re-enters the
+    // graph through the entry router (cold start). The Injection Engine advances
+    // it each iteration; undefined for agents without a skillGraph().
+    scope.currentSkillId = undefined;
+    // `.configure()` — resolved ONCE here (seed runs exactly once per run)
+    // and written to scope, which means the run's commit log records the
+    // model and instructions the run actually used. A run that changed its
+    // own model without committing that fact would produce a trace that
+    // reads as if the built-in default answered.
+    //
+    // Only what the resolver actually returned is written: an agent with no
+    // `.configure()`, or one whose resolver returned `{}`, commits nothing
+    // extra and behaves exactly as before.
+    if (deps.resolveRunConfig) {
+        const resolved = deps.resolveRunConfig(args);
+        if (resolved?.model !== undefined)
+            scope.resolvedModel = resolved.model;
+        if (resolved?.instructions !== undefined)
+            scope.resolvedInstructions = resolved.instructions;
+    }
+    (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.agent.turn_start', {
+        turnIndex: 0,
+        userPrompt: message,
+    });
+}
 //# sourceMappingURL=seed.js.map

package/dist/core/agent/stages/seed.js.map

@@ -1 +1 @@
-{"version":3,"file":"seed.js","sourceRoot":"","sources":["../../../../src/core/agent/stages/seed.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"seed.js","sourceRoot":"","sources":["../../../../src/core/agent/stages/seed.ts"],"names":[],"mappings":"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"}

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

@@ -21,6 +21,19 @@
  * `tool.execute`. Deny → tool not executed; result is a synthetic
  * denial string. Allow / gate_open → execution proceeds.
  *
+ * Gate order for one call, and why it is this order:
+ *
+ *   permission → MIDDLEWARE CHAIN → arg validation → check-in →
+ *   credentials → execute
+ *
+ * The chain sits after the permission gate so an existing checker still
+ * decides first (a denial there means no middleware runs), and before arg
+ * validation so validation judges the args that will actually be sent —
+ * a middleware that transformed args into something the tool's schema
+ * rejects must be caught, not forwarded. A middleware answering `ask`
+ * pauses on the SAME wire `checkIn` uses; the human's answer is a
+ * decision, not a result, so the chain resumes and the REAL tool runs.
+ *
  * `read_skill` is the auto-attached activation tool — when the LLM
  * calls it with a valid Skill id, the next InjectionEngine pass
  * activates that Skill (lifetime: turn).
@@ -32,6 +45,8 @@ const extractSequence_js_1 = require("../../../security/extractSequence.js");
 const types_js_1 = require("../../../identity/types.js");
 const pause_js_1 = require("../../pause.js");
 const checkin_js_1 = require("../../checkin.js");
+const runChain_js_1 = require("../middleware/runChain.js");
+const ledger_js_1 = require("../middleware/ledger.js");
 const toolArgsValidation_js_1 = require("../toolArgsValidation.js");
 const validators_js_1 = require("../validators.js");
 /**
@@ -136,6 +151,13 @@ function buildToolCallsHandler(deps) {
     };
     return {
         execute: async (scope) => {
+            // Durable-write barrier — the LAST iteration's state must have landed in
+            // the session store before THIS iteration's tools are allowed to run.
+            // `undefined` (no composer, or nothing outstanding) means no await, no
+            // microtask, no behaviour change whatsoever.
+            const durable = deps.awaitDurable?.();
+            if (durable)
+                await durable;
             // Materialize ONCE — `scope.llmLatestToolCalls` is a live TypedScope
             // deep-Proxy view; spreading yields the raw (plain, structured-clone-
             // safe) elements. This array is embedded into the assistant history
@@ -205,6 +227,12 @@ function buildToolCallsHandler(deps) {
                 // identity, and abort signal — enough surface to build sequence-
                 // aware policies (forbidden chains, idempotency limits, cost
                 // guards) without maintaining parallel state.
+                // Args as they will actually be used. The middleware chain below may
+                // replace this; everything downstream (validation, the check-in
+                // evidence a human approves, credentials, execute, the read_skill
+                // gate) reads `callArgs`, never `tc.args`, so there is exactly one
+                // answer to "what did this call really run with".
+                let callArgs = tc.args;
                 let denied = false;
                 let haltContext;
                 if (permissionChecker) {
@@ -271,6 +299,52 @@ function buildToolCallsHandler(deps) {
                         result = `[permission denied: checker error: ${msg}]`;
                     }
                 }
+                // ── The middleware chain ─────────────────────────────────────────
+                // Walked only for a call the permission gate let through, so an
+                // existing checker keeps deciding first and a denial there costs
+                // nothing. A denial from the chain lands as the tool result, exactly
+                // like every other refusal in this loop — the model reads it and
+                // adapts. An `ask` commits partial state and pauses, on the same wire
+                // the check-in gate uses.
+                if (!denied && deps.toolMiddleware && deps.toolMiddleware.length > 0) {
+                    const chain = await (0, runChain_js_1.runToolChain)(deps.toolMiddleware, {
+                        toolName: tc.name,
+                        toolCallId: tc.id,
+                        iteration,
+                        args: callArgs,
+                        history: newHistory,
+                        ...(runIdentity && { identity: runIdentity }),
+                        ...(env.signal && { signal: env.signal }),
+                    });
+                    (0, ledger_js_1.recordDecisions)(scope, chain.decisions);
+                    callArgs = chain.args;
+                    if (chain.kind === 'deny') {
+                        denied = true;
+                        result = chain.reason;
+                    }
+                    else if (chain.kind === 'ask') {
+                        // Commit partial state so resume() finds history intact (the
+                        // pauseHere / check-in path does the same). The TRANSFORMED args
+                        // ride the checkpoint: a person approves what the chain produced,
+                        // not what the model originally proposed.
+                        scope.history = newHistory;
+                        scope.pausedToolCallId = tc.id;
+                        scope.pausedToolName = tc.name;
+                        scope.pausedToolStartMs = startMs;
+                        scope.pausedAsk = true;
+                        scope.pausedAskArgs = chain.args;
+                        scope.pausedAskIndex = chain.index;
+                        scope.pausedAskMiddleware = chain.middleware;
+                        // A defined return value triggers the footprintjs pause; this
+                        // object becomes the checkpoint's pauseData, and detectPause
+                        // surfaces `pauseData.ask` as `outcome.ask`.
+                        return {
+                            toolCallId: tc.id,
+                            toolName: tc.name,
+                            ask: { ...chain.payload, middleware: chain.middleware },
+                        };
+                    }
+                }
                 // Tool-args validation (#9) — AFTER the permission gate (policy must
                 // see every attempted call, valid or not) and BEFORE credential
                 // resolution (never acquire credentials for a call that won't run).
@@ -281,7 +355,7 @@ function buildToolCallsHandler(deps) {
                 // tools (their inputSchema is the contract the LLM was shown).
                 let argsRejected = false;
                 if (!denied && tool && toolArgValidation !== 'off') {
-                    const verdict = (0, toolArgsValidation_js_1.validateToolArgs)(tc.args, tool.schema.inputSchema);
+                    const verdict = (0, toolArgsValidation_js_1.validateToolArgs)(callArgs, tool.schema.inputSchema);
                     if (!verdict.ok) {
                         (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.validation.args_invalid', {
                             toolName: tc.name,
@@ -319,7 +393,7 @@ function buildToolCallsHandler(deps) {
                     const historyForEvidence = systemPrompt
                         ? [{ role: 'system', content: systemPrompt }, ...newHistory]
                         : newHistory;
-                    if (!(0, checkin_js_1.shouldCheckIn)(tool.checkIn, tc.args, {
+                    if (!(0, checkin_js_1.shouldCheckIn)(tool.checkIn, callArgs, {
                         iteration,
                         toolCallId: tc.id,
                         history: historyForEvidence,
@@ -331,7 +405,7 @@ function buildToolCallsHandler(deps) {
                         const intent = scope.llmLatestContent ? String(scope.llmLatestContent) : undefined;
                         const evidence = await deps.checkIn.assembler({
                             tool: { name: tc.name, description: tool.schema.description },
-                            args: tc.args,
+                            args: callArgs,
                             ...(intent !== undefined && { intent }),
                             iteration,
                             history: historyForEvidence,
@@ -340,7 +414,7 @@ function buildToolCallsHandler(deps) {
                         });
                         const request = {
                             tool: tc.name,
-                            args: tc.args,
+                            args: callArgs,
                             ...(intent !== undefined && { intent }),
                             evidence,
                         };
@@ -358,7 +432,7 @@ function buildToolCallsHandler(deps) {
                         scope.pausedToolName = tc.name;
                         scope.pausedToolStartMs = startMs;
                         scope.pausedCheckIn = true;
-                        scope.pausedCheckInArgs = tc.args;
+                        scope.pausedCheckInArgs = callArgs;
                         // Returning a defined value triggers the footprintjs pause; the
                         // returned object becomes the checkpoint's pauseData. detectPause
                         // surfaces `pauseData.checkIn` as `outcome.checkIn`.
@@ -423,7 +497,7 @@ function buildToolCallsHandler(deps) {
                         try {
                             if (!tool)
                                 throw new Error(`Unknown tool: ${tc.name}`);
-                            result = await tool.execute(tc.args, {
+                            result = await tool.execute(callArgs, {
                                 toolCallId: tc.id,
                                 iteration,
                                 ...(env.signal && { signal: env.signal }),
@@ -462,7 +536,7 @@ function buildToolCallsHandler(deps) {
                 // so plain read_skill agents are byte-for-byte unaffected.
                 let skillRejected = false;
                 if (deps.allowedSkillIds && tc.name === 'read_skill' && !error && !denied) {
-                    const reqId = tc.args.id;
+                    const reqId = callArgs.id;
                     if (typeof reqId === 'string' && reqId.length > 0) {
                         const currentSkillId = scope.currentSkillId;
                         const allowed = deps.allowedSkillIds(currentSkillId);
@@ -508,7 +582,7 @@ function buildToolCallsHandler(deps) {
                 //     NEXT pass activates that Skill (lifetime: turn — stays
                 //     active until the turn ends).
                 if (tc.name === 'read_skill' && !error && !denied && !skillRejected) {
-                    const requestedId = tc.args.id;
+                    const requestedId = callArgs.id;
                     if (typeof requestedId === 'string' && requestedId.length > 0) {
                         const current = scope.activatedInjectionIds;
                         if (!current.includes(requestedId)) {
@@ -562,6 +636,12 @@ function buildToolCallsHandler(deps) {
             return undefined; // explicit: no pause, flow continues to loopTo
         },
         resume: async (scope, input) => {
+            // Same barrier as `execute`, for the same reason: an approved check-in
+            // runs the REAL tool here, and that side effect must not go out ahead of
+            // the state the last write is still carrying.
+            const durable = deps.awaitDurable?.();
+            if (durable)
+                await durable;
             // Consumer-supplied resume input becomes the paused tool's result.
             // The subflow's pre-pause scope is restored automatically by
             // footprintjs 4.17.0 via `checkpoint.subflowStates`, so
@@ -570,6 +650,126 @@ function buildToolCallsHandler(deps) {
             const toolCallId = scope.pausedToolCallId;
             const toolName = scope.pausedToolName;
             const startMs = scope.pausedToolStartMs;
+            // ── Middleware-ask decision path ─────────────────────────────────
+            // Discriminated by `scope.pausedAsk`, restored from the checkpoint.
+            //
+            // The answer is a DECISION, not a result. That is the whole reason the
+            // outcome union has no `result` arm: a middleware asks a person whether
+            // this call may proceed, and on approval the REAL tool runs — the person
+            // never writes the tool's answer, and neither does the middleware.
+            //
+            // A malformed resume DECLINES, for the same reason the check-in path
+            // does: a governed call must never execute because a message was
+            // mis-shaped.
+            if (scope.pausedAsk === true) {
+                const iteration = scope.iteration;
+                const args = (scope.pausedAskArgs ?? {});
+                const askIndex = (scope.pausedAskIndex ?? 0);
+                const askedBy = (scope.pausedAskMiddleware ?? 'middleware');
+                const decision = (0, checkin_js_1.isCheckInDecision)(input)
+                    ? input
+                    : (0, checkin_js_1.checkInDeclined)({ by: 'unknown', note: 'resume input was not a CheckInDecision' });
+                let result;
+                let error;
+                if (!decision.approved) {
+                    result = decision.note ? `declined by human: ${decision.note}` : 'declined by human';
+                    (0, ledger_js_1.recordDecisions)(scope, [
+                        {
+                            middleware: askedBy,
+                            at: 'tool',
+                            toolName,
+                            toolCallId,
+                            iteration,
+                            outcome: 'deny',
+                            changed: false,
+                            why: `declined by ${decision.by}${decision.note ? `: ${decision.note}` : ''}`,
+                        },
+                    ]);
+                }
+                else {
+                    (0, ledger_js_1.recordDecisions)(scope, [
+                        {
+                            middleware: askedBy,
+                            at: 'tool',
+                            toolName,
+                            toolCallId,
+                            iteration,
+                            outcome: 'allow',
+                            changed: false,
+                            why: `approved by ${decision.by}${decision.note ? `: ${decision.note}` : ''}`,
+                        },
+                    ]);
+                    // Continue the chain from the link AFTER the one that asked. Its
+                    // decision is already on the checkpoint; re-running it would ask the
+                    // same question twice and file a duplicate row.
+                    //
+                    // `askPolicy: 'refuse'` because footprintjs's `PausableHandler.resume`
+                    // returns void — a resumed dispatch has no second checkpoint to give.
+                    // A link further down the chain that also wants a person gets a named,
+                    // model-visible refusal and the tool does NOT run. That is the same
+                    // rule already applied to a tool that tries to pause during an
+                    // approved check-in resume: at most one human question per resume.
+                    const rest = await (0, runChain_js_1.runToolChain)(deps.toolMiddleware ?? [], {
+                        toolName,
+                        toolCallId,
+                        iteration,
+                        args,
+                        history: [...scope.history],
+                        startIndex: askIndex + 1,
+                        askPolicy: 'refuse',
+                    });
+                    (0, ledger_js_1.recordDecisions)(scope, rest.decisions);
+                    const tool = lookupTool(toolName);
+                    if (rest.kind === 'deny') {
+                        result = rest.reason;
+                    }
+                    else if (tool?.checkIn !== undefined) {
+                        // Same one-question rule, from the other direction: this tool also
+                        // demands consent, and there is no checkpoint left to ask with.
+                        // Refusing loudly beats executing a tool whose consent gate we
+                        // silently skipped.
+                        error = true;
+                        result =
+                            `tool '${toolName}' also declares checkIn, and a resumed dispatch cannot pause ` +
+                                `again to ask a second time. The call was not executed — approve it through one ` +
+                                `gate, not both.`;
+                    }
+                    else {
+                        const env = scope.$getEnv();
+                        const dispatched = await resolveCredentialAndExecute(scope, tool, toolName, rest.args, toolCallId, iteration, env);
+                        result = dispatched.result;
+                        error = dispatched.error;
+                    }
+                }
+                const askResultStr = typeof result === 'string' ? result : (0, validators_js_1.safeStringify)(result);
+                const askHistory = [
+                    ...scope.history,
+                    { role: 'tool', content: askResultStr, toolCallId, toolName },
+                ];
+                scope.history = askHistory;
+                scope.lastToolResult = { toolName, result: askResultStr };
+                (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.stream.tool_end', {
+                    toolCallId,
+                    result,
+                    durationMs: Date.now() - startMs,
+                    ...(error === true && { error: true }),
+                });
+                (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.agent.iteration_end', {
+                    turnIndex: 0,
+                    iterIndex: iteration,
+                    toolCallCount: 1,
+                    history: askHistory,
+                });
+                scope.iteration = iteration + 1;
+                scope.pausedToolCallId = '';
+                scope.pausedToolName = '';
+                scope.pausedToolStartMs = 0;
+                scope.pausedAsk = false;
+                scope.pausedAskArgs = undefined;
+                scope.pausedAskIndex = undefined;
+                scope.pausedAskMiddleware = undefined;
+                return;
+            }
             // ── Check-in decision path ───────────────────────────────────────
             // A check-in pause is discriminated by `scope.pausedCheckIn` (restored
             // from the checkpoint). The resume input is a `CheckInDecision`. On