agentfootprint 9.19.0 → 9.20.0

package/dist/core/tools.js

@@ -8,8 +8,37 @@
  * Emits:   N/A (types only).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defineTool = exports.warnIfInvalidToolName = exports.assertValidToolName = void 0;
+exports.defineTool = exports.warnIfInvalidToolName = exports.assertValidToolName = exports.assertResultCeiling = void 0;
 const footprintjs_1 = require("footprintjs");
+/**
+ * Refuse a `resultCeiling` this library cannot honor, at definition time —
+ * naming the tool and the fix, never failing at the first oversized result of
+ * the first run. Exported beside {@link assertValidToolName} for consumers
+ * assembling `Tool` objects by hand.
+ */
+function assertResultCeiling(toolName, ceiling) {
+    if (ceiling === undefined)
+        return;
+    const { maxChars, narrowBy } = ceiling;
+    if (!Number.isFinite(maxChars) || !Number.isInteger(maxChars) || maxChars <= 0) {
+        throw new Error(`defineTool: tool '${toolName}' declares resultCeiling.maxChars = ${String(maxChars)}, ` +
+            `which is not a positive whole number of characters. The ceiling is the size over ` +
+            `which the model reads a refusal instead of the result — to have no ceiling, omit ` +
+            `\`resultCeiling\` (absent means results are never measured, exactly as before).`);
+    }
+    if (narrowBy !== undefined) {
+        const usable = Array.isArray(narrowBy) &&
+            narrowBy.length > 0 &&
+            narrowBy.every((n) => typeof n === 'string' && n.trim().length > 0);
+        if (!usable) {
+            throw new Error(`defineTool: tool '${toolName}' declares resultCeiling.narrowBy = ` +
+                `${JSON.stringify(narrowBy)}, which names nothing the refusal could suggest. ` +
+                `List at least one parameter name (non-empty strings, e.g. ['limit', 'fields']), ` +
+                `or drop the field — omitting it is how "no suggestions" is said.`);
+        }
+    }
+}
+exports.assertResultCeiling = assertResultCeiling;
 /**
  * Ergonomic builder for `Tool`. Equivalent to constructing an object
  * literal with `schema` + `execute`, but flatter and safer — the name
@@ -81,6 +110,9 @@ function warnIfInvalidToolName(name) {
 exports.warnIfInvalidToolName = warnIfInvalidToolName;
 function defineTool(options) {
     warnIfInvalidToolName(options.name);
+    // A ceiling that cannot cap fails HERE, naming the tool — not at the first
+    // oversized result of the first run.
+    assertResultCeiling(options.name, options.resultCeiling);
     return {
         schema: {
             name: options.name,
@@ -94,6 +126,7 @@ function defineTool(options) {
         // Copied verbatim, never inferred — an empty array is a tool that declared
         // it touches nothing, which is a different statement from saying nothing.
         ...(options.capabilities !== undefined && { capabilities: options.capabilities }),
+        ...(options.resultCeiling !== undefined && { resultCeiling: options.resultCeiling }),
         execute: options.execute,
     };
 }

package/dist/core/tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/core/tools.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH,6CAAwC;AAoNxC;;;;;;;;;;;;;;;;;;GAkBG;AACH;;;;;;;GAOG;AACH,MAAM,gBAAgB,GAAG,uBAAuB,CAAC;AAEjD;;;;;;GAMG;AACH,SAAgB,mBAAmB,CAAC,IAAa;IAC/C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CACb,yDAAyD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAClF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,MAAM,MAAM,GACV,IAAI,CAAC,MAAM,GAAG,EAAE;YACd,CAAC,CAAC,SAAS,IAAI,CAAC,MAAM,iBAAiB;YACvC,CAAC,CAAC,mFAAmF,CAAC;QAC1F,MAAM,IAAI,KAAK,CACb,aAAa,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,MAAM,IAAI;YAC/C,sFAAsF;YACtF,wEAAwE;YACxE,0DAA0D,CAC7D,CAAC;IACJ,CAAC;AACH,CAAC;AAlBD,kDAkBC;AAED;;;;;;GAMG;AACH,SAAgB,qBAAqB,CAAC,IAAa;IACjD,IAAI,CAAC,IAAA,uBAAS,GAAE;QAAE,OAAO;IACzB,IAAI,CAAC;QACH,mBAAmB,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,sCAAsC;QACtC,OAAO,CAAC,IAAI,CAAC,4BAA6B,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;IACnE,CAAC;AACH,CAAC;AARD,sDAQC;AAED,SAAgB,UAAU,CACxB,OAA0C;IAE1C,qBAAqB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO;QACL,MAAM,EAAE;YACN,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;SACvE;QACD,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QAC9C,uEAAuE;QACvE,2DAA2D;QAC3D,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,OAAwB,EAAE,CAAC;QACnF,2EAA2E;QAC3E,0EAA0E;QAC1E,GAAG,CAAC,OAAO,CAAC,YAAY,KAAK,SAAS,IAAI,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC;QACjF,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC;AACJ,CAAC;AAnBD,gCAmBC"}
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/core/tools.ts"],"names":[],"mappings":"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"}

package/dist/esm/core/agent/resultCeiling.d.ts

@@ -0,0 +1,58 @@
+/**
+ * resultCeiling — the refusing ceiling a tool declares on its OWN result
+ * (9.20.0). One owner of the measurement and the refusal sentence; the
+ * tool-dispatch loop (`stages/toolCalls.ts`) calls it at every boundary where
+ * a handler's return becomes final, so a resumed call is refused exactly as an
+ * inline one.
+ *
+ * Pattern: measured refusal at the dispatch boundary — the sibling of
+ *          `toolResultCap.ts`, with the OPPOSITE answer to overflow, because
+ *          the two serve different owners:
+ *
+ *   • `maxToolResultChars` (agent-level, 9.11.0) TRUNCATES: the operator caps
+ *     tools they did not write, so the most honest deliverable is a marker
+ *     plus a verbatim head of whatever came back.
+ *   • `resultCeiling` (per-tool, this module) REFUSES: the AUTHOR declared
+ *     what a sane result is and which parameters (`narrowBy`) make a retry
+ *     smaller. A truncated result reads as a complete one — the model cannot
+ *     tell the data ends where the cut happened and fabricates from the part
+ *     it saw — while a refusal that says "No data was returned" and names the
+ *     narrowing parameters produces a clean retry (field-verified on a
+ *     ~191k-char return).
+ *
+ * The oversized payload never leaves the dispatch: not into history, not into
+ * `stream.tool_end`, not into any recorder. The RECORD keeps the truth as the
+ * typed `agentfootprint.tools.result_refused` event (true size, ceiling,
+ * suggestions), emitted by the caller beside the replacement; the delivered
+ * result carries status `'invalid'` — the closed-set member whose corrective
+ * action is "fix the call" — so `onToolStatus` edges can route on it.
+ *
+ * Emits: nothing itself (pure measurement); zero-cost-when-unused — no
+ * declared ceiling means one `undefined` check and byte-identical behavior.
+ */
+import type { ToolResultCeiling } from '../tools.js';
+/** What an over-ceiling measurement hands the dispatch loop: the sentence the
+ *  model reads and the true size for the record. `undefined` from
+ *  {@link applyResultCeiling} means no ceiling or under it — untouched path. */
+export interface ResultCeilingRefusal {
+    /** The teaching refusal — the ONLY thing the model (and every downstream
+     *  channel) receives in place of the oversized payload. */
+    readonly refusal: string;
+    /** The stringified result's true length — the record's fact, carried by the
+     *  `tools.result_refused` event, never by any content channel. */
+    readonly sizeChars: number;
+}
+/**
+ * Measure one handler result against the tool's declared ceiling.
+ *
+ * Returns `undefined` when there is no ceiling or the result fits — the caller
+ * keeps every byte of today's path. Over the ceiling, returns the refusal to
+ * deliver INSTEAD of the payload. What is measured is the string the model
+ * would have read (strings as-is, everything else `safeStringify`d) — the same
+ * rule `toolResultCap.ts` measures by, so the two ceilings always argue about
+ * the same number.
+ */
+export declare function applyResultCeiling(value: unknown, opts: {
+    readonly toolName: string;
+    readonly ceiling: ToolResultCeiling | undefined;
+}): ResultCeilingRefusal | undefined;

