agentfootprint 9.20.0 → 9.22.0

package/dist/core/agent/buildToolRegistry.js

@@ -41,13 +41,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildToolRegistry = void 0;
 const skillTools_js_1 = require("../../lib/injection-engine/skillTools.js");
 const skillSteps_js_1 = require("../../lib/injection-engine/skillSteps.js");
+const present_js_1 = require("../../artifacts/present.js");
+const presentTool_js_1 = require("./presentTool.js");
 const tools_js_1 = require("../tools.js");
 /**
  * Compose the augmented tool registry from the static `.tool()`
  * registry + the agent's injections (skills only). Throws on tool-
  * name collisions across sources.
  */
-function buildToolRegistry(registry, injections) {
+function buildToolRegistry(registry, injections, options = {}) {
     const skills = injections.filter((i) => i.flavor === 'skill');
     // Collect skill tools, deduping by name when the SAME Tool reference
     // is shared across skills. Different Tool implementations under the
@@ -91,9 +93,36 @@ function buildToolRegistry(registry, injections) {
         ? // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
             [{ name: 'read_skill', tool: (0, skillTools_js_1.buildReadSkillTool)(skills) }]
         : [];
+    // ── `present` — the hand-to-the-screen tool (9.22.0) ────────────────
+    // Auto-attached as a FULL citizen (schema offered + dispatchable) ONLY
+    // when a store is attached — the read_skill seam. The name is reserved
+    // the moment the store is: a consumer tool already holding 'present'
+    // would silently win the dispatch map and the model's presentations
+    // would run somebody else's function — accepted-and-silently-wrong, so
+    // it is refused by name (the skip_step law). Without a store, nothing
+    // here runs and a consumer's own 'present' is nobody's business.
+    const presentEntries = [];
+    if (options.hasArtifactStore === true) {
+        const holders = [
+            ...registry.map((e) => e.name),
+            ...skillToolEntries.map((e) => e.name),
+            ...sharedSkillTools.keys(),
+        ];
+        if (holders.includes(present_js_1.PRESENT_TOOL_NAME)) {
+            throw new Error(`Agent: tool name '${present_js_1.PRESENT_TOOL_NAME}' is reserved when an artifact store is ` +
+                `attached — the framework auto-attaches the hand-to-the-screen tool under that ` +
+                `name, and a same-named tool would silently take over the model's presentations. ` +
+                `Rename your tool, or drop the \`artifacts\` store.`);
+        }
+        presentEntries.push({
+            name: present_js_1.PRESENT_TOOL_NAME,
+            tool: (0, presentTool_js_1.buildPresentTool)(),
+        });
+    }
     const augmentedRegistry = [
         ...registry,
         ...readSkillEntries,
+        ...presentEntries,
         ...skillToolEntries,
     ];
     // Final cross-source name-uniqueness check: static .tool() vs

package/dist/core/agent/buildToolRegistry.js.map

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

package/dist/core/agent/presentTool.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * presentTool — the SHELL of the auto-attached `present` tool (9.22.0).
+ *
+ * Pattern: the `skip_step` placeholder, exactly. The tool here carries the
+ * schema the model reads; the AUTHORITATIVE work — `head` the ref under the
+ * run's scope, compose the description-snapshot result, emit
+ * `agentfootprint.artifacts.presented` — lives in the tool-calls stage
+ * (`applyPresent` in `stages/toolCalls.ts`), which OVERWRITES this
+ * placeholder's result. Bookkeeping lives where the batch order lives: the
+ * stage owns the scope, the store, and the typed emit channel; a tool's
+ * execute owns none of them.
+ *
+ * Attached by `buildToolRegistry` ONLY when a store is attached (the
+ * `read_skill` seam): a storeless agent never sees the tool, never reserves
+ * the name, and is byte-identical.
+ *
+ * The pure half — `PRESENT_TOOL_NAME`, `presentArtifact`, the snapshot
+ * shapes — lives in `src/artifacts/present.ts`, which cannot import core.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPresentTool = void 0;
+const present_js_1 = require("../../artifacts/present.js");
+const tools_js_1 = require("../tools.js");
+/** Build the placeholder `present` tool. See the module header. */
+function buildPresentTool() {
+    return (0, tools_js_1.defineTool)({
+        name: present_js_1.PRESENT_TOOL_NAME,
+        description: 'Hand a stored artifact to the screen instead of writing its contents out. Pass the ' +
+            "art_… ref and say how to render it (as: 'bar-chart', 'table', 'image', …); the " +
+            'screen redeems the ref itself. Use this to finish an answer whose substance is data ' +
+            'you stored — never retype what the store already holds.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ref: {
+                    type: 'string',
+                    description: 'The art_… ref of the stored artifact to present.',
+                },
+                as: {
+                    type: 'string',
+                    description: "Consumer vocabulary for how the screen should render it: 'bar-chart', 'table', " +
+                        "'image', 'markdown', … Say what it is; the screen picks the renderer.",
+                },
+                label: {
+                    type: 'string',
+                    description: "Optional human title for this presentation (e.g. 'Q3 sales by region').",
+                },
+            },
+            required: ['ref', 'as'],
+            additionalProperties: false,
+        },
+        execute: () => 'present noted. (Raw placeholder — the agent loop replaces this result with the ' +
+            'description snapshot; reading it verbatim means the runner that dispatched present ' +
+            'has no artifact store behind it.)',
+    });
+}
+exports.buildPresentTool = buildPresentTool;
+//# sourceMappingURL=presentTool.js.map

