agentfootprint 9.41.0 → 9.44.0

package/dist/esm/core/agent/coverage/types.d.ts

@@ -0,0 +1,142 @@
+/**
+ * coverage/types — the shared vocabulary of the two coverage primitives.
+ *
+ * Pattern: one value type, two consumers — `absent()` says "I looked HERE and
+ *          found nothing", `coverage()` says "my answer covers THIS and not
+ *          THAT". Both are statements about the same thing: the ground a
+ *          result stands on. Spelling them with one vocabulary is what lets
+ *          the answer-level block merge an absence's boundary with a
+ *          verdict's without translating between two grammars.
+ * Role:    core/ layer, pure data. No imports, no behavior.
+ * Emits:   N/A.
+ */
+/**
+ * One piece of ground, and (optionally) why it is where it is.
+ *
+ * `what` is prose the TOOL AUTHOR wrote — a source, a window, a filter, a
+ * fleet ("the fcns database on shq-fab-a", "the last 24h", "all four
+ * arrays"). It is never composed from the model's arguments by this library,
+ * because the library does not know which of them are real.
+ */
+export interface CoverageItem {
+    /** The source, window, filter or population. Non-empty. */
+    readonly what: string;
+    /**
+     * Why it sits where it does. REQUIRED on `cannotCover` (a permanent blind
+     * spot is a claim about capability, and a claim with no reason cannot be
+     * acted on or disproved); optional on `checked` and `notChecked`, where
+     * "we did" and "we did not need to" are often the whole story.
+     */
+    readonly why?: string;
+}
+/** What an author may write in a coverage list: bare prose, or prose + why. */
+export type CoverageInput = string | CoverageItem;
+/**
+ * The three lists, normalized. This is the shape everything downstream reads —
+ * the renderer, the event payload, the answer-level block.
+ *
+ * The three are NOT interchangeable, and the difference is the whole point:
+ *
+ *   • `checked` — ground this result actually stands on. A clean verdict here
+ *     means VERIFIED.
+ *   • `notChecked` — ground this run could have covered and did not (budget,
+ *     a timeout, a scope the caller chose). A clean verdict says nothing
+ *     about it. Re-asking with a wider scope can move it to `checked`.
+ *   • `cannotCover` — ground no call to this tool will ever reach (no
+ *     collector, no permission, no such telemetry). A clean verdict says
+ *     nothing about it, and no retry ever will. This is the list that turns
+ *     "everything looks fine" into "everything I can see looks fine".
+ */
+export interface Coverage {
+    readonly checked: readonly CoverageItem[];
+    readonly notChecked: readonly CoverageItem[];
+    readonly cannotCover: readonly CoverageItem[];
+}
+/** What a tool author passes to {@link import('./ledger.js').coverage}. */
+export interface CoverageDeclaration {
+    readonly checked?: readonly CoverageInput[];
+    readonly notChecked?: readonly CoverageInput[];
+    readonly cannotCover?: readonly CoverageInput[];
+}
+/** What a tool author passes to {@link import('./absent.js').absent}. */
+export interface AbsenceDeclaration {
+    /**
+     * What was looked for, in the author's own words ("FLOGI entries on
+     * fc1/3"). Required: an absence that cannot say what it did not find is
+     * indistinguishable from a tool that returned nothing by accident.
+     */
+    readonly what: string;
+    /**
+     * The coverage of the search — REQUIRED and non-empty. An absence that
+     * names no coverage is a `null` with extra steps: the reader still cannot
+     * tell "I looked and there is nothing" from "I could not look", which is
+     * the entire failure this primitive exists to prevent.
+     */
+    readonly checked: readonly CoverageInput[];
+    /** Ground the search did not reach this time — an absence here proves
+     *  nothing about it. */
+    readonly notChecked?: readonly CoverageInput[];
+    /** Ground no search by this tool can reach. Each needs a `why`. */
+    readonly cannotCover?: readonly CoverageInput[];
+    /**
+     * Where to go INSTEAD, in one sentence ("widen the window with
+     * `window: '7d'`, or ask for a different interface"). Optional, and the
+     * highest-value optional field in the shape: the loop this primitive stops
+     * is a model with nowhere else to go.
+     */
+    readonly tryInstead?: string;
+}
+/**
+ * The rendered absence — the exact object a tool hands back and the model
+ * reads. Field names are snake_case and English on purpose: this value is
+ * read by a language model far more often than by code, and `af_absent` is
+ * the only field here that exists for the machine.
+ *
+ * The `af_absent` key is RESERVED vocabulary on the tool-result wire (the
+ * `propose-transition` / `require-instruction` precedent): a plain object
+ * carrying it is an absence, and nothing else in this library will treat any
+ * other shape as one.
+ */
+export interface ToolAbsence {
+    readonly af_absent: true;
+    /** The plain-English handle. Present so a model that skims one key still
+     *  reads the outcome rather than inferring it from a missing field. */
+    readonly outcome: 'nothing_found';
+    readonly looked_for: string;
+    readonly checked: readonly CoverageItem[];
+    readonly not_checked?: readonly CoverageItem[];
+    readonly cannot_cover?: readonly CoverageItem[];
+    /** Stated as data as well as prose — the note can be skimmed past, a
+     *  `true` in a field named for the question cannot. */
+    readonly retry_returns_the_same: true;
+    readonly try_instead?: string;
+    /** The static sentence. Never interpolated — see `absent.ts`. */
+    readonly note: string;
+}
+/** The rendered coverage ledger, wrapped around the result it bounds. */
+export interface CoveredResult<T = unknown> {
+    readonly af_coverage: {
+        readonly checked?: readonly CoverageItem[];
+        readonly not_checked?: readonly CoverageItem[];
+        readonly cannot_cover?: readonly CoverageItem[];
+        readonly note: string;
+    };
+    /** The tool's own answer, untouched. */
+    readonly result: T;
+}
+/**
+ * One coverage statement as the RUN recorded it — what the event carries and
+ * what accumulates in `AgentState.coverageDeclared`.
+ *
+ * `kind` is kept because the two read differently at the answer boundary: a
+ * `'ledger'` bounds a verdict the answer is probably built on, an
+ * `'absence'` bounds a search that found nothing.
+ */
+export interface DeclaredCoverage extends Coverage {
+    readonly kind: 'absence' | 'ledger';
+    readonly toolName: string;
+    readonly toolCallId?: string;
+    readonly iteration: number;
+    /** Present for `'absence'` only — what the search was for. */
+    readonly lookedFor?: string;
+}

