@nathapp/nax-agent 0.1.0

package/dist/tools/runtime.js

@@ -0,0 +1,345 @@
+/**
+ * Pairs the compiled policy with the tool registry and answers one call.
+ *
+ * nax-permission-mode-allow: consumes grants resolved by resolvePermissions;
+ * makes no permission decision of its own.
+ *
+ * The three outcomes are kept structurally distinct. Reusing one channel for a
+ * refusal and a crash would make a denied permission look like a recoverable
+ * tool error, which ADR-029 section 5 forbids.
+ */
+import { randomUUID } from "node:crypto";
+import { getSafeLogger } from "#src/infra/index";
+import { headlessAskResolver } from "#src/permissions/index";
+import { deleteTool } from "./delete.js";
+import { editTool } from "./edit.js";
+import { gitTool } from "./git.js";
+import { gitCommitTool } from "./git-commit.js";
+import { globTool } from "./glob.js";
+import { grepTool } from "./grep.js";
+import { readTool } from "./read.js";
+import { getCodingTool, registerBuiltinTool } from "./registry.js";
+import { requestCapabilityTool } from "./request-capability.js";
+import { openCallShadowTap, resolveAskOutcome, resolveDenialOutcome, resolveGuardDenial, resolvePolicyIdentity, } from "./runtime-calltool.js";
+import { scratchpadListTool, scratchpadReadTool, scratchpadWriteTool } from "./scratchpad.js";
+import { applyModelTruncationPolicy } from "./spill.js";
+import { createNoOpToolAuditSink } from "./tool-audit.js";
+import { READ_CEILING } from "./truncate.js";
+import { writeTool } from "./write.js";
+/** Per-call output ceiling, mirroring ToolDescriptor.maxTokensPerCall in spirit. */
+export const DEFAULT_TOOL_MAX_BYTES = 40_000;
+/**
+ * Largest file a tool will read whole or write at all.
+ *
+ * Distinct from DEFAULT_TOOL_MAX_BYTES because they answer different questions:
+ * that one is how much the model may be told, this one is how much file a tool
+ * will handle. Edit must read and rewrite a file entirely, so it cannot use the
+ * output ceiling without refusing ordinary source files.
+ *
+ * Generous on purpose. Nothing an LLM legitimately edits approaches it, and a
+ * limit that fires during normal work would be worked around rather than
+ * respected.
+ */
+export const DEFAULT_TOOL_MAX_FILE_BYTES = 2_000_000;
+/** Injectable logger seam, mirroring _pullToolsDeps.getLogger. */
+export const _codingToolDeps = { getLogger: getSafeLogger };
+let builtinsRegistered = false;
+/** Idempotent: the registry is process-global, the runtime is per-session. */
+export function registerBuiltinCodingTools() {
+    if (builtinsRegistered)
+        return;
+    for (const tool of [
+        readTool,
+        globTool,
+        grepTool,
+        writeTool,
+        editTool,
+        deleteTool,
+        gitTool,
+        gitCommitTool,
+        requestCapabilityTool,
+        scratchpadWriteTool,
+        scratchpadReadTool,
+        scratchpadListTool,
+    ]) {
+        if (getCodingTool(tool.name) === undefined)
+            registerBuiltinTool(tool);
+    }
+    builtinsRegistered = true;
+}
+/** @internal Test-only: pairs with _resetRegistryForTest. */
+export function _resetBuiltinsForTest() {
+    builtinsRegistered = false;
+}
+/**
+ * The run-scoped ports every ToolRunContext carries, present-field only.
+ * Built once per runtime and kept out of `runTool`, which sits at its
+ * complexity baseline.
+ */
+function contextPorts(opts) {
+    return {
+        ...(opts.interceptor !== undefined ? { interceptor: opts.interceptor } : {}),
+        ...(opts.protectedPaths !== undefined ? { protectedPaths: opts.protectedPaths } : {}),
+    };
+}
+export function createCodingToolRuntime(opts) {
+    registerBuiltinCodingTools();
+    // The global registry cannot hold session-local tools like RunCommand (its
+    // declared commands are per-project). Consult this layer before the registry.
+    const extra = new Map((opts.extraTools ?? []).map((t) => [t.name, t]));
+    const lookup = (name) => extra.get(name) ?? getCodingTool(name);
+    const sink = opts.sink ?? createNoOpToolAuditSink();
+    const ports = contextPorts(opts);
+    const maxBytes = opts.maxBytes ?? DEFAULT_TOOL_MAX_BYTES;
+    const maxFileBytes = opts.maxFileBytes ?? DEFAULT_TOOL_MAX_FILE_BYTES;
+    const readCeiling = opts.readCeiling ?? READ_CEILING;
+    const askResolver = opts.askResolver ?? headlessAskResolver();
+    const granted = new Set(opts.policy.grantedTools());
+    // Captured so the `ToolRunContext` constructed inside `runTool` carries the
+    // session-wide abort signal; tools (Bash, Exec's argv branch) forward it
+    // into their launcher / runArgv call so turn cancellation reaches the
+    // process group. US-001.
+    const signal = opts.signal;
+    // What `advertised()` actually returned, so a denial can name only tools the
+    // session really received. Recomputing from `granted` would be wrong: an op
+    // narrows the set by declaring fewer tools than it was granted.
+    let advertisedNames = new Set();
+    /**
+     * One line per call, mirroring the pull-tool subsystem's `invoked` record.
+     *
+     * Every outcome is logged, denials included: a refused call that leaves no
+     * trace is indistinguishable from a call never made, and telling those two
+     * apart is the whole reason this exists.
+     *
+     * The logger keeps its calls for operator visibility. The audit sink is the
+     * durable copy a later decision reads from; the two are not interchangeable.
+     */
+    function log(tool, outcome, resultBytes, input, context, breach, reason, routineErrors, audit, resultBytesPreTruncation) {
+        // The level is the console filter: `normal` mode drops debug, and the file
+        // sink writes every level regardless, so demoting keeps the record without
+        // spending an operator's attention on it. A breach is the one outcome that
+        // can indicate prompt injection, so it alone reaches `error`.
+        const level = outcome === "denied" || outcome === "denied:ask"
+            ? breach === true
+                ? "error"
+                : "warn"
+            : outcome === "error" && !routineErrors
+                ? "warn"
+                : "debug";
+        // Never parse the namespaced name apart — the provider id is carried
+        // explicitly precisely so a naming-convention change cannot break
+        // telemetry silently. `tool` is the identity the ledger records: the
+        // namespaced name for a provider tool, `Exec` for the argv branch (which
+        // is not provider-supplied, so the lookup misses and the field is absent).
+        const provider = opts.providerIdByTool?.get(tool);
+        // `reason` rides under the `error` key because the formatter's
+        // readFailureReason() renders exactly that key on warn/error lines. The
+        // message names the tool so the line is legible without the JSONL: these
+        // used to print as a bare "coding-tool invoked" with neither.
+        _codingToolDeps.getLogger()?.[level]("coding-tool", `${tool} ${outcome}`, {
+            storyId: opts.storyId,
+            tool,
+            outcome,
+            resultBytes,
+            ...(reason !== undefined && reason.length > 0 ? { error: reason } : {}),
+        });
+        sink.record({
+            tool,
+            outcome,
+            breach,
+            input,
+            resultBytes,
+            storyId: opts.storyId,
+            at: new Date().toISOString(),
+            ...(reason !== undefined && reason.length > 0 ? { reason } : {}),
+            ...(audit?.executed !== undefined ? { executed: audit.executed } : {}),
+            ...(audit?.target !== undefined ? { target: audit.target } : {}),
+            ...(audit?.approval !== undefined ? { approval: audit.approval } : {}),
+            ...(audit?.sandbox !== undefined ? { sandbox: audit.sandbox } : {}),
+            ...(audit?.exitCode !== undefined ? { exitCode: audit.exitCode } : {}),
+            ...(provider !== undefined ? { provider } : {}),
+            ...(resultBytesPreTruncation !== undefined ? { resultBytesPreTruncation } : {}),
+            ...(opts.callId !== undefined ? { callId: opts.callId } : {}),
+            ...(opts.scopeId !== undefined ? { scopeId: opts.scopeId } : {}),
+            ...(context?.turnId !== undefined ? { turnId: context.turnId } : {}),
+            ...(context?.roundTrips !== undefined ? { roundTrips: context.roundTrips } : {}),
+            ...(context?.toolCallId !== undefined ? { toolCallId: context.toolCallId } : {}),
+        });
+    }
+    async function shapeToolResult(body, toolName, context) {
+        if (context?.deferModelTruncation === true)
+            return body;
+        return applyModelTruncationPolicy(body, {
+            toolName,
+            callId: context?.toolCallId ?? randomUUID(),
+            root: opts.policy.root,
+            maxBytes,
+        });
+    }
+    return {
+        advertised(declared) {
+            const out = [];
+            for (const name of declared) {
+                if (!granted.has(name))
+                    continue;
+                const tool = lookup(name);
+                if (tool !== undefined)
+                    out.push(tool);
+            }
+            advertisedNames = new Set(out.map((t) => t.name));
+            return out;
+        },
+        async callTool(name, input, context) {
+            const tool = lookup(name);
+            if (tool === undefined) {
+                const reason = `unknown tool "${name}"`;
+                log(name, "denied", 0, input, context, false, reason);
+                return { kind: "denied", reason, breach: false };
+            }
+            const { policyIdentity, argvField, hasArgv } = resolvePolicyIdentity(name, tool, input);
+            const verdict = opts.policy.check(policyIdentity, tool.scope, input);
+            // P5: observe the command now (not awaited), settle from logCall below.
+            const tap = openCallShadowTap({
+                shadow: opts.commandShadow,
+                identity: policyIdentity,
+                tool,
+                input,
+                hasArgv,
+                argvField,
+                root: opts.policy.root,
+                stage: opts.pipelineStage,
+                storyId: opts.storyId,
+                callId: opts.callId,
+                scopeId: opts.scopeId,
+                context,
+                verdict,
+            });
+            // Every ledger outcome of this call settles the tap exactly once, with
+            // `denied:ask` and `decidedBy` intact -- which CodingToolOutcome.kind
+            // alone would lose (spec 4.2). The audit is a named parameter, not a
+            // rest-array index: `log`'s positional shape can then change without
+            // silently shifting what the tap settles with.
+            const logCall = (tool, outcome, resultBytes, input, context, breach, reason, routineErrors, audit, resultBytesPreTruncation) => {
+                log(tool, outcome, resultBytes, input, context, breach, reason, routineErrors, audit, resultBytesPreTruncation);
+                tap?.settle(outcome, audit?.approval?.decidedBy, audit?.executed === undefined
+                    ? undefined
+                    : { executed: audit.executed, ...(audit.cwd !== undefined ? { cwd: audit.cwd } : {}) });
+            };
+            /**
+             * Executes a permitted call and records its outcome. Shared by the
+             * ordinary allow path and an ask verdict an AskResolver approved, so an
+             * approved call behaves exactly as a grant would have.
+             *
+             * The result is shaped by `applyModelTruncationPolicy` before it is
+             * returned, which is what makes the model-facing cap one policy rather
+             * than one per tool: the tools bound their own I/O at `ctx.readCeiling`,
+             * and this is where the byte/line ceilings the model experiences — and
+             * the spill of whatever they cut — are applied. The native session
+             * applies the same policy at its `after_tool` chokepoint, so a call made
+             * through the loop and one made directly see the same shaping.
+             */
+            async function runTool(target, callInput, resolvedPaths, approval) {
+                // US-002 AC15: a per-call `ToolCallContext.signal` (the native batch's
+                // turn signal) takes priority over the runtime-level signal. Both
+                // describe "abort this in-flight tool"; the per-call one is the one
+                // the batch explicitly put in scope, so it wins when both are
+                // present, falling back to the runtime-level signal otherwise so the
+                // session-wide abort keeps working when no per-call signal is in
+                // scope.
+                const callSignal = context?.signal ?? signal;
+                try {
+                    const result = await target.run(callInput, {
+                        root: opts.policy.root,
+                        resolvedPaths,
+                        maxBytes,
+                        maxFileBytes,
+                        readCeiling,
+                        ...(opts.denyPaths !== undefined ? { denyPaths: opts.denyPaths } : {}),
+                        ...ports,
+                        ...(callSignal !== undefined ? { signal: callSignal } : {}),
+                    });
+                    const kind = result.isError === true ? "error" : "ok";
+                    const content = await shapeToolResult(result.content, policyIdentity, context);
+                    const record = (finalContent) => logCall(policyIdentity, kind, finalContent.length, callInput, context, false, kind === "error" ? result.content : undefined, target.routineErrors, { ...result.audit, ...(approval ? { approval } : {}) }, result.resultBytesPreTruncation);
+                    if (context?.deferModelTruncation === true)
+                        return { kind, content, finalizeAudit: record };
+                    record(content);
+                    return { kind, content };
+                }
+                catch (err) {
+                    const rawContent = err instanceof Error ? err.message : String(err);
+                    const content = await shapeToolResult(rawContent, policyIdentity, context);
+                    const record = (finalContent) => logCall(policyIdentity, "error", finalContent.length, callInput, context, false, rawContent, target.routineErrors, approval ? { approval } : undefined);
+                    if (context?.deferModelTruncation === true) {
+                        return { kind: "error", content, finalizeAudit: record };
+                    }
+                    record(content);
+                    return { kind: "error", content };
+                }
+            }
+            if (!verdict.allowed && verdict.outcome === "ask") {
+                return resolveAskOutcome({
+                    identity: policyIdentity,
+                    tool,
+                    input,
+                    context,
+                    verdict,
+                    runtimeSignal: signal,
+                    askResolver,
+                    stage: opts.pipelineStage,
+                    storyId: opts.storyId,
+                    root: opts.policy.root,
+                    logCall,
+                    runTool,
+                });
+            }
+            if (!verdict.allowed) {
+                return resolveDenialOutcome({
+                    name,
+                    identity: policyIdentity,
+                    tool,
+                    input,
+                    context,
+                    verdict,
+                    argvField,
+                    advertisedNames,
+                    declaredCommands: opts.declaredCommands,
+                    root: opts.policy.root,
+                    logCall,
+                });
+            }
+            // US-004: an ALLOWED `Bash`/`Exec` call the configured guard flags is
+            // routed through the existing ask channel; every other call (no guard,
+            // unflagged, any other identity) runs exactly as before. The tap above
+            // was opened BEFORE this await, so the shadow's observation starts the
+            // shared classification the guard then reuses.
+            const guardDenial = await resolveGuardDenial({
+                identity: policyIdentity,
+                tool,
+                input,
+                argvField,
+                guard: opts.commandShadow?.guard,
+                root: opts.policy.root,
+                tempConfined: opts.tempConfined ?? false,
+                resolvedPaths: verdict.resolvedPaths,
+            });
+            if (guardDenial !== undefined) {
+                return resolveAskOutcome({
+                    identity: policyIdentity,
+                    tool,
+                    input,
+                    context,
+                    verdict: guardDenial,
+                    runtimeSignal: signal,
+                    askResolver,
+                    stage: opts.pipelineStage,
+                    storyId: opts.storyId,
+                    root: opts.policy.root,
+                    logCall,
+                    runTool,
+                });
+            }
+            return runTool(tool, input, verdict.resolvedPaths);
+        },
+    };
+}

