agentfootprint 13.0.0 → 14.0.0

package/dist/esm/core/agent/stages/toolCalls/contracts/resources.d.ts

@@ -0,0 +1,67 @@
+import type { MemoryIdentity } from '../../../../../memory/identity/types.js';
+import type { ComponentResources } from '../../../componentResources.js';
+/** The resources dependencies of the existing tool-call stage. */
+export interface ToolResourcesPort {
+    /**
+     * The durable-write barrier (`core/durabilityBarrier.ts`). Asked ONCE per
+     * iteration, before any of this iteration's tools are dispatched: if the last
+     * iteration's state is still being written to a session store, wait for it.
+     *
+     * This is what bounds side-effect replay. Without it, iteration N's tools run
+     * while iteration N-1's write is in flight, so a crash can re-issue more than
+     * one iteration's worth of tool calls on replay and "how much re-executes?"
+     * has no answer. With it the answer is exactly one: the current iteration.
+     *
+     * Returns `undefined` when nobody installed a barrier — the ordinary case —
+     * and the dispatch loop then does not await at all, so an agent without a
+     * durable session composer is byte-identical in behaviour AND in timing.
+     *
+     * NOT a general extension point: the only installer is
+     * `agentfootprint/hosting`'s session writer, through a module-private
+     * WeakMap that appears on no barrel. See `core/durabilityBarrier.ts`.
+     *
+     * @internal
+     */
+    readonly awaitDurable?: () => Promise<void> | undefined;
+    /**
+     * The identity facts THIS run carries, for `ToolExecutionContext` (9.7.0).
+     *
+     * An ACCESSOR, for the same reason `awaitDurable` is one: the chart is built
+     * ONCE at construction and these change per run, so a captured value would be
+     * run #1's forever. Read once per dispatch loop, beside `scope.runIdentity`.
+     *
+     * `identity` here is the CALLER's explicit identity (`Agent.lastRunIdentity`),
+     * NOT `scope.runIdentity` — the latter is always populated, defaulting to
+     * `{ conversationId: '<runId>' }` (or, on a session-bound run since 9.10.0,
+     * to `{ conversationId: sessionId }`), and publishing either to a tool would
+     * present a synthesized conversation as one somebody named.
+     *
+     * @internal
+     */
+    /**
+     * Is this stage running in the agent's OWN executor? Asked of the scope
+     * (`stages/seed.ts` · `isOwnRun`): a stage in another runner's executor — a
+     * composition member — retains the actual native component run facts and
+     * takes only its explicit member identity from `scope.memberRun`. The
+     * member link never substitutes a different executor's run context.
+     * Absent → the agent's own run.
+     *
+     * @internal
+     */
+    readonly isOwnRun?: (scope: object) => boolean;
+    /** Captured native leg/component liveness, never the runner selected by a later call. */
+    readonly isRunRetired: () => boolean;
+    readonly currentRun?: () => {
+        readonly runContext?: import('../../../../../bridge/eventMeta.js').RunContext;
+        readonly runId: string;
+        readonly sessionId?: string;
+        readonly identity?: MemoryIdentity;
+    };
+    /**
+     * This native component's resource adapter. It persists finite references
+     * before tool resource effects and borrows the existing shared tier before
+     * dispatch. Live views and callbacks never cross checkpoints.
+     * @internal
+     */
+    readonly resources?: ComponentResources;
+}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=resources.js.map

package/dist/esm/core/agent/stages/toolCalls/contracts/resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../../../../../../../src/core/agent/stages/toolCalls/contracts/resources.ts"],"names":[],"mappings":""}

package/dist/esm/core/agent/stages/toolCalls/contracts/results.d.ts