package/dist/core/agent/presentTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presentTool.js","sourceRoot":"","sources":["../../../src/core/agent/presentTool.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AAEH,2DAA+D;AAC/D,0CAAoD;AAEpD,mEAAmE;AACnE,SAAgB,gBAAgB;IAC9B,OAAO,IAAA,qBAAU,EAAsD;QACrE,IAAI,EAAE,8BAAiB;QACvB,WAAW,EACT,qFAAqF;YACrF,iFAAiF;YACjF,sFAAsF;YACtF,yDAAyD;QAC3D,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,GAAG,EAAE;oBACH,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,kDAAkD;iBAChE;gBACD,EAAE,EAAE;oBACF,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,iFAAiF;wBACjF,uEAAuE;iBAC1E;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,yEAAyE;iBACvF;aACF;YACD,QAAQ,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC;YACvB,oBAAoB,EAAE,KAAK;SAC5B;QACD,OAAO,EAAE,GAAG,EAAE,CACZ,iFAAiF;YACjF,qFAAqF;YACrF,mCAAmC;KACtC,CAAoB,CAAC;AACxB,CAAC;AAlCD,4CAkCC"}

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

@@ -52,6 +52,10 @@ const extractSequence_js_1 = require("../../../security/extractSequence.js");
 const skillTarget_js_1 = require("../../../security/skillTarget.js");
 const routingPolicy_js_1 = require("../../../lib/injection-engine/routingPolicy.js");
 const types_js_2 = require("../../../identity/types.js");
+const capability_js_1 = require("../../../artifacts/capability.js");
+const wants_js_1 = require("../../../artifacts/wants.js");
+const present_js_1 = require("../../../artifacts/present.js");
+const placement_js_1 = require("../../../artifacts/placement.js");
 const consent_js_1 = require("../../../identity/consent.js");
 const pause_js_1 = require("../../pause.js");
 const checkin_js_1 = require("../../checkin.js");
@@ -640,6 +644,248 @@ function buildToolCallsHandler(deps) {
             },
         };
     };