package/dist/esm/core/agent/coverage/types.js

@@ -0,0 +1,14 @@
+/**
+ * coverage/types — the shared vocabulary of the two coverage primitives.
+ *
+ * Pattern: one value type, two consumers — `absent()` says "I looked HERE and
+ *          found nothing", `coverage()` says "my answer covers THIS and not
+ *          THAT". Both are statements about the same thing: the ground a
+ *          result stands on. Spelling them with one vocabulary is what lets
+ *          the answer-level block merge an absence's boundary with a
+ *          verdict's without translating between two grammars.
+ * Role:    core/ layer, pure data. No imports, no behavior.
+ * Emits:   N/A.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/core/agent/coverage/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../src/core/agent/coverage/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/esm/core/agent/evidence/evidenceIndex.d.ts

@@ -26,6 +26,13 @@
  *     value because the model passed it to a tool would let any invention
  *     launder itself through one failed lookup.
  *   • **The model's own earlier answers do not count**, for the same reason.
+ *   • **An `absent(…)` result grounds its COVERAGE only.** An absence names
+ *     what was looked FOR, which in practice quotes the arguments the model
+ *     passed — so indexing the whole frame would ground an invented
+ *     identifier through the one operation that proves nothing about it: a
+ *     lookup that found nothing. `checked` / `not_checked` / `cannot_cover`
+ *     are the tool's own words about the world and do count. See
+ *     `../coverage/evidence.ts`.
  *
  * The EXEMPT index is built from a different corpus with the same machinery:
  * the user's own message, the conversation's user/system turns, and the

package/dist/esm/core/agent/evidence/evidenceIndex.js

@@ -26,6 +26,13 @@
  *     value because the model passed it to a tool would let any invention
  *     launder itself through one failed lookup.
  *   • **The model's own earlier answers do not count**, for the same reason.
+ *   • **An `absent(…)` result grounds its COVERAGE only.** An absence names
+ *     what was looked FOR, which in practice quotes the arguments the model
+ *     passed — so indexing the whole frame would ground an invented
+ *     identifier through the one operation that proves nothing about it: a
+ *     lookup that found nothing. `checked` / `not_checked` / `cannot_cover`
+ *     are the tool's own words about the world and do count. See
+ *     `../coverage/evidence.ts`.
  *
  * The EXEMPT index is built from a different corpus with the same machinery:
  * the user's own message, the conversation's user/system turns, and the
@@ -33,6 +40,7 @@
  * not a fabrication — the user gave it — and neither is one the app's own
  * prompt or skill body put in front of the model.
  */