@@ -0,0 +1,26 @@
+/** The results dependencies of the existing tool-call stage. */
+export interface ToolResultsPort {
+    /**
+     * The opt-in ceiling on ONE tool result, in characters (9.11.0).
+     *
+     * Undefined — the ordinary case — means results are never measured and never
+     * replaced, which is what every release before 9.11.0 did. Set, and EVERY
+     * result on EVERY dispatch path in this handler is measured against it; over
+     * the cap, the result the model reads and the result
+     * `agentfootprint.stream.tool_end` carries are both the marker. See
+     * `../../../toolResultCap.ts` for the shape and why it is opt-in.
+     */
+    readonly maxToolResultChars?: number;
+    /**
+     * Tell the model when it has already made this exact call and already got
+     * this exact answer (9.26.0). Threaded from `AgentOptions.repeatedCallNudge`,
+     * and only when the operator turned it OFF — `undefined` here means the
+     * default, which is on.
+     *
+     * Applied at the BATCH dispatch loop only, which is where a turn's repeats
+     * actually happen. The pause-resume paths deliver a call a PERSON answered
+     * or approved, and a note telling the model it has already done what a human
+     * just authorised would be the framework arguing with the human.
+     */
+    readonly repeatedCallNudge?: boolean;
+}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=results.js.map

package/dist/esm/core/agent/stages/toolCalls/contracts/results.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"results.js","sourceRoot":"","sources":["../../../../../../../src/core/agent/stages/toolCalls/contracts/results.ts"],"names":[],"mappings":""}

package/dist/esm/core/agent/stages/toolCalls/contracts/resumeFrames.d.ts

@@ -0,0 +1,14 @@
+import type { CheckInDecision } from '../../../../checkin.js';
+/** Ephemeral values for one existing resume door; never checkpoint state. */
+export interface ResumeCallFrame {
+    readonly toolName: string;
+    readonly toolCallId: string;
+    readonly startMs: number;
+}
+export interface ResumeConsentFrame extends ResumeCallFrame {
+    readonly consentDecision: CheckInDecision;
+    readonly runSignal: AbortSignal | undefined;
+}
+export interface ResumeResultFrame extends ResumeCallFrame {
+    readonly input: unknown;
+}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=resumeFrames.js.map

package/dist/esm/core/agent/stages/toolCalls/contracts/resumeFrames.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resumeFrames.js","sourceRoot":"","sources":["../../../../../../../src/core/agent/stages/toolCalls/contracts/resumeFrames.ts"],"names":[],"mappings":""}

package/dist/esm/core/agent/stages/toolCalls/contracts/routing.d.ts