+    /**
+     * `ctx.artifacts` + `ctx.hasArtifacts` for one dispatch — the claim-check
+     * capability, shaped exactly like `ctx.credentials` (9.21.0).
+     *
+     * The SCOPE is `scope.runIdentity` — the tuple the seed stage committed and
+     * memory already scopes on (an anonymous run isolates to its own runId, a
+     * session-bound run to its sessionId, an identity-carrying run to the
+     * caller's tenant/principal). Composed HERE, where the tool cannot reach:
+     * the capability closes over it, so a ref alone opens nothing and a tool
+     * can never widen the scope it resolves under. Detached to a plain object
+     * so the store never holds a live scope proxy.
+     *
+     * Every fact the capability reports rides the ordinary emit channel via
+     * `typedEmit`, mid-stage, carrying the real runtimeStageId — collected
+     * during traversal, exactly like `credential.failed`. Payload bytes never
+     * enter an event; the facts are meta only.
+     *
+     * With NO store attached the capability is the fail-closed teacher and no
+     * runIdentity read happens — a storeless agent's trace stays byte-identical.
+     */
+    const toolArtifacts = (scope, toolName, toolCallId) => {
+        const onEvent = (fact) => {
+            switch (fact.type) {
+                case 'minted': {
+                    const meta = fact.meta;
+                    (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.artifacts.minted', {
+                        ref: meta.ref,
+                        kind: meta.kind,
+                        mediaType: meta.mediaType,
+                        bytes: meta.bytes,
+                        ...(meta.label !== undefined && { label: meta.label }),
+                        ...(meta.digest !== undefined && { digest: meta.digest }),
+                        ...(meta.expiresAt !== undefined && { expiresAt: meta.expiresAt }),
+                        ...(meta.origin !== undefined && { origin: meta.origin }),
+                        ...(meta.parentRefs !== undefined && { parentRefs: meta.parentRefs }),
+                        tool: toolName,
+                    });
+                    return;
+                }
+                case 'resolved':
+                    (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.artifacts.resolved', {
+                        ref: fact.ref,
+                        via: fact.via,
+                        kind: fact.kind,
+                        bytes: fact.bytes,
+                        tool: toolName,
+                    });
+                    return;
+                case 'expired':
+                    (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.artifacts.expired', {
+                        ref: fact.swept.ref,
+                        reason: fact.swept.reason,
+                        kind: fact.swept.kind,
+                        bytes: fact.swept.bytes,
+                        tool: toolName,
+                    });
+                    return;
+                case 'refused':
+                    (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.artifacts.refused', {
+                        op: fact.op,
+                        reason: fact.reason,
+                        ...(fact.ref !== undefined && { ref: fact.ref }),
+                        ...(fact.detail !== undefined && { detail: fact.detail }),
+                        tool: toolName,
+                    });
+                    return;
+            }
+        };
+        const store = deps.artifactStore;
+        if (store === undefined) {
+            return { artifacts: (0, capability_js_1.unconfiguredArtifacts)(onEvent), hasArtifacts: false };
+        }
+        const facts = deps.currentRun?.();
+        const artifacts = (0, capability_js_1.bindArtifacts)(store, runScopeOf(scope), {
+            origin: { ...(facts?.runId !== undefined && { runId: facts.runId }), toolCallId },
+            onEvent,
+        });
+        return { artifacts, hasArtifacts: true };
+    };
+    /**
+     * The run's artifact scope — `scope.runIdentity`, detached to a plain
+     * object so no store or resolver ever holds a live scope proxy. ONE
+     * composition shared by the capability binding, `wants` resolution,
+     * `present`, and placement: four doors, one isolation rule, no drift.
+     */
+    const runScopeOf = (scope) => {
+        const identity = scope.runIdentity;
+        return {
+            conversationId: identity.conversationId,
+            ...(identity.tenant !== undefined && { tenant: identity.tenant }),
+            ...(identity.principal !== undefined && { principal: identity.principal }),
+        };
+    };
+    // ── Ref ARGUMENTS at dispatch (9.22.0, Leg 1) — ONE resolver, every door ──
+    // The batch loop and `resolveCredentialAndExecute` (the resume paths) both
+    // dispatch tools; each calls this BEFORE credential resolution — never
+    // acquire credentials for a call that won't run — so a declared ref is
+    // judged identically whichever door the call came through. Success rides
+    // the existing `artifacts.resolved` (one event per resolved argument);
+    // refusals ride `artifacts.refused` with `op: 'dispatch'`, and the tool is
+    // NOT executed — the model reads the teaching refusal instead.
+    const resolveWantsAtDispatch = async (scope, toolName, wants, args) => {
+        const store = deps.artifactStore;
+        if (store === undefined) {
+            // Statically registered tools are refused at BUILD; this serves the
+            // doors that only meet the tool at dispatch (provider-served tools).
+            (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.artifacts.refused', {
+                op: 'dispatch',
+                reason: 'no-store',
+                detail: `tool '${toolName}' declares wants but no artifact store is attached`,
+                tool: toolName,
+            });
+            return { ok: false, refusal: (0, wants_js_1.wantsNeedsStoreRefusal)(toolName, wants) };
+        }
+        const verdict = await (0, wants_js_1.resolveToolWants)(store, runScopeOf(scope), toolName, wants, args);
+        if (!verdict.ok) {
+            for (const refusal of verdict.refusals) {
+                (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.artifacts.refused', {
+                    op: 'dispatch',
+                    reason: refusal.reason,
+                    ...(refusal.ref !== undefined && { ref: refusal.ref }),
+                    detail: refusal.detail,
+                    tool: toolName,
+                });
+            }
+            return { ok: false, refusal: verdict.refusal };
+        }
+        for (const { meta } of verdict.resolved) {
+            (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.artifacts.resolved', {
+                ref: meta.ref,
+                via: 'get',
+                kind: meta.kind,
+                bytes: meta.bytes,
+                tool: toolName,
+            });
+        }
+        return {
+            ok: true,
+            args: verdict.args,
+            // Absent when nothing resolved (no declared arg was passed): absent
+            // and empty are different facts, and `ctx.wanted` keeps them apart.
+            ...(verdict.resolved.length > 0 && { wanted: verdict.wanted }),
+        };
+    };
+    // ── The `present` tool's authoritative result (9.22.0, Leg 2) ──────────
+    // The skip_step pattern: the auto-attached placeholder ran; the stage —
+    // which owns the scope, the store and the emit channel — OVERWRITES its
+    // result with the description snapshot (or the teaching refusal), so
+    // governance rules and the caps compose over what the model will read.
+    const applyPresent = async (scope, call) => {
+        const store = deps.artifactStore;
+        if (store === undefined) {
+            // Unreachable through the Agent (the tool is only attached beside a
+            // store) — kept for the same reason the placeholder text exists.
+            return {
+                ok: false,
+                text: 'present has no artifact store behind it here; nothing was presented.',
+            };
+        }
+        const outcome = await (0, present_js_1.presentArtifact)(store, runScopeOf(scope), call.args);
+        if (!outcome.ok) {
+            (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.artifacts.refused', {
+                op: 'dispatch',
+                reason: outcome.missedRef !== undefined ? 'missing-or-expired' : 'invalid-input',
+                ...(outcome.missedRef !== undefined && { ref: outcome.missedRef }),
+                detail: outcome.refusal,
+                tool: present_js_1.PRESENT_TOOL_NAME,
+            });
+            return { ok: false, text: outcome.refusal };
+        }
+        const { ref, as, snapshot } = outcome.result;
+        (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.artifacts.resolved', {
+            ref,
+            via: 'head',
+            kind: snapshot.kind,
+            bytes: snapshot.bytes,
+            tool: present_js_1.PRESENT_TOOL_NAME,
+        });
+        (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.artifacts.presented', {
+            ref,
+            as,
+            snapshot: { ...snapshot },
+            toolCallId: call.toolCallId,
+            iteration: call.iteration,
+        });
+        // The snapshot lives INSIDE the tool result — the one thing provider
+        // history keeps typed and durable — so a reloaded conversation can
+        // re-draw the pane, or state honestly why it can't.
+        return { ok: true, text: (0, validators_js_1.safeStringify)(outcome.result) };
+    };
+    // ── The placement threshold (9.22.0, Leg 3) — ONE judge, every door ────
+    // Called beside every `capResults` site, on the FINALIZED values (after
+    // the tool's own resultCeiling, after the after-tool chain) and before the
+    // truncation net — the stated precedence: author's refusal first, then the
+    // operator's ref-ing, then the last-resort net (which then measures the
+    // ticket). A placed result is a TICKET, not a refusal: the caller's
+    // effects/step bookkeeping proceeds exactly as if the payload had landed.
+    const placeResults = async (scope, call, values, eligible) => {
+        const placement = deps.placement;
+        if (placement === undefined || deps.artifactStore === undefined || !eligible)
+            return values;
+        const text = typeof values.modelResult === 'string'
+            ? values.modelResult
+            : (0, validators_js_1.safeStringify)(values.modelResult);
+        if (text.length <= placement.maxInlineChars)
+            return values;
+        const bound = toolArtifacts(scope, call.toolName, call.toolCallId);
+        let meta;
+        try {
+            // The payload stored is the EXACT text the model would have read —
+            // byte-faithful, so a consumer redeems precisely what was displaced.
+            // `mediaType` states what that text is: a JSON serialization when the
+            // tool returned a value, plain text when it returned a string.
+            meta = await bound.artifacts.put({
+                kind: (0, placement_js_1.placedResultKind)(call.toolName),
+                mediaType: typeof values.modelResult === 'string' ? 'text/plain' : 'application/json',
+                data: text,
+                label: `${call.toolName} result`,
+            });
+        }
+        catch (err) {
+            // The store could not take it (a payload over the whole scope budget,
+            // say). The refusal is already on the record via the capability sink;
+            // the honest fallback is today's path — the truncation net still
+            // measures what placement could not lift. Named in dev mode.
+            if ((0, footprintjs_1.isDevMode)()) {
+                // eslint-disable-next-line no-console
+                console.warn(`agentfootprint placement: tool '${call.toolName}' result (${text.length} chars) ` +
+                    `exceeded the ${placement.maxInlineChars}-char threshold but could not be ` +
+                    `stored: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            return values;
+        }
+        const substitute = (0, placement_js_1.placedToolResult)(call.toolName, meta, text.length, placement.maxInlineChars);
+        return {
+            // One ticket when the two channels carry one value — the capResults
+            // law. A chain-transformed `result` keeps its own truth and meets the
+            // truncation net below, exactly as before.
+            result: values.result === values.modelResult ? substitute : values.result,
+            modelResult: substitute,
+        };
+    };
     /**
      * Fire the `'call'`-scoped cleanups this tool call registered.
      *
@@ -746,6 +992,18 @@ function buildToolCallsHandler(deps) {
     const resolveCredentialAndExecute = async (scope, tool, toolName, args, toolCallId, iteration, env) => {
         if (!tool)
             return { result: `Unknown tool: ${toolName}`, error: true };
+        // Declared artifact arguments (9.22.0) — the same resolution the batch
+        // loop applies, at this door: a resumed call's refs are judged exactly
+        // as an inline call's, BEFORE credentials, and a refusal means the tool
+        // does not run.
+        let wantedMeta;
+        if (tool.wants !== undefined) {
+            const resolution = await resolveWantsAtDispatch(scope, toolName, tool.wants, args);
+            if (!resolution.ok)
+                return { result: resolution.refusal, error: true };
+            args = resolution.args;
+            wantedMeta = resolution.wanted;
+        }
         const runIdentity = scope.runIdentity;
         let resolvedCredential;
         const need = tool.needs;
@@ -817,6 +1075,8 @@ function buildToolCallsHandler(deps) {
                 credentials: reportingCredentials(credentials, scope, toolName),
                 hasCredentials,
                 ...(resolvedCredential && { credential: resolvedCredential }),
+                ...toolArtifacts(scope, toolName, toolCallId),
+                ...(wantedMeta !== undefined && { wanted: wantedMeta }),
                 ...sessionContext(scope, toolName, toolCallId),
             });
             await endCall(toolCallId);
@@ -1325,6 +1585,29 @@ function buildToolCallsHandler(deps) {
                     }
                 }
                 if (!denied && !argsRejected) {
+                    // ── Declared artifact arguments (9.22.0) ──────────────────────
+                    // The `needs` precedent applied to data: resolve the tool's
+                    // declared `wants` refs BEFORE credential resolution (never
+                    // acquire credentials for a call that won't run) and BEFORE
+                    // execute — a stale/unknown/wrong-kind ref never reaches the
+                    // tool; the model reads a teaching refusal listing the live refs
+                    // of the wanted kind. On success `callArgs` carries the RESOLVED
+                    // DATA and `ctx.wanted` the claim tickets. Tools without `wants`
+                    // take the exact path they always took.
+                    let wantedMeta;
+                    let wantsBlocked = false;
+                    if (tool?.wants !== undefined) {
+                        const resolution = await resolveWantsAtDispatch(scope, tc.name, tool.wants, callArgs);
+                        if (resolution.ok) {
+                            callArgs = resolution.args;
+                            wantedMeta = resolution.wanted;
+                        }
+                        else {
+                            wantsBlocked = true;
+                            error = true;
+                            result = resolution.refusal;
+                        }
+                    }
                     // Declare-and-push: resolve the tool's declared credential BEFORE
                     // invoking, and inject it as ctx.credential. On consent-required or
                     // failure, surface the reason to the LLM (tool result) + emit; the
@@ -1332,7 +1615,7 @@ function buildToolCallsHandler(deps) {
                     // throws is surfaced, not retried).
                     let resolvedCredential;
                     let credentialBlocked = false;
-                    const need = tool?.needs;
+                    const need = wantsBlocked ? undefined : tool?.needs;
                     if (need) {
                         (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.credential.requested', {
                             service: need.credential,
@@ -1427,7 +1710,7 @@ function buildToolCallsHandler(deps) {
                             result = `credential error for '${need.credential}': ${reason}`;
                         }
                     }
-                    if (!credentialBlocked) {
+                    if (!credentialBlocked && !wantsBlocked) {
                         try {
                             if (!tool)
                                 throw new Error(`Unknown tool: ${tc.name}`);
@@ -1442,6 +1725,8 @@ function buildToolCallsHandler(deps) {
                                 credentials: reportingCredentials(credentials, scope, tc.name),
                                 hasCredentials,
                                 ...(resolvedCredential && { credential: resolvedCredential }),
+                                ...toolArtifacts(scope, tc.name, tc.id),
+                                ...(wantedMeta !== undefined && { wanted: wantedMeta }),
                                 ...sessionContext(scope, tc.name, tc.id),
                             });
                             // The typed effects channel (9.19.0): a recognized envelope is
@@ -1586,6 +1871,23 @@ function buildToolCallsHandler(deps) {
                 if (deps.stepPlanFor && tc.name === skillSteps_js_1.SKIP_STEP_TOOL_NAME && !error && !denied) {
                     result = applySkipStep(scope, { args: callArgs, toolCallId: tc.id, iteration });
                 }
+                // ── present bookkeeping (9.22.0) ───────────────────────────────
+                // Same mechanism as skip_step: the auto-attached placeholder ran;
+                // the stage overwrites its result with the description snapshot (or
+                // the teaching refusal) BEFORE the after-tool moment, so governance
+                // and the caps compose over what the model will actually read. A
+                // miss is an errored call: the model holds no presentation, and a
+                // procedure step whose tool presented nothing must not advance.
+                if (deps.artifactStore && tc.name === present_js_1.PRESENT_TOOL_NAME && executed && !error && !denied) {
+                    const presented = await applyPresent(scope, {
+                        args: callArgs,
+                        toolCallId: tc.id,
+                        iteration,
+                    });
+                    result = presented.text;
+                    if (!presented.ok)
+                        error = true;
+                }
                 // ── The after-tool moment ────────────────────────────────────────
                 // Last thing before the result becomes history, and only for a call
                 // that ran. `modelResult` is what the model reads; `result` stays the
@@ -1604,10 +1906,19 @@ function buildToolCallsHandler(deps) {
                         ...(env.signal && { signal: env.signal }),
                     })
                     : result;
+                // Placement next (9.22.0) — the operator's ref-ing, judged on what
+                // the chain let through (a rule that already summarized a huge
+                // result is measured on what it produced, the same reasoning as the
+                // cap). Over the threshold, the payload is checked into the store
+                // and BOTH channels carry the ticket; the truncation net below then
+                // measures the ticket. A refused/denied/errored call is never
+                // placed: a refusal is already short, and 'tool-result/<name>' must
+                // never claim an error is the tool's result.
+                const placedValues = await placeResults(scope, { toolName: tc.name, toolCallId: tc.id, iteration }, { result, modelResult: rawModelResult }, executed && !error && !denied && !ceilingRefused);
                 // The ceiling, last — after the tool, after the chain. A rule that
                 // already summarized a huge result is measured on what it produced, so
                 // the cap composes with governance rather than pre-empting it.
-                const capped = capResults(tc.name, { result, modelResult: rawModelResult });
+                const capped = capResults(tc.name, placedValues);
                 const modelResult = capped.modelResult;
                 const durationMs = Date.now() - startMs;
                 (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.stream.tool_end', {
@@ -1929,6 +2240,22 @@ function buildToolCallsHandler(deps) {
                         if (deps.stepPlanFor && toolName === skillSteps_js_1.SKIP_STEP_TOOL_NAME && stepToolRan) {
                             result = applySkipStep(scope, { args: rest.args, toolCallId, iteration });
                         }
+                        // present behind a middleware ask, approved (9.22.0): same
+                        // overwrite the batch loop applies — the snapshot (or refusal)
+                        // replaces the placeholder before the chain's last word. A miss
+                        // is an errored call here too.
+                        if (deps.artifactStore && toolName === present_js_1.PRESENT_TOOL_NAME && stepToolRan) {
+                            const presented = await applyPresent(scope, {
+                                args: rest.args,
+                                toolCallId,
+                                iteration,
+                            });
+                            result = presented.text;
+                            if (!presented.ok) {
+                                error = true;
+                                stepToolRan = false;
+                            }
+                        }
                         // The tool ran on this side of the pause, so the chain gets its
                         // last word here too — a rule about results cannot be skipped by
                         // routing a call through a human.
@@ -1952,7 +2279,11 @@ function buildToolCallsHandler(deps) {
                 // else the two are the same value.
                 if (modelResult === undefined)
                     modelResult = result;
-                const askCapped = capResults(toolName, { result, modelResult });
+                // Placement then the truncation net — the batch loop's precedence,
+                // kept on this door (a resumed result is as placeable as an inline
+                // one; `stepToolRan` is exactly "ran clean").
+                const askPlaced = await placeResults(scope, { toolName, toolCallId, iteration }, { result, modelResult }, stepToolRan);
+                const askCapped = capResults(toolName, askPlaced);
                 modelResult = askCapped.modelResult;
                 let askResultStr = typeof modelResult === 'string' ? modelResult : (0, validators_js_1.safeStringify)(modelResult);
                 // Step boundary (9.18.0) — a result finalized HERE is as final as one
@@ -2073,7 +2404,9 @@ function buildToolCallsHandler(deps) {
                 }
                 if (modelResult === undefined)
                     modelResult = result;
-                const decisionCapped = capResults(toolName, { result, modelResult });
+                // Placement then the truncation net — the batch loop's precedence.
+                const decisionPlaced = await placeResults(scope, { toolName, toolCallId, iteration }, { result, modelResult }, stepToolRan);
+                const decisionCapped = capResults(toolName, decisionPlaced);
                 modelResult = decisionCapped.modelResult;
                 let decisionResultStr = typeof modelResult === 'string' ? modelResult : (0, validators_js_1.safeStringify)(modelResult);
                 // Step boundary (9.18.0) — an approved consequential step (a checkIn
@@ -2165,7 +2498,9 @@ function buildToolCallsHandler(deps) {
                 }
                 if (modelResult === undefined)
                     modelResult = result;
-                const consentCapped = capResults(toolName, { result, modelResult });
+                // Placement then the truncation net — the batch loop's precedence.
+                const consentPlaced = await placeResults(scope, { toolName, toolCallId, iteration }, { result, modelResult }, dispatched.executed === true && error !== true && dispatched.ceilingRefused !== true);
+                const consentCapped = capResults(toolName, consentPlaced);
                 modelResult = consentCapped.modelResult;
                 let consentResultStr = typeof modelResult === 'string' ? modelResult : (0, validators_js_1.safeStringify)(modelResult);
                 // Step boundary (9.18.0) — a step tool that waited on 3LO consent
@@ -2269,8 +2604,12 @@ function buildToolCallsHandler(deps) {
             });
             // A person's answer is measured too. The cap is about what one turn can
             // afford to carry, and a pasted transcript costs a window exactly as much
-            // as a tool's rows do.
-            const pauseCapped = capResults(toolName, { result: input, modelResult: rawPauseResult });
+            // as a tool's rows do — which is also why PLACEMENT judges it: the
+            // handler's contract makes the answer the tool's result, so a pasted
+            // 500KB transcript is checked in as `tool-result/<tool>` and the model
+            // routes the ticket.
+            const pausePlaced = await placeResults(scope, { toolName, toolCallId, iteration }, { result: input, modelResult: rawPauseResult }, true);
+            const pauseCapped = capResults(toolName, pausePlaced);
             const modelResult = pauseCapped.modelResult;
             let resultStr = typeof modelResult === 'string' ? modelResult : (0, validators_js_1.safeStringify)(modelResult);
             // Step boundary (9.18.0) — THE HITL step ("ask a human, then export"):