package/dist/esm/core/agent/resultCeiling.js

@@ -0,0 +1,61 @@
+/**
+ * resultCeiling — the refusing ceiling a tool declares on its OWN result
+ * (9.20.0). One owner of the measurement and the refusal sentence; the
+ * tool-dispatch loop (`stages/toolCalls.ts`) calls it at every boundary where
+ * a handler's return becomes final, so a resumed call is refused exactly as an
+ * inline one.
+ *
+ * Pattern: measured refusal at the dispatch boundary — the sibling of
+ *          `toolResultCap.ts`, with the OPPOSITE answer to overflow, because
+ *          the two serve different owners:
+ *
+ *   • `maxToolResultChars` (agent-level, 9.11.0) TRUNCATES: the operator caps
+ *     tools they did not write, so the most honest deliverable is a marker
+ *     plus a verbatim head of whatever came back.
+ *   • `resultCeiling` (per-tool, this module) REFUSES: the AUTHOR declared
+ *     what a sane result is and which parameters (`narrowBy`) make a retry
+ *     smaller. A truncated result reads as a complete one — the model cannot
+ *     tell the data ends where the cut happened and fabricates from the part
+ *     it saw — while a refusal that says "No data was returned" and names the
+ *     narrowing parameters produces a clean retry (field-verified on a
+ *     ~191k-char return).
+ *
+ * The oversized payload never leaves the dispatch: not into history, not into
+ * `stream.tool_end`, not into any recorder. The RECORD keeps the truth as the
+ * typed `agentfootprint.tools.result_refused` event (true size, ceiling,
+ * suggestions), emitted by the caller beside the replacement; the delivered
+ * result carries status `'invalid'` — the closed-set member whose corrective
+ * action is "fix the call" — so `onToolStatus` edges can route on it.
+ *
+ * Emits: nothing itself (pure measurement); zero-cost-when-unused — no
+ * declared ceiling means one `undefined` check and byte-identical behavior.
+ */
+import { safeStringify } from './validators.js';
+/**
+ * Measure one handler result against the tool's declared ceiling.
+ *
+ * Returns `undefined` when there is no ceiling or the result fits — the caller
+ * keeps every byte of today's path. Over the ceiling, returns the refusal to
+ * deliver INSTEAD of the payload. What is measured is the string the model
+ * would have read (strings as-is, everything else `safeStringify`d) — the same
+ * rule `toolResultCap.ts` measures by, so the two ceilings always argue about
+ * the same number.
+ */
+export function applyResultCeiling(value, opts) {
+    const ceiling = opts.ceiling;
+    if (ceiling === undefined)
+        return undefined;
+    const text = typeof value === 'string' ? value : safeStringify(value);
+    if (text.length <= ceiling.maxChars)
+        return undefined;
+    const narrow = ceiling.narrowBy !== undefined && ceiling.narrowBy.length > 0
+        ? ` — e.g. pass ${ceiling.narrowBy.map((n) => `'${n}'`).join(', ')}`
+        : '';
+    return {
+        refusal: `Result too large: ${opts.toolName} returned ${text.length} chars, over its declared ` +
+            `${ceiling.maxChars}-char ceiling. Narrow the request and call again${narrow}. ` +
+            `No data was returned.`,
+        sizeChars: text.length,
+    };
+}
+//# sourceMappingURL=resultCeiling.js.map