+import { absenceEvidenceProjection } from '../coverage/index.js';
 import { isLibraryAuthoredTurn } from './frames.js';
 import { lookupForms, normalizeToken, tokenize } from './normalize.js';
 /**
@@ -93,7 +101,16 @@ function indexResult(content, sink) {
     const trimmed = content.trim();
     if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
         try {
-            walk(JSON.parse(trimmed), sink);
+            const parsed = JSON.parse(trimmed);
+            // An `absent(…)` frame grounds its COVERAGE and nothing else: the rest
+            // of it is prose about the REQUEST, which usually quotes the model's own
+            // arguments, and indexing that would ground every identifier a model
+            // invented as long as it handed the invention to one tool that found
+            // nothing. See `../coverage/evidence.ts` — it is the frames.ts argument
+            // on the tool side of the conversation. `undefined` (every other result
+            // ever returned) keeps the walk it always had.
+            const projection = absenceEvidenceProjection(parsed);
+            walk(projection ?? parsed, sink);
             return;
         }
         catch {

package/dist/esm/core/agent/evidence/evidenceIndex.js.map

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

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

@@ -27,3 +27,21 @@
 import type { TypedScope } from 'footprintjs';
 import type { AgentState } from '../types.js';
 export declare const prepareFinalStage: (scope: TypedScope<AgentState>) => void;
+/**
+ * `.limitsTravelWithTheAnswer()`'s half of prepare-final — the SAME stage,
+ * with the run's declared coverage folded into the answer first.
+ *
+ * Mounted in place of `prepareFinalStage` by both chart builders when the
+ * option is configured, and nowhere else: an agent that did not ask for it
+ * runs the function above, byte for byte. Written as one stage rather than a
+ * second one because everything the capture files must agree about what the
+ * answer WAS — a second stage afterwards would leave `turn_end` reporting an
+ * answer the caller never saw.
+ *
+ * It runs AFTER the evidence gate has judged (the gate is in the Route
+ * decider, one stage earlier). That ordering is deliberate: the block is
+ * composed by the framework out of what the TOOLS declared, so subjecting it
+ * to a check for values the MODEL could not support would be asking whether
+ * the library grounded itself.
+ */
+export declare const prepareFinalWithLimitsStage: (scope: TypedScope<AgentState>) => void;

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

@@ -25,9 +25,22 @@
  * `stages/route.ts`.
  */
 import { typedEmit } from '../../../recorders/core/typedEmit.js';
-export const prepareFinalStage = (scope) => {
+import { composeAnswerWithCoverage } from '../coverage/index.js';
+/**
+ * The stage body, with the answer passed IN.
+ *
+ * One body, two entry points. The answer is a parameter rather than a read of
+ * `scope.llmLatestContent` because `.limitsTravelWithTheAnswer()` composes a
+ * different one — and everything filed here (`finalContent`, `newMessages`,
+ * which memory persists, and `turn_end.finalContent`) must agree about what
+ * the answer WAS. Note that `llmLatestContent` itself is a READ-ONLY input to
+ * this branch subflow, so there is no version of this where the composed
+ * answer is written back over it: the capture is the only place all four
+ * readers meet.
+ */
+const captureTurnPayload = (scope, answer) => {
     const iteration = scope.iteration;
-    scope.finalContent = scope.llmLatestContent;
+    scope.finalContent = answer;
     // v2.14 — attach thinking blocks to the assistant final message
     // (if any). For non-Anthropic providers this is informational; for
     // Anthropic + extended-thinking-with-tool-use, signature round-trip
@@ -59,4 +72,31 @@ export const prepareFinalStage = (scope) => {
         durationMs: Date.now() - scope.turnStartMs,
     });
 };