package/dist/tools/scratchpad.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Confined write/read/list tools for an agent-owned throwaway directory.
+ *
+ * Three small tools (ScratchpadWrite / ScratchpadRead / ScratchpadList) that
+ * let a session keep notes, command output and intermediate lists between
+ * calls without ever writing anything the policy could later attribute to
+ * the run. Containment is the load-bearing seam: every tool declares
+ * `scope.confineTo = SCRATCHPAD_DIR`, so the policy runs `resolveWithin`
+ * against `<root>/<confineTo>` instead of the repository root. A `..`
+ * traversal leaves the confined directory, returns null from `resolveWithin`,
+ * and the policy reports `breach: true` (US-001). The tools themselves never
+ * resolve a path -- they consume `ctx.resolvedPaths[0]` only, so the policy
+ * stays the single seam.
+ */
+import type { CodingTool } from "./registry.ts";
+/** The canonical scratchpad path, written into the policy as `scope.confineTo`. */
+export declare const SCRATCHPAD_DIR = ".nax/scratchpad";
+export declare const scratchpadWriteTool: CodingTool;
+export declare const scratchpadReadTool: CodingTool;
+export declare const scratchpadListTool: CodingTool;

package/dist/tools/scratchpad.js

@@ -0,0 +1,197 @@
+/**
+ * Confined write/read/list tools for an agent-owned throwaway directory.
+ *
+ * Three small tools (ScratchpadWrite / ScratchpadRead / ScratchpadList) that
+ * let a session keep notes, command output and intermediate lists between
+ * calls without ever writing anything the policy could later attribute to
+ * the run. Containment is the load-bearing seam: every tool declares
+ * `scope.confineTo = SCRATCHPAD_DIR`, so the policy runs `resolveWithin`
+ * against `<root>/<confineTo>` instead of the repository root. A `..`
+ * traversal leaves the confined directory, returns null from `resolveWithin`,
+ * and the policy reports `breach: true` (US-001). The tools themselves never
+ * resolve a path -- they consume `ctx.resolvedPaths[0]` only, so the policy
+ * stays the single seam.
+ */
+import { existsSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join, sep } from "node:path";
+import { fileSizeOrZero } from "#src/internal/file-size";
+import { getAgentRuntime } from "#src/runtime/index";
+import { resolveWithin } from "./policy.js";
+import { readFileSlice } from "./read-file.js";
+import { READ_CEILING } from "./truncate.js";
+/** The canonical scratchpad path, written into the policy as `scope.confineTo`. */
+export const SCRATCHPAD_DIR = ".nax/scratchpad";
+/**
+ * Match cap for ScratchpadList. Mirrors `glob.ts`'s `MAX_MATCHES` -- a
+ * long-running session accumulates throwaway files by design, so an
+ * unbounded scan would feed an arbitrarily large listing back into model
+ * context, bypassing the model-facing ceiling the after_tool policy
+ * applies to every other content-returning tool.
+ */
+const MAX_MATCHES = 500;
+export const scratchpadWriteTool = {
+    name: "ScratchpadWrite",
+    description: "Write a throwaway file to your scratchpad at .nax/scratchpad/. Use it for notes to yourself, command output you want to re-read, intermediate lists, or a probe script to run against the project's code. It is never committed and is wiped when a run finishes (a failed run's scratchpad is retained for inspection until the next run starts and clears it). Paths are relative to the scratchpad and cannot reach the repository.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "Path relative to the scratchpad directory" },
+            content: { type: "string", description: "Full file contents to write" },
+        },
+        required: ["path", "content"],
+    },
+    scope: { pathFields: ["path"], confineTo: SCRATCHPAD_DIR },
+    async run(input, ctx) {
+        const [target] = ctx.resolvedPaths;
+        if (target === undefined)
+            return { content: "no path supplied", isError: true };
+        const content = input.content;
+        if (typeof content !== "string")
+            return { content: "content must be a string", isError: true };
+        // Check the ceiling BEFORE any directory or file creation, so a refused
+        // write leaves no empty file at the target. This is the load-bearing
+        // property the AC11 boundary pins.
+        const size = Buffer.byteLength(content, "utf8");
+        if (size > ctx.maxFileBytes) {
+            return {
+                content: `content is ${size} bytes, which exceeds the ${ctx.maxFileBytes}-byte file ceiling`,
+                isError: true,
+            };
+        }
+        try {
+            await mkdir(dirname(target), { recursive: true });
+            await writeFile(target, content, "utf8");
+            return { content: `wrote ${size} bytes` };
+        }
+        catch (err) {
+            return { content: err instanceof Error ? err.message : String(err), isError: true };
+        }
+    },
+};
+export const scratchpadReadTool = {
+    name: "ScratchpadRead",
+    description: "Read a throwaway file from your scratchpad at .nax/scratchpad/. Paths are relative to the scratchpad. Use it to re-read notes, command output and intermediate lists you wrote with ScratchpadWrite -- including the output a truncated tool result spilled there. Optionally pass offset (1-based line number to start from) and/or limit (maximum number of lines to return) to page through a body too large to read at once.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "Path relative to the scratchpad directory" },
+            offset: { type: "integer", minimum: 1, description: "1-based line number to start reading from" },
+            limit: { type: "integer", minimum: 1, description: "Maximum number of lines to return" },
+        },
+        required: ["path"],
+    },
+    scope: { pathFields: ["path"], confineTo: SCRATCHPAD_DIR },
+    async run(input, ctx) {
+        const [target] = ctx.resolvedPaths;
+        if (target === undefined)
+            return { content: "no path supplied", isError: true };
+        const requestedPath = typeof input.path === "string" ? input.path : "<path>";
+        const rawOffset = input.offset;
+        if (rawOffset !== undefined && typeof rawOffset !== "number") {
+            return { content: "offset must be an integer", isError: true };
+        }
+        const rawLimit = input.limit;
+        if (rawLimit !== undefined && typeof rawLimit !== "number") {
+            return { content: "limit must be an integer", isError: true };
+        }
+        const offset = rawOffset;
+        const limit = rawLimit;
+        try {
+            // The tool bounds its own I/O at `readCeiling`, NOT at `maxBytes`: the
+            // model-facing cap belongs to the session's after_tool policy, which
+            // also owns the spill of whatever it cuts. Reading up to the ceiling is
+            // what lets a body in (maxBytes, readCeiling) reach that policy whole.
+            //
+            // `resultBytesPreTruncation` reports the file's FULL byte length, before
+            // any of this, so the ledger can answer "how much did we discard" for a
+            // result that was shaped after it left here.
+            const slice = await readFileSlice(target, {
+                readCeiling: ctx.readCeiling ?? READ_CEILING,
+                ...(offset !== undefined ? { offset } : {}),
+                ...(limit !== undefined ? { limit } : {}),
+            });
+            const fullBytes = fileSizeOrZero(target);
+            const { content, bounded, totalLines } = slice;
+            // The header leads EVERY read that returns file content, the paged one
+            // included: it reports the FILE's line count, which is what a model
+            // paging a spilled body needs in order to know how many pages remain —
+            // the page it asked for is not a substitute for that number. Precedent
+            // from readTool's whole-file read, marked with `+` when the read stopped
+            // at the I/O ceiling and the count is therefore a floor rather than the
+            // file's true total.
+            const header = `[${bounded ? `${totalLines}+` : `${totalLines}`} lines]`;
+            if (offset !== undefined || limit !== undefined) {
+                // An offset past the last line is answered with the line count rather
+                // than an empty result, because "there is nothing here" is
+                // indistinguishable from "the file is empty" and the model can act on
+                // the number -- and there the count IS the message, so no header leads
+                // it. The condition is the OFFSET against the file, never the emptiness
+                // of the slice: a range that selects only blank lines is a perfectly
+                // valid page, and reporting it as past-the-end would hide content the
+                // caller asked for and that the file really holds.
+                if (offset !== undefined && offset > totalLines) {
+                    const pastEnd = `offset ${String(offset)} is past the end of the file -- it has ${totalLines} lines`;
+                    return { content: pastEnd, resultBytesPreTruncation: fullBytes };
+                }
+                // The header goes on its own line and the requested range follows it,
+                // verbatim -- possibly empty, when the page holds blank lines.
+                // readTool's ranged read composes it the same way.
+                return { content: `${header}\n${content}`, resultBytesPreTruncation: fullBytes };
+            }
+            return { content: content === "" ? header : `${header}\n${content}`, resultBytesPreTruncation: fullBytes };
+        }
+        catch (err) {
+            // A missing file is a tool ERROR the model can react to, never a
+            // denial -- the policy already said yes. Naming the requested path is
+            // what AC7 pins: the model should see what it asked for, not "ENOENT".
+            const message = err instanceof Error ? err.message : String(err);
+            return { content: `cannot read "${requestedPath}": ${message}`, isError: true };
+        }
+    },
+};
+export const scratchpadListTool = {
+    name: "ScratchpadList",
+    description: "List files in your scratchpad at .nax/scratchpad/. Returns paths relative to the scratchpad. Reports no entries when the scratchpad is empty or has not been written to this run.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+    },
+    // No path field: there is nothing for the policy to gate per call. The
+    // directory the tool reads is the confined directory, declared at registration.
+    scope: { pathFields: [], confineTo: SCRATCHPAD_DIR },
+    async run(_input, ctx) {
+        const scratchpad = join(ctx.root, SCRATCHPAD_DIR);
+        // A missing scratchpad is not an error -- a model that has not written
+        // anything yet (or one whose prior writes have been wiped at run start)
+        // should see a clean empty listing, not an ENOENT to recover from.
+        if (!existsSync(scratchpad))
+            return { content: "(no entries)" };
+        const entries = getAgentRuntime().globSync("**/*", { cwd: scratchpad, absolute: false });
+        // Mirror glob.ts: every match is re-checked through resolveWithin before
+        // it is emitted, so a directory symlink planted inside the scratchpad
+        // cannot leak external paths the policy never saw. resolveWithin runs
+        // the symlink through isInside(realOrRaw(...)), so a symlink to outside
+        // the policy root yields null and the entry is skipped.
+        //
+        // Sort first, then cap. Capping first would leak the scan's enumeration
+        // order into the model, which is not what any caller expects from a
+        // listing -- a deterministic alphabetical prefix is the useful signal
+        // when a scratchpad has grown past the cap. The caller materializes the
+        // full list before we see it, so the sort/cap are bounded by what the
+        // scan produced, not by anything the tool itself decided to walk.
+        const sorted = [...entries].sort();
+        const files = [];
+        for (const hit of sorted) {
+            if (files.length >= MAX_MATCHES)
+                break;
+            if (resolveWithin(ctx.root, hit) === null)
+                continue;
+            files.push(hit.split(sep).join("/"));
+        }
+        if (files.length === 0)
+            return { content: "(no entries)" };
+        const rendered = files.join("\n");
+        return { content: rendered };
+    },
+};