@@ -0,0 +1,114 @@
+import type { StepPlanFor } from '../../../../../injection-engine/skillSteps.js';
+/** The routing dependencies of the existing tool-call stage. */
+export interface ToolRoutingPort {
+    /**
+     * Skill-graph read_skill GATE (`graph.reachableSkills`). When present, a
+     * `read_skill('id')` whose `id` is not reachable from the current cursor is
+     * REJECTED — the model gets a synthetic re-prompt naming the allowed ids and
+     * the cursor/activations stay unchanged, so it can't leave the graph mid-run.
+     * Undefined → no gate (plain read_skill agents append as before).
+     */
+    readonly allowedSkillIds?: (currentSkillId?: string) => readonly string[];
+    /**
+     * The OPEN skills — registered skills the graph never wires, admitted by the gate
+     * from ANY cursor (8.4.0; see `Agent.openSkillIds`). They ACTIVATE and never move
+     * the cursor: a skill the graph does not route is not a node, so it cannot be a
+     * hop. Only meaningful alongside `allowedSkillIds`.
+     */
+    readonly openSkillIds?: readonly string[];
+    /**
+     * The mount kernel's plan (9.59.0) — present only on agents built with
+     * `.maps()`. Read for exactly one thing: to tell a cursor move from a
+     * RE-ENGAGEMENT at the gate below. Everything else about engagement stays
+     * the kernel's business.
+     */
+    readonly engagementPlan?: import('../../../../../maps/engagement/types.js').EngagementPlan;
+    /**
+     * Is the mounted graph a decision `tree()`? Changes only the REFUSAL TEXT (8.5.0).
+     *
+     * A tree routes by predicate every iteration and has no cursor, so
+     * `reachableSkills()` is empty and every leaf pick is refused. Told with the
+     * generic message that reads "No skills are reachable from here", which is true
+     * but teaches nothing — the model would keep trying. The tree-shaped message says
+     * why the graph cannot be jumped at all, so the model stops asking and answers.
+     */
+    readonly skillGraphIsTree?: boolean;
+    /**
+     * The frozen step plans, keyed by skill id (9.18.0) — set only when ≥1
+     * registered skill declares `steps`. This stage owns the pointer's two
+     * RESULT-BOUNDARY moves, applied at EVERY site a result becomes final and
+     * is pushed (the batch loop AND all the pausable resume paths — a step
+     * whose tool paused, an `askHuman` step first among them, must advance on
+     * the resumed call exactly as it would have inline):
+     *
+     *   • ADVANCE — the finalized call is the current step's tool, ran, and
+     *     was not an error/denial/refusal → pointer + 1, `step_advanced`, and
+     *     the model-visible result gains the "now on step k+1" suffix
+     *     (composed BEFORE the history push — one past, no splicing).
+     *   • SKIP — a `skip_step` call: reason validated (empty → teaching
+     *     result, no event), `step_skipped` emitted, pointer moved or held
+     *     per the skill's declared `onSkip`, and the model-visible result is
+     *     OVERWRITTEN with the authoritative sentence (the read_skill-refusal
+     *     precedent — bookkeeping lives where the batch order lives).
+     *
+     * Postures never gate `skip_step`: skipping is judgment INSIDE a step,
+     * not routing. Undefined → no stepped skill anywhere; not one new line
+     * runs (zero-cost-when-unused).
+     */
+    readonly stepPlanFor?: StepPlanFor;
+    /**
+     * The mount's routing POSTURE beyond reachability (SG-C `strictness`).
+     * Undefined = `'assist'` = today's gate, byte-for-byte — not one new line
+     * runs. Judged AFTER reachability (an unreachable pick keeps its original
+     * teaching refusal), and only on HOPS — an OPEN skill (`.selfExplain()`,
+     * a `.skill()` beside the graph) is admitted from anywhere under every
+     * posture, so debugging never breaks:
+     *   • `'guard'` — a routing pick is admitted only while the turn's MENU is
+     *     outstanding AND names an offered id (the framework declared the
+     *     ambiguity; the model resolves exactly that). Off-menu / no-menu picks
+     *     get a teaching refusal + `skill.rejected { posture: 'guard' }`.
+     *   • `'rails'` — routing picks are refused outright: rules/scorer resolve
+     *     turn starts, declared routes handle transitions.
+     * Same graph, same trace: postures change refusal behavior only.
+     *
+     * Read only by the `read_skill` gate below, and that is the whole scope:
+     * `applyToolEffects` never consults it, because a `propose-transition`
+     * comes from a tool — the author's own code — and is admitted under every
+     * posture against reachability alone. See `SkillGraphOptions.strictness`
+     * (AgentBuilder.ts), which states the exemption for authors.
+     */
+    readonly skillStrictness?: 'guard' | 'rails';
+    /**
+     * Escalate-on-evidence (9.19.0). When declared, the two `skill.rejected`
+     * emit sites below increment a per-turn counter; at `afterRefusals` the
+     * rest of the turn flips onto the escalation brain (`scope.skillEscalated`
+     * — a committed fact callLLM's `brainFor` reads) and `skill.escalated`
+     * goes on the record ONCE. Undefined — the default — and not one new key
+     * is read or written (zero-cost-when-unused).
+     */
+    readonly escalation?: {
+        readonly afterRefusals: number;
+        /** The declared escalation brain, for the event's `to`. */
+        readonly to: {
+            readonly provider: string;
+            readonly model?: string;
+        };
+        /** Resolve the brain that WAS serving (the event's honest `from`) — the
+         *  same precedence chain callLLM applies, evaluated at the flip. */
+        readonly describeFrom: (cursor: string | undefined, resolvedModel: string | undefined) => {
+            readonly provider: string;
+            readonly model: string;
+        };
+    };
+    /**
+     * The registered injection ids a `require-instruction` tool effect may
+     * push, with the one fact its check-up needs (9.19.0): a skill whose
+     * declared body channel is `'tool-only'` cannot be pushed through the
+     * system slot — the slot suppresses it — so granting the lease would be
+     * accepted-and-silently-undelivered. Undefined → the agent registered no
+     * injections; every require-instruction is a teaching refusal.
+     */
+    readonly leaseTargets?: ReadonlyMap<string, {
+        readonly surfaceMode?: string;
+    }>;
+}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=routing.js.map