package/dist/esm/core/agent/resultCeiling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resultCeiling.js","sourceRoot":"","sources":["../../../../src/core/agent/resultCeiling.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAchD;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAc,EACd,IAAoF;IAEpF,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;IAC7B,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC5C,MAAM,IAAI,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;IACtE,IAAI,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC;IACtD,MAAM,MAAM,GACV,OAAO,CAAC,QAAQ,KAAK,SAAS,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC;QAC3D,CAAC,CAAC,gBAAgB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;QACpE,CAAC,CAAC,EAAE,CAAC;IACT,OAAO;QACL,OAAO,EACL,qBAAqB,IAAI,CAAC,QAAQ,aAAa,IAAI,CAAC,MAAM,4BAA4B;YACtF,GAAG,OAAO,CAAC,QAAQ,mDAAmD,MAAM,IAAI;YAChF,uBAAuB;QACzB,SAAS,EAAE,IAAI,CAAC,MAAM;KACvB,CAAC;AACJ,CAAC"}

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

@@ -57,6 +57,7 @@ import { recordDecisions } from '../middleware/ledger.js';
 import { formatToolArgIssues, validateToolArgs, } from '../toolArgsValidation.js';
 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 { explainStatusOnlyNearMiss, pruneLeases, readToolResultEnvelope, tenantOf, } from '../toolEffects.js';
 /** Declaration order preserved, ids de-duplicated — the shape the gate's re-prompt
@@ -252,6 +253,38 @@ export function buildToolCallsHandler(deps) {
                 : capToolResult(values.modelResult, { toolName, maxChars: max }).value,
         };
     };
+    /**
+     * 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;
+        const verdict = applyResultCeiling(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;
+    };
     // ── 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
@@ -789,8 +822,37 @@ export function buildToolCallsHandler(deps) {
             // judged exactly as an inline one's.
             const envelope = readToolResultEnvelope(result);
             if (envelope !== undefined) {
+                // 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
+                // proposed a transition and overflowed its payload does not lose the
+                // 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);
+                if (refusal !== undefined) {
+                    return {
+                        result: refusal,
+                        executed: true,
+                        ceilingRefused: true,
+                        envelope: { ...envelope, content: refusal, status: 'invalid' },
+                    };
+                }
                 return { result: envelope.content, executed: true, envelope };
             }
+            const refusal = refuseOverCeiling(scope, { toolName, toolCallId, iteration }, tool, result);
+            if (refusal !== undefined) {
+                // Synthesized empty-effects envelope: the resume paths read the
+                // routing status off `envelope.status`, and this is how a refused
+                // NON-envelope result carries `'invalid'` there without every path
+                // learning about ceilings. Empty effects/malformed judge to nothing.
+                return {
+                    result: refusal,
+                    executed: true,
+                    ceilingRefused: true,
+                    envelope: { content: refusal, effects: [], status: 'invalid', malformed: [] },
+                };
+            }
             // A status-only shape missing its `effects: []` marker is DATA (bytes
             // unchanged) — but never silently: name the dropped marker in dev mode.
             const nearMiss = explainStatusOnlyNearMiss(result);
@@ -932,6 +994,10 @@ export function buildToolCallsHandler(deps) {
                 let denied = false;
                 /** True once `tool.execute` has been entered — see `afterMoment`. */
                 let executed = false;
