agentfootprint 7.17.0 → 7.18.0

package/dist/esm/core/agent/stages/seed.d.ts

@@ -19,6 +19,7 @@
 import type { TypedScope } from 'footprintjs';
 import type { LLMMessage, LLMToolSchema } from '../../../adapters/types.js';
 import type { AgentInput, AgentState, RunConfig } from '../types.js';
+import type { MessageMiddleware } from '../middleware/types.js';
 export interface SeedStageDeps {
     /** Resolved `clampIterations(opts.maxIterations ?? 10)`. Frozen at
      *  chart-build time. */
@@ -53,10 +54,24 @@ export interface SeedStageDeps {
      * written, so the commit log is byte-identical to earlier releases.
      */
     readonly resolveRunConfig?: (input: AgentInput) => RunConfig | undefined;
+    /**
+     * The message chain (`.messageMiddleware(...)`), walked here at the
+     * `'input'` phase — BEFORE `userMessage` and `history` are written.
+     *
+     * This is the only placement that keeps the run honest. Everything
+     * downstream reads `scope.history`: the window strategies, the injection
+     * engine, all three slots, the request that goes on the wire, and every
+     * slice taken afterwards. Transform later than this and those components
+     * disagree about what the user actually said — the trace would show one
+     * message and the model would have answered another.
+     *
+     * Empty / undefined → seed stays the synchronous stage it always was.
+     */
+    readonly messageMiddleware?: readonly MessageMiddleware[];
 }
 /**
  * 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.
  */
-export declare function buildSeedStage(deps: SeedStageDeps): (scope: TypedScope<AgentState>) => void;
+export declare function buildSeedStage(deps: SeedStageDeps): (scope: TypedScope<AgentState>) => void | Promise<void>;

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

@@ -17,99 +17,144 @@
  * features need.
  */
 import { typedEmit } from '../../../recorders/core/typedEmit.js';
+import { runMessageChain } from '../middleware/runChain.js';
+import { recordDecisions } from '../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.
  */
 export 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;
-        }
-        typedEmit(scope, 'agentfootprint.agent.turn_start', {
-            turnIndex: 0,
-            userPrompt: args.message,
+    }
+    return async (scope) => {
+        const args = scope.$getArgs();
+        const verdict = await runMessageChain(chain, {
+            phase: 'input',
+            content: args.message,
+            history: [],
+            // The input boundary runs before iteration 1 exists.
+            iteration: 0,
+            ...(args.identity && { identity: args.identity }),
         });
+        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);
+    };
+}
+/**
+ * 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;
+    }
+    typedEmit(scope, 'agentfootprint.agent.turn_start', {
+        turnIndex: 0,
+        userPrompt: message,
+    });
 }
 //# sourceMappingURL=seed.js.map

package/dist/esm/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/esm/core/agent/stages/toolCalls.d.ts

@@ -20,6 +20,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).
@@ -31,6 +44,7 @@ import type { CredentialProvider } from '../../../identity/types.js';
 import { type ResolvedCheckInConfig } from '../../checkin.js';
 import type { ProviderToolCache } from '../../slots/buildToolsSlot.js';
 import type { Tool } from '../../tools.js';
+import type { ToolMiddleware } from '../middleware/types.js';
 import { type ToolArgValidationMode } from '../toolArgsValidation.js';
 import type { AgentState } from '../types.js';
 export interface ToolCallsHandlerDeps {
@@ -78,6 +92,15 @@ export interface ToolCallsHandlerDeps {
      * Agent (no check-in). The gate fires ONLY for tools that declared `checkIn`.
      */
     readonly checkIn?: ResolvedCheckInConfig;