package/dist/esm/core/agent/stages/toolCalls/contracts/routing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.js","sourceRoot":"","sources":["../../../../../../../src/core/agent/stages/toolCalls/contracts/routing.ts"],"names":[],"mappings":""}

package/dist/esm/core/agent/stages/toolCalls/decorators/limitsOperations.d.ts

@@ -0,0 +1,4 @@
+import type { ToolCallsHandlerDeps } from '../contracts/handlerDeps.js';
+import type { ToolLimitsOperations } from '../contracts/operations/limits.js';
+/** Compose the existing limits callbacks once for this handler. */
+export declare function buildToolLimitsOperations(deps: Pick<ToolCallsHandlerDeps, 'maxToolResultChars'>): ToolLimitsOperations;

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

@@ -0,0 +1,80 @@
+import { capToolResult } from '../../../toolResultCap.js';
+import { applyResultCeiling } from '../../../resultCeiling.js';
+import { servedToModel } from '../../../../../semantics/coverage/read.js';
+import { typedEmit } from '../../../../../recorders/core/typedEmit.js';
+/** Compose the existing limits callbacks once for this handler. */
+export function buildToolLimitsOperations(deps) {
+    /**
+     * The tool-result ceiling, applied at the ONE place a result leaves dispatch.
+     *
+     * Both channels are measured SEPARATELY and on purpose. `result` is the
+     * tool's own truth and is what `stream.tool_end` reports; `modelResult` is
+     * what an `onToolResult` rule let the model read, and a rule that summarized
+     * a huge result down to a paragraph should not then be told it was
+     * truncated. Measuring each against the same cap keeps every channel honest
+     * about what IT is carrying — and stops a capped run from shipping the very
+     * payload it capped to an event sink.
+     *
+     * Absent cap → both values come back by reference, so an agent that did not
+     * ask for a ceiling is byte-identical.
+     */
+    const capResults = (toolName, values) => {
+        const max = deps.maxToolResultChars;
+        if (max === undefined)
+            return values;
+        const result = capToolResult(values.result, { toolName, maxChars: max }).value;
+        return {
+            result,
+            // One marker when the two channels carry one value — the common case, and
+            // the one where two distinct objects would be a difference with no fact
+            // behind it.
+            modelResult: values.modelResult === values.result
+                ? result
+                : capToolResult(values.modelResult, { toolName, maxChars: max }).value,
+        };
+    };
+    // LENS · tool-result · persistent-history
+    // reads: the tool's own declared resultCeiling / resultColumns ← ../../../resultCeiling.ts · applyResultCeiling, one owner of the measurement and the sentence
+    // law: may omit, never deny; every clause anchored to the call it was composed on.
+    /**
+     * The tool's OWN refusing ceiling (9.20.0) — ONE implementation for every
+     * dispatch door, applied at the execute boundary the moment the handler's
+     * return lands (BEFORE the after-tool chain, the read_skill-gate precedent:
+     * governance composes over what the model will actually read).
+     *
+     * `undefined` = no ceiling declared or the result fits — the caller keeps
+     * today's path byte for byte. Otherwise: the typed `tools.result_refused`
+     * event records the true size (the only place it survives), and the returned
+     * TEACHING REFUSAL replaces the payload on every channel — history,
+     * `stream.tool_end`, recorders. Distinct from the agent-level
+     * `maxToolResultChars` (which truncates with a verbatim head, measured AFTER
+     * the chain): this is the tool author's own contract, and the two compose —
+     * the refusal sentence is far under any sane agent cap.
+     */
+    const refuseOverCeiling = (scope, call, tool, value, declaredStatus) => {
+        const ceiling = tool?.resultCeiling;
+        // Measured on what the MODEL will read: the record-only coverage fields
+        // (`short`, `kind`) come off before serving (`afterMoment`), so declaring
+        // them must never tip a served result into a refusal. Same reference when
+        // nothing is declared — the measurement is the one it always was.
+        const verdict = applyResultCeiling(servedToModel(value), {
+            toolName: call.toolName,
+            ceiling,
+        });
+        if (verdict === undefined || ceiling === undefined)
+            return undefined;
+        typedEmit(scope, 'agentfootprint.tools.result_refused', {
+            toolName: call.toolName,
+            toolCallId: call.toolCallId,
+            iteration: call.iteration,
+            sizeChars: verdict.sizeChars,
+            maxChars: ceiling.maxChars,
+            // Copied — event payloads are detached plain data, never shared refs.
+            ...(ceiling.narrowBy !== undefined && { narrowBy: [...ceiling.narrowBy] }),
+            ...(declaredStatus !== undefined && { declaredStatus }),
+        });
+        return verdict.refusal;
+    };
+    return { capResults, refuseOverCeiling };
+}
+//# sourceMappingURL=limitsOperations.js.map