+export const prepareFinalStage = (scope) => {
+    captureTurnPayload(scope, scope.llmLatestContent);
+};
+/**
+ * `.limitsTravelWithTheAnswer()`'s half of prepare-final — the SAME stage,
+ * with the run's declared coverage folded into the answer first.
+ *
+ * Mounted in place of `prepareFinalStage` by both chart builders when the
+ * option is configured, and nowhere else: an agent that did not ask for it
+ * runs the function above, byte for byte. Written as one stage rather than a
+ * second one because everything the capture files must agree about what the
+ * answer WAS — a second stage afterwards would leave `turn_end` reporting an
+ * answer the caller never saw.
+ *
+ * It runs AFTER the evidence gate has judged (the gate is in the Route
+ * decider, one stage earlier). That ordering is deliberate: the block is
+ * composed by the framework out of what the TOOLS declared, so subjecting it
+ * to a check for values the MODEL could not support would be asking whether
+ * the library grounded itself.
+ */
+export const prepareFinalWithLimitsStage = (scope) => {
+    const declared = scope.coverageDeclared;
+    const answer = declared !== undefined && declared.length > 0
+        ? composeAnswerWithCoverage(scope.llmLatestContent, declared)
+        : scope.llmLatestContent;
+    captureTurnPayload(scope, answer);
+};
 //# sourceMappingURL=prepareFinal.js.map

package/dist/esm/core/agent/stages/prepareFinal.js.map

@@ -1 +1 @@
-{"version":3,"file":"prepareFinal.js","sourceRoot":"","sources":["../../../../../src/core/agent/stages/prepareFinal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AAGjE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,KAA6B,EAAQ,EAAE;IACvE,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;IAClC,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC,gBAAgB,CAAC;IAC5C,gEAAgE;IAChE,mEAAmE;IACnE,oEAAoE;IACpE,iEAAiE;IACjE,+DAA+D;IAC/D,MAAM,cAAc,GAAG,KAAK,CAAC,cAAc,CAAC;IAC5C,MAAM,WAAW,GAAG,cAAc,KAAK,SAAS,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,CAAC;IAC9E,6DAA6D;IAC7D,wCAAwC;IACxC,KAAK,CAAC,WAAW,GAAG;QAClB,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,WAAW,EAAE;QAC5C;YACE,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,KAAK,CAAC,YAAY;YAC3B,GAAG,CAAC,WAAW,IAAI,EAAE,cAAc,EAAE,CAAC;SACvC;KACF,CAAC;IAEF,SAAS,CAAC,KAAK,EAAE,oCAAoC,EAAE;QACrD,SAAS,EAAE,CAAC;QACZ,SAAS,EAAE,SAAS;QACpB,aAAa,EAAE,CAAC;KACjB,CAAC,CAAC;IACH,SAAS,CAAC,KAAK,EAAE,+BAA+B,EAAE;QAChD,SAAS,EAAE,CAAC;QACZ,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;QACxC,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;QAC1C,cAAc,EAAE,SAAS;QACzB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,WAAW;KAC3C,CAAC,CAAC;AACL,CAAC,CAAC"}
+{"version":3,"file":"prepareFinal.js","sourceRoot":"","sources":["../../../../../src/core/agent/stages/prepareFinal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AACjE,OAAO,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAGjE;;;;;;;;;;;GAWG;AACH,MAAM,kBAAkB,GAAG,CAAC,KAA6B,EAAE,MAAc,EAAQ,EAAE;IACjF,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;IAClC,KAAK,CAAC,YAAY,GAAG,MAAM,CAAC;IAC5B,gEAAgE;IAChE,mEAAmE;IACnE,oEAAoE;IACpE,iEAAiE;IACjE,+DAA+D;IAC/D,MAAM,cAAc,GAAG,KAAK,CAAC,cAAc,CAAC;IAC5C,MAAM,WAAW,GAAG,cAAc,KAAK,SAAS,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,CAAC;IAC9E,6DAA6D;IAC7D,wCAAwC;IACxC,KAAK,CAAC,WAAW,GAAG;QAClB,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,WAAW,EAAE;QAC5C;YACE,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,KAAK,CAAC,YAAY;YAC3B,GAAG,CAAC,WAAW,IAAI,EAAE,cAAc,EAAE,CAAC;SACvC;KACF,CAAC;IAEF,SAAS,CAAC,KAAK,EAAE,oCAAoC,EAAE;QACrD,SAAS,EAAE,CAAC;QACZ,SAAS,EAAE,SAAS;QACpB,aAAa,EAAE,CAAC;KACjB,CAAC,CAAC;IACH,SAAS,CAAC,KAAK,EAAE,+BAA+B,EAAE;QAChD,SAAS,EAAE,CAAC;QACZ,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;QACxC,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;QAC1C,cAAc,EAAE,SAAS;QACzB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,WAAW;KAC3C,CAAC,CAAC;AACL,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,KAA6B,EAAQ,EAAE;IACvE,kBAAkB,CAAC,KAAK,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC;AACpD,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,KAA6B,EAAQ,EAAE;IACjF,MAAM,QAAQ,GAAG,KAAK,CAAC,gBAAgB,CAAC;IACxC,MAAM,MAAM,GACV,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAC3C,CAAC,CAAC,yBAAyB,CAAC,KAAK,CAAC,gBAAgB,EAAE,QAAQ,CAAC;QAC7D,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC;IAC7B,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AACpC,CAAC,CAAC"}

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

@@ -65,6 +65,7 @@ import { safeStringify } from '../validators.js';
 import { capToolResult } from '../toolResultCap.js';
 import { applyResultCeiling } from '../resultCeiling.js';
 import { currentStepOf, pointerOf, readSkillStepIntro, skipAdvanceSentence, skipHoldSentence, skipNeedsReasonSentence, skipNothingActiveSentence, stepAdvanceSuffix, stepInProgress, SKIP_STEP_TOOL_NAME, } from '../../../lib/injection-engine/skillSteps.js';
+import { readCoverageResult, } from '../coverage/index.js';
 import { explainStatusOnlyNearMiss, pruneLeases, readToolResultEnvelope, tenantOf, } from '../toolEffects.js';
 /** Declaration order preserved, ids de-duplicated — the shape the gate's re-prompt
  *  and the `skill.rejected` payload both report as "what this gate accepts". */
@@ -306,6 +307,76 @@ export function buildToolCallsHandler(deps) {
         });
         return verdict.refusal;
     };