package/dist/tools/spill.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Spill writer and the model-facing composition of the truncation policy
+ * (US-003).
+ *
+ * The policy itself (`truncateForModel`) decides *what* the model may see; this
+ * module decides what happens to the rest. On truncation only, the untruncated
+ * body — up to `READ_CEILING` — is written under the scratchpad at
+ * `spill/<toolName>-<callId>.txt`, and the marker naming that path and both byte
+ * counts is appended to the content the model receives. `writeSpill` keeps
+ * returning the scratchpad-relative spelling; `applyModelTruncationPolicy`
+ * turns it into the path the marker names — root-relative
+ * (`.nax/scratchpad/spill/...`) by default, so the session's own tools and
+ * shell can open it verbatim, or absolute when the root is not the session's
+ * shell root. The spilled body stays recoverable with `offset`/`limit`.
+ *
+ * The composition lives here, beside the writer, because the marker and the
+ * spill are one decision: the path may only appear in the marker when the write
+ * actually succeeded. Both transports reach it — the coding-tool runtime applies
+ * it to every genuine tool result, and the native session applies it at the
+ * `after_tool` chokepoint — so there is exactly one implementation of the
+ * model-facing cap rather than one per tool.
+ *
+ * Filesystem calls are injectable (`_spillDeps`), following `_scratchpadWipeDeps`
+ * in src/execution/lifecycle/scratchpad-wipe.ts, and writes go through
+ * asynchronous Node filesystem APIs.
+ */
+/** Directory under the scratchpad that holds spilled tool output. */
+export declare const SPILL_DIR = "spill";
+/** Injectable filesystem seam (see docs/architecture/conventions.md §2). */
+export declare const _spillDeps: {
+    mkdir: (path: string) => Promise<string | undefined>;
+    writeFile: (path: string, data: string) => Promise<number>;
+};
+export interface SpillRequest {
+    /** Absolute root holding `.nax/scratchpad/` — the same root the tools are confined to. */
+    readonly root: string;
+    readonly toolName: string;
+    readonly callId: string;
+    /** The untruncated body, exactly as the tool returned it. */
+    readonly body: string;
+}
+/** `spill/<toolName>-<callId>.txt`, relative to the scratchpad directory. */
+export declare function spillRelativePath(toolName: string, callId: string): string;
+/**
+ * Write the untruncated body under the scratchpad and return its path relative
+ * to the scratchpad, or `undefined` when the write failed.
+ *
+ * Failure is fail-open by contract: the caller still delivers the truncated
+ * result. What it must not do is name a file that is not there, which is why
+ * this returns the path rather than a boolean.
+ */
+export declare function writeSpill(req: SpillRequest): Promise<string | undefined>;
+export interface ModelTruncationOptions {
+    readonly toolName: string;
+    /** Identifies the spill file; the model's own tool-call id when it has one. */
+    readonly callId: string;
+    /** Absolute root to spill under. Omitted means no spill, and no path in the marker. */
+    readonly root?: string;
+    /** Model-facing byte ceiling. Defaults to `MODEL_MAX_BYTES`. */
+    readonly maxBytes?: number;
+    /**
+     * How the marker spells the spill path. `"root-relative"` (the default)
+     * names it from the directory the session's tools and shell start in
+     * (`.nax/scratchpad/spill/...`), so the model can open it verbatim;
+     * `"absolute"` names the written file's absolute path, for a caller whose
+     * root is not that directory (the native transcript fallback).
+     */
+    readonly spillPathStyle?: "root-relative" | "absolute";
+}
+/**
+ * Apply the model-facing truncation policy to one tool result.
+ *
+ * Returns the body unchanged when it is within every cap — no spill, no marker.
+ * Otherwise the shared policy shapes the content, the untruncated body is
+ * spilled when a root is known, and the marker naming both byte counts and the
+ * spill path is composed inside the same ceilings the body obeys.
+ *
+ * The byte ceiling is the caller's `maxBytes`, defaulting to `MODEL_MAX_BYTES`;
+ * the line ceilings always come from the shared policy's constants.
+ */
+export declare function applyModelTruncationPolicy(body: string, opts: ModelTruncationOptions): Promise<string>;