package/dist/esm/core/agent/stages/toolCalls/decorators/limitsOperations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limitsOperations.js","sourceRoot":"","sources":["../../../../../../../src/core/agent/stages/toolCalls/decorators/limitsOperations.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAK1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,2CAA2C,CAAC;AAC1E,OAAO,EAAE,SAAS,EAAE,MAAM,4CAA4C,CAAC;AAGvE,mEAAmE;AACnE,MAAM,UAAU,yBAAyB,CACvC,IAAsD;IAEtD;;;;;;;;;;;;;OAaG;IACH,MAAM,UAAU,GAAG,CACjB,QAAgB,EAChB,MAAmE,EACN,EAAE;QAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,kBAAkB,CAAC;QACpC,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC;QACrC,MAAM,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC;QAC/E,OAAO;YACL,MAAM;YACN,0EAA0E;YAC1E,wEAAwE;YACxE,aAAa;YACb,WAAW,EACT,MAAM,CAAC,WAAW,KAAK,MAAM,CAAC,MAAM;gBAClC,CAAC,CAAC,MAAM;gBACR,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,WAAW,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC,KAAK;SAC3E,CAAC;IACJ,CAAC,CAAC;IAEF,0CAA0C;IAC1C,+JAA+J;IAC/J,mFAAmF;IACnF;;;;;;;;;;;;;;OAcG;IACH,MAAM,iBAAiB,GAAG,CACxB,KAA6B,EAC7B,IAA4F,EAC5F,IAAsB,EACtB,KAAc,EACd,cAAiC,EACb,EAAE;QACtB,MAAM,OAAO,GAAG,IAAI,EAAE,aAAa,CAAC;QACpC,wEAAwE;QACxE,0EAA0E;QAC1E,0EAA0E;QAC1E,kEAAkE;QAClE,MAAM,OAAO,GAAG,kBAAkB,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE;YACvD,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,OAAO;SACR,CAAC,CAAC;QACH,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QACrE,SAAS,CAAC,KAAK,EAAE,qCAAqC,EAAE;YACtD,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,sEAAsE;YACtE,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1E,GAAG,CAAC,cAAc,KAAK,SAAS,IAAI,EAAE,cAAc,EAAE,CAAC;SACxD,CAAC,CAAC;QACH,OAAO,OAAO,CAAC,OAAO,CAAC;IACzB,CAAC,CAAC;IAEF,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,CAAC;AAC3C,CAAC"}

package/dist/esm/core/agent/stages/toolCalls/decorators/middlewareOperations.d.ts

@@ -0,0 +1,4 @@
+import type { ToolCallsHandlerDeps } from '../contracts/handlerDeps.js';
+import type { ToolMiddlewareOperations } from '../contracts/operations/middleware.js';
+/** Compose the existing middleware callbacks once for this handler. */
+export declare function buildToolMiddlewareOperations(deps: Pick<ToolCallsHandlerDeps, 'negativeClaimsArmed' | 'toolMiddleware'>): ToolMiddlewareOperations;

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