+    /**
+     * Coverage declarations — `absent(…)` and `coverage(…)`, recognized at the
+     * SAME execute boundaries the ceiling is measured at (one implementation,
+     * every door: a resumed call declares its coverage exactly as an inline
+     * one).
+     *
+     * Returns the DELIVERED status: `'absent'` when an absence is in play,
+     * `undefined` otherwise. That single line is the whole downstream
+     * behavioural change, and it is deliberately narrow — an absence is not an
+     * error, so nothing here sets `error: true`, nothing refuses, nothing
+     * retries, and the value the model reads is the value the tool minted. The
+     * direction-of-error argument (see `../coverage/absent.ts`) is that a
+     * *nothing-found* routed as a *failure* sends someone to investigate a
+     * healthy collector, while a *failure* routed as *nothing-found* declares a
+     * system fine that was never checked; giving the outcome its own word is
+     * how `onToolStatus` edges stop having to guess.
+     *
+     * The RECORD keeps the coverage twice over: on the emit channel (per-call
+     * facts belong there) and, because a limit is a fact about the ANSWER
+     * rather than about an attempt, in tracked state — where the final-answer
+     * block reads it. Written only when a tool declares one, so an agent that
+     * returns neither shape commits exactly what it always did.
+     */
+    const declareCoverage = (scope, call, value) => {
+        const reading = readCoverageResult(value);
+        if (reading === undefined)
+            return undefined;
+        const rows = [];
+        for (const facts of reading.declared) {
+            // Copied item by item — event payloads are detached plain data, never
+            // a shared reference into a value the tool still holds.
+            const copy = (list) => list.map((i) => ({ what: i.what, ...(i.why !== undefined && { why: i.why }) }));
+            const checked = copy(facts.coverage.checked);
+            const notChecked = copy(facts.coverage.notChecked);
+            const cannotCover = copy(facts.coverage.cannotCover);
+            if (facts.kind === 'absence') {
+                typedEmit(scope, 'agentfootprint.tools.absent', {
+                    toolName: call.toolName,
+                    toolCallId: call.toolCallId,
+                    iteration: call.iteration,
+                    ...(facts.lookedFor !== undefined && { lookedFor: facts.lookedFor }),
+                    checked,
+                    ...(notChecked.length > 0 && { notChecked }),
+                    ...(cannotCover.length > 0 && { cannotCover }),
+                });
+            }
+            else {
+                typedEmit(scope, 'agentfootprint.tools.coverage_declared', {
+                    toolName: call.toolName,
+                    toolCallId: call.toolCallId,
+                    iteration: call.iteration,
+                    ...(checked.length > 0 && { checked }),
+                    ...(notChecked.length > 0 && { notChecked }),
+                    ...(cannotCover.length > 0 && { cannotCover }),
+                });
+            }
+            rows.push({
+                kind: facts.kind,
+                toolName: call.toolName,
+                toolCallId: call.toolCallId,
+                iteration: call.iteration,
+                ...(facts.lookedFor !== undefined && { lookedFor: facts.lookedFor }),
+                checked,
+                notChecked,
+                cannotCover,
+            });
+        }
+        scope.coverageDeclared = [...(scope.coverageDeclared ?? []), ...rows];
+        return reading.status;
+    };
     // ── Step-procedure boundary (9.18.0) — ONE implementation, five sites ──
     // The batch loop and the four resume paths all finalize results; each
     // calls these where its result becomes final, so a pointer can never miss