+    /**
+     * The tool-dispatch governance chain (`.toolMiddleware(...)`), in
+     * declaration order. Walked AFTER the permission gate — so an existing
+     * `PermissionChecker` still decides first and a denial there means no
+     * middleware runs at all — and BEFORE arg validation, so validation judges
+     * the args that will actually be sent rather than the ones the model
+     * proposed. Empty / undefined → not walked, no ledger key, no events.
+     */
+    readonly toolMiddleware?: readonly ToolMiddleware[];
 }
 /**
  * Build the pausable tool-call handler for the agent's chart.

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

@@ -20,6 +20,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).
@@ -29,6 +42,8 @@ import { extractSequence } from '../../../security/extractSequence.js';
 import { unconfiguredCredentialProvider } from '../../../identity/types.js';
 import { isPauseRequest } from '../../pause.js';
 import { shouldCheckIn, isCheckInDecision, checkInDeclined, } from '../../checkin.js';
+import { runToolChain } from '../middleware/runChain.js';
+import { recordDecisions } from '../middleware/ledger.js';
 import { formatToolArgIssues, validateToolArgs, } from '../toolArgsValidation.js';
 import { safeStringify } from '../validators.js';
 /**
@@ -202,6 +217,12 @@ export 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) {
@@ -268,6 +289,52 @@ export 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 runToolChain(deps.toolMiddleware, {
+                        toolName: tc.name,
+                        toolCallId: tc.id,
+                        iteration,
+                        args: callArgs,
+                        history: newHistory,
+                        ...(runIdentity && { identity: runIdentity }),
+                        ...(env.signal && { signal: env.signal }),
+                    });
+                    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).
@@ -278,7 +345,7 @@ export function buildToolCallsHandler(deps) {
                 // tools (their inputSchema is the contract the LLM was shown).
                 let argsRejected = false;
                 if (!denied && tool && toolArgValidation !== 'off') {
-                    const verdict = validateToolArgs(tc.args, tool.schema.inputSchema);
+                    const verdict = validateToolArgs(callArgs, tool.schema.inputSchema);
                     if (!verdict.ok) {
                         typedEmit(scope, 'agentfootprint.validation.args_invalid', {
                             toolName: tc.name,
@@ -316,7 +383,7 @@ export function buildToolCallsHandler(deps) {
                     const historyForEvidence = systemPrompt
                         ? [{ role: 'system', content: systemPrompt }, ...newHistory]
                         : newHistory;
-                    if (!shouldCheckIn(tool.checkIn, tc.args, {
+                    if (!shouldCheckIn(tool.checkIn, callArgs, {
                         iteration,
                         toolCallId: tc.id,
                         history: historyForEvidence,
@@ -328,7 +395,7 @@ export 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,
@@ -337,7 +404,7 @@ export function buildToolCallsHandler(deps) {
                         });
                         const request = {
                             tool: tc.name,
-                            args: tc.args,
+                            args: callArgs,
                             ...(intent !== undefined && { intent }),
                             evidence,
                         };
@@ -355,7 +422,7 @@ export 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`.
@@ -420,7 +487,7 @@ export 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 }),
@@ -459,7 +526,7 @@ export 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);
@@ -505,7 +572,7 @@ export 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)) {
@@ -567,6 +634,126 @@ export 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 = isCheckInDecision(input)
+                    ? input
+                    : 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';
+                    recordDecisions(scope, [
+                        {
+                            middleware: askedBy,
+                            at: 'tool',
+                            toolName,
+                            toolCallId,
+                            iteration,
+                            outcome: 'deny',
+                            changed: false,
+                            why: `declined by ${decision.by}${decision.note ? `: ${decision.note}` : ''}`,
+                        },
+                    ]);
+                }
+                else {
+                    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 runToolChain(deps.toolMiddleware ?? [], {
+                        toolName,
+                        toolCallId,
+                        iteration,
+                        args,
+                        history: [...scope.history],
+                        startIndex: askIndex + 1,
+                        askPolicy: 'refuse',
+                    });
+                    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 : safeStringify(result);
+                const askHistory = [
+                    ...scope.history,
+                    { role: 'tool', content: askResultStr, toolCallId, toolName },
+                ];
+                scope.history = askHistory;
+                scope.lastToolResult = { toolName, result: askResultStr };
+                typedEmit(scope, 'agentfootprint.stream.tool_end', {
+                    toolCallId,
+                    result,
+                    durationMs: Date.now() - startMs,
+                    ...(error === true && { error: true }),
+                });
+                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