@@ -0,0 +1,83 @@
+import { runToolAfterChain } from '../../../../../tools/runChain.js';
+import { captureNegativeRefusal, keepNegativeResultOut } from '../../../negativeClaims/capture.js';
+import { servedToModel } from '../../../../../semantics/coverage/read.js';
+import { recordDecisions } from '../../../middleware/ledger.js';
+import { readToolResultEnvelope } from '../../../../../semantics/toolEffects.js';
+import { isJsonFaithful } from '../../../../../lib/jsonFaithful.js';
+/** Compose the existing middleware callbacks once for this handler. */
+export function buildToolMiddlewareOperations(deps) {
+    /**
+     * The after-tool moment: the chain's last word, on a call that RAN.
+     *
+     * Called from all FIVE dispatch sites and from nowhere else — the loop, an
+     * approved ask, an approved check-in, a granted credential consent, and (since
+     * 8.13.0) a resumed `pauseHere` / `askHuman`. Every one of them has just
+     * produced the result of a call that ran, which is the entire precondition. A
+     * call the chain denied, a call whose args were rejected, a call whose
+     * credential never issued and a call still waiting on a person have no result,
+     * and asking a rule about a result that does not exist would be the same
+     * fabrication the outcome union removes.
+     *
+     * On the `pauseHere` path the value is the one a PERSON supplied, and that is
+     * still this moment's business: the handler's contract is that the human's
+     * answer IS the paused tool's result — it lands as `role: 'tool'` under the
+     * same `toolCallId`, `stream.tool_end` reports it, and `lastToolResult` fires
+     * `on-tool-return` triggers off it. A redaction rule that runs on every other
+     * tool result and not on that one is a redaction rule with a hole in it, in
+     * the one channel where a person can paste a secret.
+     *
+     * Returns what the MODEL reads. The real result stays with the caller for
+     * `stream.tool_end`, so an event stream keeps reporting what the tool
+     * returned while the history carries what the rules allowed through — and
+     * the ledger row beside them says which is which.
+     */
+    const afterMoment = async (scope, call) => {
+        // The record-only coverage fields (`short`, `kind`) come off FIRST, so the
+        // model is never served them and every link below is handed what the
+        // model will read — none can re-serve them. Every dispatch path calls
+        // this moment for a result that ran (the batch loop and the four resume
+        // doors), which is why the strip lives here and nowhere else. The SAME
+        // reference back when no item carried either key: a run whose tools
+        // declare neither serves the bytes it always did, and the callers'
+        // reference-inequality stamp of `tool_end.modelResult` stays unstamped.
+        if (deps.negativeClaimsArmed === true && call.error)
+            captureNegativeRefusal(scope, call.toolName, call.result, call.args);
+        const served = servedToModel(call.result);
+        const chain = deps.toolMiddleware ?? [];
+        // No `onToolResult` hook anywhere in the chain → no walk, no rows, no await
+        // beyond the ones this dispatch already made. An agent whose middleware
+        // only governs calls is byte-identical to one built before this moment
+        // existed.
+        if (!chain.some((mw) => typeof mw.onToolResult === 'function'))
+            return served;
+        const verdict = await runToolAfterChain(chain, {
+            toolName: call.toolName,
+            ...(call.tool?.source !== undefined && { toolSource: call.tool.source }),
+            toolCallId: call.toolCallId,
+            iteration: call.iteration,
+            args: call.args,
+            result: served,
+            ...(call.error === true && { error: true }),
+            history: call.history,
+            ...(call.identity && { identity: call.identity }),
+            ...(call.signal && { signal: call.signal }),
+        });
+        recordDecisions(scope, verdict.decisions);
+        const delivered = verdict.kind === 'deny' ? verdict.reason : verdict.result;
+        // An explicit policy denial withdraws access to the native observation.
+        // A guessed handle must not make the final composer disclose it again.
+        // Allowed summaries remain eligible: their native coverage and gaps, not
+        // the summary's claims, are what the final checker uses.
+        if (deps.negativeClaimsArmed === true) {
+            const transformedStatus = readToolResultEnvelope(delivered)?.status;
+            const notRead = ['invalid', 'denied', 'failure', 'pending'].includes(transformedStatus ?? '');
+            if (verdict.kind === 'deny' || notRead || !isJsonFaithful(delivered))
+                keepNegativeResultOut(scope, call.negativeResultId);
+            if (verdict.kind === 'deny' || notRead)
+                captureNegativeRefusal(scope, call.toolName, delivered, call.args);
+        }
+        return delivered;
+    };
+    return { afterMoment };
+}
+//# sourceMappingURL=middlewareOperations.js.map