@@ -1182,6 +1253,14 @@ export function buildToolCallsHandler(deps) {
             // judged exactly as an inline one's.
             const envelope = readToolResultEnvelope(result);
             if (envelope !== undefined) {
+                // Coverage (this release) before the ceiling, for the same reason the
+                // effects are judged even when the payload is refused: the boundary a
+                // tool declared is not the channel that can overflow, and a limit
+                // that died with an oversized result would be the silence this
+                // primitive exists to break. An absence's status is the tool's own
+                // and wins over the envelope's only when the envelope declared none.
+                const coverageStatus = declareCoverage(scope, { toolName, toolCallId, iteration }, envelope.content);
+                const declaredStatus = envelope.status ?? coverageStatus;
                 // The tool's own ceiling (9.20.0) measures the CONTENT — the channel
                 // that can overflow a context window. The DECLARED effects are small
                 // validated data and are still judged by the caller: a tool that
@@ -1189,7 +1268,7 @@ export function buildToolCallsHandler(deps) {
                 // transition. The delivered status becomes 'invalid' (the declared
                 // status described a result the model never received — the
                 // `result_refused` event keeps what was declared).
-                const refusal = refuseOverCeiling(scope, { toolName, toolCallId, iteration }, tool, envelope.content, envelope.status);
+                const refusal = refuseOverCeiling(scope, { toolName, toolCallId, iteration }, tool, envelope.content, declaredStatus);
                 if (refusal !== undefined) {
                     return {
                         result: refusal,
@@ -1198,9 +1277,14 @@ export function buildToolCallsHandler(deps) {
                         envelope: { ...envelope, content: refusal, status: 'invalid' },
                     };
                 }
-                return { result: envelope.content, executed: true, envelope };
+                return {
+                    result: envelope.content,
+                    executed: true,
+                    envelope: declaredStatus === envelope.status ? envelope : { ...envelope, status: declaredStatus },
+                };
             }
-            const refusal = refuseOverCeiling(scope, { toolName, toolCallId, iteration }, tool, result);
+            const coverageStatus = declareCoverage(scope, { toolName, toolCallId, iteration }, result);
+            const refusal = refuseOverCeiling(scope, { toolName, toolCallId, iteration }, tool, result, coverageStatus);
             if (refusal !== undefined) {
                 // Synthesized empty-effects envelope: the resume paths read the
                 // routing status off `envelope.status`, and this is how a refused
@@ -1218,6 +1302,19 @@ export function buildToolCallsHandler(deps) {
             const nearMiss = explainStatusOnlyNearMiss(result);
             if (nearMiss !== undefined)
                 warnEffect(toolName, nearMiss);
+            if (coverageStatus !== undefined) {
+                // The ceiling path's synthesized envelope, for the same reason: the
+                // resume paths read the routing status off `envelope.status`, and an
+                // absence that lost its status here would route down whichever edge a
+                // statusless result routes down — the confusion the word exists to
+                // end. Empty effects/malformed judge to nothing, so the only thing
+                // this carries is the status.
+                return {
+                    result,
+                    executed: true,
+                    envelope: { content: result, effects: [], status: coverageStatus, malformed: [] },
+                };
+            }
             return { result, executed: true };
         }
         catch (err) {
@@ -1876,6 +1973,15 @@ export function buildToolCallsHandler(deps) {
                                 if (nearMiss !== undefined)
                                     warnEffect(tc.name, nearMiss);
                             }
+                            // Coverage (this release), on the UNWRAPPED content and before
+                            // the ceiling — the boundary a tool declared is not the channel
+                            // that can overflow. A tool that spelled its own status keeps
+                            // it; otherwise an absence names the delivered outcome, so an
+                            // `onToolStatus` edge can route "we looked and there was
+                            // nothing" somewhere other than "the call broke".
+                            const coverageStatus = declareCoverage(scope, { toolName: tc.name, toolCallId: tc.id, iteration }, result);
+                            if (toolStatus === undefined)
+                                toolStatus = coverageStatus;
                             // The tool's own refusing ceiling (9.20.0) — at the execute
                             // boundary, BEFORE the gates and the after-tool chain, so
                             // governance and the agent-level cap compose over what the