+                /** The tool's own `resultCeiling` refused this call's result (9.20.0)
+                 *  — the call ran, but it must not complete a procedure step: the
+                 *  refusal's own instruction is to call again. */
+                let ceilingRefused = false;
                 let haltContext;
                 if (permissionChecker) {
                     try {
@@ -1395,6 +1461,21 @@ export function buildToolCallsHandler(deps) {
                                 if (nearMiss !== undefined)
                                     warnEffect(tc.name, nearMiss);
                             }
+                            // 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
+                            // model will actually read (the read_skill-gate precedent).
+                            // A recognized envelope's DECLARED effects (`toolEnvelope`)
+                            // are still judged below — the effects channel is not the
+                            // channel that overflowed; the delivered status becomes
+                            // 'invalid' so `onToolStatus` edges can route the overflow
+                            // (the declared one rides the `result_refused` event).
+                            const overflowRefusal = refuseOverCeiling(scope, { toolName: tc.name, toolCallId: tc.id, iteration }, tool, result, toolStatus);
+                            if (overflowRefusal !== undefined) {
+                                ceilingRefused = true;
+                                result = overflowRefusal;
+                                toolStatus = 'invalid';
+                            }
                             await endCall(tc.id);
                         }
                         catch (err) {
@@ -1552,8 +1633,10 @@ export function buildToolCallsHandler(deps) {
                     // The advance: only a call that RAN clean completes a step — an
                     // error result never advances (the pointer holds; the model
                     // retries, skips with a reason, or routes around), and neither
-                    // does a permission denial or a gate refusal.
-                    if (executed && !error && !denied && !skillRejected) {
+                    // does a permission denial, a gate refusal, or a ceiling refusal
+                    // (the model holds no data and was told to call again — advancing
+                    // would contradict the refusal's own instruction).
+                    if (executed && !error && !denied && !skillRejected && !ceilingRefused) {
                         resultStr += applyStepReturn(scope, {
                             toolName: tc.name,
                             toolCallId: tc.id,
@@ -1828,9 +1911,14 @@ export function buildToolCallsHandler(deps) {
                         const dispatched = await resolveCredentialAndExecute(scope, tool, toolName, rest.args, toolCallId, iteration, env);
                         result = dispatched.result;
                         error = dispatched.error;
-                        stepToolRan = dispatched.executed === true && error !== true;
-                        if (stepToolRan)
+                        // A ceiling-refused call RAN but must not advance a step (9.20.0);
+                        // its envelope — status 'invalid' plus any surviving declared
+                        // effects — is still picked up and judged below.
+                        stepToolRan =
+                            dispatched.executed === true && error !== true && dispatched.ceilingRefused !== true;
+                        if (dispatched.executed === true && error !== true) {
                             resumeEnvelope = dispatched.envelope;
+                        }
                         // skip_step behind a middleware ask, approved (9.18.0): the
                         // placeholder just landed — replace it with the authoritative
                         // sentence BEFORE the chain's last word, the execute loop's
@@ -1954,9 +2042,12 @@ export function buildToolCallsHandler(deps) {
                     const dispatched = await resolveCredentialAndExecute(scope, tool, toolName, args, toolCallId, iteration, env);
                     result = dispatched.result;
                     error = dispatched.error;
-                    stepToolRan = dispatched.executed === true && error !== true;
-                    if (stepToolRan)
+                    // Same ceiling law as the ask path: ran ≠ completed a step (9.20.0).
+                    stepToolRan =
+                        dispatched.executed === true && error !== true && dispatched.ceilingRefused !== true;
+                    if (dispatched.executed === true && error !== true) {
                         resumeEnvelope = dispatched.envelope;
+                    }
                     // Consent moved the execution to this side of the pause; the rules
                     // about results move with it.
                     if (dispatched.executed === true) {
@@ -2075,8 +2166,13 @@ export function buildToolCallsHandler(deps) {
                 modelResult = consentCapped.modelResult;
                 let consentResultStr = typeof modelResult === 'string' ? modelResult : safeStringify(modelResult);
                 // Step boundary (9.18.0) — a step tool that waited on 3LO consent
-                // advances the moment its resumed dispatch really ran, clean.
-                if (deps.stepPlanFor && dispatched.executed === true && error !== true) {
+                // advances the moment its resumed dispatch really ran, clean. A
+                // ceiling-refused result is not clean (9.20.0): the model holds no
+                // data and was told to call again.
+                if (deps.stepPlanFor &&
+                    dispatched.executed === true &&
+                    error !== true &&
+                    dispatched.ceilingRefused !== true) {
                     consentResultStr += applyStepReturn(scope, { toolName, toolCallId, iteration });
                 }
                 // Typed tool effects (9.19.0) — same judge as every other path.