package/dist/esm/core/agent/stages/toolCalls/decorators/middlewareOperations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middlewareOperations.js","sourceRoot":"","sources":["../../../../../../../src/core/agent/stages/toolCalls/decorators/middlewareOperations.ts"],"names":[],"mappings":"AAIA,OAAO,EAAiB,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAEpF,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AACnG,OAAO,EAAE,aAAa,EAAE,MAAM,2CAA2C,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,yCAAyC,CAAC;AACjF,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAGpE,uEAAuE;AACvE,MAAM,UAAU,6BAA6B,CAC3C,IAA0E;IAE1E;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,MAAM,WAAW,GAAG,KAAK,EACvB,KAA6B,EAC7B,IAYC,EACiB,EAAE;QACpB,2EAA2E;QAC3E,qEAAqE;QACrE,sEAAsE;QACtE,wEAAwE;QACxE,uEAAuE;QACvE,oEAAoE;QACpE,mEAAmE;QACnE,wEAAwE;QACxE,IAAI,IAAI,CAAC,mBAAmB,KAAK,IAAI,IAAI,IAAI,CAAC,KAAK;YACjD,sBAAsB,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QACvE,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,cAAc,IAAI,EAAE,CAAC;QACxC,4EAA4E;QAC5E,wEAAwE;QACxE,uEAAuE;QACvE,WAAW;QACX,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,CAAC,YAAY,KAAK,UAAU,CAAC;YAAE,OAAO,MAAM,CAAC;QAC9E,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC,KAAK,EAAE;YAC7C,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACxE,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,MAAM,EAAE,MAAM;YACd,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,IAAI,IAAI,EAAE,KAAK,EAAE,IAAa,EAAE,CAAC;YACpD,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;YACjD,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;SAC5C,CAAC,CAAC;QACH,eAAe,CAAC,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;QAC1C,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;QAC5E,wEAAwE;QACxE,uEAAuE;QACvE,yEAAyE;QACzE,yDAAyD;QACzD,IAAI,IAAI,CAAC,mBAAmB,KAAK,IAAI,EAAE,CAAC;YACtC,MAAM,iBAAiB,GAAG,sBAAsB,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;YACpE,MAAM,OAAO,GAAG,CAAC,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC;YAC9F,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC;gBAClE,qBAAqB,CAAC,KAAK,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC;YACtD,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO;gBACpC,sBAAsB,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QACvE,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC;IAEF,OAAO,EAAE,WAAW,EAAE,CAAC;AACzB,CAAC"}

package/dist/esm/core/agent/stages/toolCalls/decorators/reportingCredentials.d.ts

@@ -0,0 +1,29 @@
+import type { CredentialProvider } from '../../../../../identity/types.js';
+import type { ToolSecurityEmitter } from '../../../toolSecurityEvents.js';
+/**
+ * The constructor name of what was thrown, when what was thrown was an Error.
+ *
+ * Reported on `agentfootprint.credential.failed` so an alert can route on the
+ * CLASS of failure rather than parse a message. `undefined` for a thrown
+ * non-Error, because "Object" would be a fact about JavaScript rather than
+ * about the failure.
+ */
+export declare function errorClassOf(err: unknown): string | undefined;
+/**
+ * Wrap the credential provider handed to a tool as `ctx.credentials`, so a
+ * failure inside the tool's OWN `getCredential(...)` call is as visible as one
+ * on the declared-`needs` path.
+ *
+ * Why this exists (9.4.0). `needs` resolution has emitted
+ * `agentfootprint.credential.failed` since 6.11.0. The pull path — a tool that
+ * asks for its own credential mid-execute — emitted nothing: the throw was
+ * caught by the generic tool catch and became `tool_end` with `error: true`,
+ * one indistinguishable failure among all the other ways a tool can fail. An
+ * operator watching the credential domain saw a healthy silence while every
+ * call was failing to authenticate, which is the exact shape of the AWS
+ * identity-adapter bug this release fixes.
+ *
+ * It is a decorator, not a replacement: the same `id`, the same result, the
+ * same throw. It only makes a noise on the way past.
+ */
+export declare function reportingCredentials(provider: CredentialProvider, emitSecurity: ToolSecurityEmitter, toolName: string): CredentialProvider;

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

@@ -0,0 +1,48 @@
+/**
+ * The constructor name of what was thrown, when what was thrown was an Error.
+ *
+ * Reported on `agentfootprint.credential.failed` so an alert can route on the
+ * CLASS of failure rather than parse a message. `undefined` for a thrown
+ * non-Error, because "Object" would be a fact about JavaScript rather than
+ * about the failure.
+ */
+export function errorClassOf(err) {
+    return err instanceof Error ? err.constructor?.name ?? err.name : undefined;
+}
+/**
+ * Wrap the credential provider handed to a tool as `ctx.credentials`, so a
+ * failure inside the tool's OWN `getCredential(...)` call is as visible as one
+ * on the declared-`needs` path.
+ *
+ * Why this exists (9.4.0). `needs` resolution has emitted
+ * `agentfootprint.credential.failed` since 6.11.0. The pull path — a tool that
+ * asks for its own credential mid-execute — emitted nothing: the throw was
+ * caught by the generic tool catch and became `tool_end` with `error: true`,
+ * one indistinguishable failure among all the other ways a tool can fail. An
+ * operator watching the credential domain saw a healthy silence while every
+ * call was failing to authenticate, which is the exact shape of the AWS
+ * identity-adapter bug this release fixes.
+ *
+ * It is a decorator, not a replacement: the same `id`, the same result, the
+ * same throw. It only makes a noise on the way past.
+ */
+export function reportingCredentials(provider, emitSecurity, toolName) {
+    return {
+        id: provider.id,
+        async getCredential(req) {
+            try {
+                return await provider.getCredential(req);
+            }
+            catch (err) {
+                emitSecurity('agentfootprint.credential.failed', {
+                    service: req.service,
+                    reason: err instanceof Error ? err.message : String(err),
+                    tool: toolName,
+                    ...(errorClassOf(err) !== undefined && { errorClass: errorClassOf(err) }),
+                });
+                throw err;
+            }
+        },
+    };
+}
+//# sourceMappingURL=reportingCredentials.js.map

package/dist/esm/core/agent/stages/toolCalls/decorators/reportingCredentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reportingCredentials.js","sourceRoot":"","sources":["../../../../../../../src/core/agent/stages/toolCalls/decorators/reportingCredentials.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9E,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAA4B,EAC5B,YAAiC,EACjC,QAAgB;IAEhB,OAAO;QACL,EAAE,EAAE,QAAQ,CAAC,EAAE;QACf,KAAK,CAAC,aAAa,CAAC,GAAG;YACrB,IAAI,CAAC;gBACH,OAAO,MAAM,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;YAC3C,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,YAAY,CAAC,kCAAkC,EAAE;oBAC/C,OAAO,EAAE,GAAG,CAAC,OAAO;oBACpB,MAAM,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;oBACxD,IAAI,EAAE,QAAQ;oBACd,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC;iBAC1E,CAAC,CAAC;gBACH,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/esm/core/agent/stages/toolCalls/evidence/coverageOperations.d.ts

@@ -0,0 +1,9 @@
+import type { ToolCallsHandlerDeps } from '../contracts/handlerDeps.js';
+import type { ToolCoverageOperations } from '../contracts/operations/coverage.js';
+import type { ToolIntegrityOperations } from '../contracts/operations/integrity.js';
+interface ToolCoverageOperationsLinks {
+    readonly noticeEmptyLookup: ToolIntegrityOperations['noticeEmptyLookup'];
+}
+/** Compose the existing coverage callbacks once for this handler. */
+export declare function buildToolCoverageOperations(deps: Pick<ToolCallsHandlerDeps, 'resultsLayer' | 'negativeClaimsArmed'>, links: ToolCoverageOperationsLinks): ToolCoverageOperations;
+export {};