@nathapp/nax-agent 0.1.0

package/dist/tools/truncate.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Shared model-facing truncation policy — US-001.
+ *
+ * The single byte-safe implementation that `after_tool` will apply, replacing
+ * the per-tool `truncate(body, ctx.maxBytes)` helpers. Constants, direction
+ * lookup, and the core algorithm all live here so a future regression that
+ * resuscitates a per-tool slicer sits behind one import rather than 5+.
+ *
+ * Three independent caps compose as an ORDERED PIPELINE, never as alternatives:
+ *   1. Per-line cap: every line longer than MODEL_MAX_LINE_CHARS (UTF-16
+ *      code units) is shortened.
+ *   2. Line-count cap: if still over MODEL_MAX_LINES lines, direction selects
+ *      which lines to keep — over the WHOLE body, not over a byte window of it.
+ *   3. Byte cap LAST: if the result still exceeds MODEL_MAX_BYTES, cut on a
+ *      codepoint boundary. Running it last is what makes the byte ceiling
+ *      unconditional — nothing is appended or prepended after the cut. Under
+ *      `tail-with-first-line` the first line is retained INSIDE that budget,
+ *      with the trailing slice taken against what remains after the first line
+ *      and its newline; if the first line alone does not fit, it is itself cut.
+ *
+ * Line counting: a trailing newline TERMINATES the last line rather than
+ * opening an empty one, and an empty body has no lines, matching
+ * `readFileSlice`'s `totalLines` and `readTool`'s `[N lines]` header.
+ */
+/** Tool-layer I/O bound for ranged file reads. */
+export declare const READ_CEILING = 2000000;
+export declare const MODEL_MAX_BYTES = 40000;
+export declare const MODEL_MAX_LINES = 1000;
+export declare const MODEL_MAX_LINE_CHARS = 2000;
+export type TruncationDirection = "head" | "tail-with-first-line";
+/** Result of `truncateForModel`: the rewritten body and whether any stage changed it. */
+export interface TruncationResult {
+    readonly content: string;
+    readonly truncated: boolean;
+    /** Full UTF-8 byte length of the input, regardless of whether anything was truncated. */
+    readonly originalBytes: number;
+}
+/** Options passed to `truncateForModel`. Direction is determined by tool name via `truncationDirectionFor`. */
+export interface TruncateForModelOptions {
+    readonly direction: TruncationDirection;
+}
+/** Look up the truncation direction for a tool by name. */
+export declare function truncationDirectionFor(toolName: string): TruncationDirection;
+/**
+ * Split a body into lines honouring the trailing-newline convention:
+ * "a\nb\n" is two lines, not three. An empty body yields zero lines.
+ *
+ * Exported because the spill-and-marker composition (src/tools/spill.ts) has
+ * to count the same lines this policy counts: a marker line occupies one of
+ * `MODEL_MAX_LINES`, and counting it with a raw `split("\n")` would let the
+ * delivered content exceed the cap by exactly the phantom empty line.
+ */
+export declare function splitModelLines(body: string): string[];
+/**
+ * Shorten a single line so its UTF-16 code-unit length is at most
+ * `maxCodeUnits`. Backs up one code unit if the cut would land on a high
+ * surrogate (the lead of a surrogate pair), so the result never carries
+ * a lone surrogate that would re-encode as U+FFFD in a downstream stage.
+ *
+ * Exported for the same reason `splitModelLines` is: the marker composition
+ * keeps lines that the policy has not yet shaped, and it must shorten them
+ * the one way the policy shortens them.
+ */
+export declare function capModelLine(line: string, maxCodeUnits: number): string;
+/**
+ * Cut `body` to at most `maxBytes` bytes on a clean codepoint boundary.
+ * Nothing is appended after the cut: the byte cap is unconditional.
+ *
+ * The one codepoint-boundary slicer in the tool layer — `readFileSlice`
+ * needs the same guarantee for its own I/O bound, so it shares this rather
+ * than growing a second copy.
+ *
+ * The boundary is found STRUCTURALLY, by walking back over continuation bytes,
+ * not by measuring the decoded candidate's byte length. Measurement is unsound:
+ * a slice that ends mid-codepoint decodes into a U+FFFD, and that replacement
+ * costs 3 bytes — exactly what a truncated 4-byte codepoint contributed when
+ * three of its four bytes were included. The length check then passes while the
+ * output carries a replacement character, which is the outcome the codepoint
+ * boundary exists to prevent. Walking back stops where a codepoint starts, so
+ * the slice is always whole codepoints and re-encodes to exactly `cut` bytes.
+ */
+export declare function cutBufferToByteCap(buffer: Buffer, maxBytes: number): Buffer;
+export declare function cutToByteCap(body: string, maxBytes: number): string;
+/**
+ * Apply the model-facing truncation policy to a tool result body.
+ *
+ * Three stages, in order, each independently reachable: per-line cap,
+ * line-count cap, byte cap. The pipeline reports `truncated: true` when
+ * any stage changed the content. `originalBytes` always reports the
+ * input's full UTF-8 byte length, regardless of which stages fired.
+ *
+ * Direction governs both stages that drop content: the line-count cap keeps
+ * the first N lines (`head`) or the first line plus the last N-1 lines
+ * (`tail-with-first-line`), and the byte cap keeps the leading bytes or the
+ * first line plus the trailing bytes the same way. Within-cap bodies are
+ * returned unchanged regardless of direction.
+ */
+export declare function truncateForModel(body: string, opts: TruncateForModelOptions): TruncationResult;

package/dist/tools/truncate.js

@@ -0,0 +1,297 @@
+/**
+ * Shared model-facing truncation policy — US-001.
+ *
+ * The single byte-safe implementation that `after_tool` will apply, replacing
+ * the per-tool `truncate(body, ctx.maxBytes)` helpers. Constants, direction
+ * lookup, and the core algorithm all live here so a future regression that
+ * resuscitates a per-tool slicer sits behind one import rather than 5+.
+ *
+ * Three independent caps compose as an ORDERED PIPELINE, never as alternatives:
+ *   1. Per-line cap: every line longer than MODEL_MAX_LINE_CHARS (UTF-16
+ *      code units) is shortened.
+ *   2. Line-count cap: if still over MODEL_MAX_LINES lines, direction selects
+ *      which lines to keep — over the WHOLE body, not over a byte window of it.
+ *   3. Byte cap LAST: if the result still exceeds MODEL_MAX_BYTES, cut on a
+ *      codepoint boundary. Running it last is what makes the byte ceiling
+ *      unconditional — nothing is appended or prepended after the cut. Under
+ *      `tail-with-first-line` the first line is retained INSIDE that budget,
+ *      with the trailing slice taken against what remains after the first line
+ *      and its newline; if the first line alone does not fit, it is itself cut.
+ *
+ * Line counting: a trailing newline TERMINATES the last line rather than
+ * opening an empty one, and an empty body has no lines, matching
+ * `readFileSlice`'s `totalLines` and `readTool`'s `[N lines]` header.
+ */
+/** Tool-layer I/O bound for ranged file reads. */
+export const READ_CEILING = 2_000_000;
+export const MODEL_MAX_BYTES = 40_000;
+export const MODEL_MAX_LINES = 1_000;
+export const MODEL_MAX_LINE_CHARS = 2_000;
+/** Tools whose output direction is `tail-with-first-line` — keep the start AND the end. */
+const TAIL_DIRECTION_TOOLS = new Set(["Bash", "RunCommand", "Exec"]);
+/** Look up the truncation direction for a tool by name. */
+export function truncationDirectionFor(toolName) {
+    if (TAIL_DIRECTION_TOOLS.has(toolName))
+        return "tail-with-first-line";
+    return "head";
+}
+/**
+ * Split a body into lines honouring the trailing-newline convention:
+ * "a\nb\n" is two lines, not three. An empty body yields zero lines.
+ *
+ * Exported because the spill-and-marker composition (src/tools/spill.ts) has
+ * to count the same lines this policy counts: a marker line occupies one of
+ * `MODEL_MAX_LINES`, and counting it with a raw `split("\n")` would let the
+ * delivered content exceed the cap by exactly the phantom empty line.
+ */
+export function splitModelLines(body) {
+    if (body === "")
+        return [];
+    const trimmed = body.endsWith("\n") ? body.slice(0, -1) : body;
+    return trimmed.split("\n");
+}
+/**
+ * Shorten a single line so its UTF-16 code-unit length is at most
+ * `maxCodeUnits`. Backs up one code unit if the cut would land on a high
+ * surrogate (the lead of a surrogate pair), so the result never carries
+ * a lone surrogate that would re-encode as U+FFFD in a downstream stage.
+ *
+ * Exported for the same reason `splitModelLines` is: the marker composition
+ * keeps lines that the policy has not yet shaped, and it must shorten them
+ * the one way the policy shortens them.
+ */
+export function capModelLine(line, maxCodeUnits) {
+    if (line.length <= maxCodeUnits)
+        return line;
+    let cut = maxCodeUnits;
+    // Avoid splitting a surrogate pair: if the last code unit kept is a
+    // high surrogate, back up one so the pair stays whole.
+    if (cut > 0) {
+        const last = line.charCodeAt(cut - 1);
+        if (last >= 0xd800 && last <= 0xdbff)
+            cut -= 1;
+    }
+    return line.slice(0, cut);
+}
+/**
+ * Apply the per-line cap (stage 1) to every line, preserving the array
+ * shape so later stages can count and slice by line.
+ */
+function applyLineCharCap(lines, maxLineChars) {
+    let changed = false;
+    const out = [];
+    for (const line of lines) {
+        if (line.length <= maxLineChars) {
+            out.push(line);
+            continue;
+        }
+        changed = true;
+        out.push(capModelLine(line, maxLineChars));
+    }
+    return { lines: out, changed };
+}
+/**
+ * Apply the line-count cap (stage 2) by direction, chosen over the WHOLE
+ * body rather than over a byte window of it. `head` keeps the first N
+ * lines and drops the rest; `tail-with-first-line` keeps the first line
+ * followed by the last N-1 lines, dropping the middle.
+ */
+function applyLineCountCap(lines, maxLines, direction) {
+    if (lines.length <= maxLines)
+        return { lines, changed: false };
+    if (direction === "head") {
+        return { lines: lines.slice(0, maxLines), changed: true };
+    }
+    // tail-with-first-line: first line + last (maxLines - 1) lines.
+    // When maxLines is 0 or 1 the result is just the first line.
+    const tailCount = Math.max(0, maxLines - 1);
+    const tail = lines.slice(-tailCount);
+    const head = lines.slice(0, 1);
+    return { lines: [...head, ...tail], changed: true };
+}
+/**
+ * True when `byte` is a UTF-8 continuation byte (`10xxxxxx`) — meaning the
+ * position it sits at is INSIDE a multi-byte codepoint, not at its start.
+ */
+function isContinuationByte(byte) {
+    return byte !== undefined && (byte & 0xc0) === 0x80;
+}
+function utf8SequenceLength(byte) {
+    if (byte === undefined || byte < 0x80)
+        return 1;
+    if ((byte & 0xe0) === 0xc0)
+        return 2;
+    if ((byte & 0xf0) === 0xe0)
+        return 3;
+    if ((byte & 0xf8) === 0xf0)
+        return 4;
+    return 1;
+}
+/**
+ * Cut `body` to at most `maxBytes` bytes on a clean codepoint boundary.
+ * Nothing is appended after the cut: the byte cap is unconditional.
+ *
+ * The one codepoint-boundary slicer in the tool layer — `readFileSlice`
+ * needs the same guarantee for its own I/O bound, so it shares this rather
+ * than growing a second copy.
+ *
+ * The boundary is found STRUCTURALLY, by walking back over continuation bytes,
+ * not by measuring the decoded candidate's byte length. Measurement is unsound:
+ * a slice that ends mid-codepoint decodes into a U+FFFD, and that replacement
+ * costs 3 bytes — exactly what a truncated 4-byte codepoint contributed when
+ * three of its four bytes were included. The length check then passes while the
+ * output carries a replacement character, which is the outcome the codepoint
+ * boundary exists to prevent. Walking back stops where a codepoint starts, so
+ * the slice is always whole codepoints and re-encodes to exactly `cut` bytes.
+ */
+export function cutBufferToByteCap(buffer, maxBytes) {
+    let cut = Math.min(buffer.length, maxBytes);
+    while (cut > 0 && isContinuationByte(buffer[cut]))
+        cut -= 1;
+    let sequenceStart = cut - 1;
+    while (sequenceStart >= 0 && isContinuationByte(buffer[sequenceStart]))
+        sequenceStart -= 1;
+    if (sequenceStart >= 0 && sequenceStart + utf8SequenceLength(buffer[sequenceStart]) > cut) {
+        cut = sequenceStart;
+    }
+    return buffer.subarray(0, cut);
+}
+export function cutToByteCap(body, maxBytes) {
+    const buffer = Buffer.from(body, "utf8");
+    return cutBufferToByteCap(buffer, maxBytes).toString("utf8");
+}
+/**
+ * Cut `body` down to its LAST `maxBytes` bytes, on a clean codepoint boundary.
+ * The mirror of `cutToByteCap`: that one backs up over the continuation bytes a
+ * cut-inside-a-codepoint would end on, this one skips forward over the
+ * continuation bytes such a start would begin on. Same structural rule, same
+ * reason — measuring the decoded candidate would accept a tail that opens with
+ * a U+FFFD whenever the replacement costs no more bytes than the partial
+ * codepoint it replaced.
+ */
+function tailWithinBytes(body, maxBytes) {
+    const buf = Buffer.from(body, "utf8");
+    if (buf.length <= maxBytes)
+        return body;
+    let start = buf.length - maxBytes;
+    while (start < buf.length && isContinuationByte(buf[start]))
+        start += 1;
+    return buf.subarray(start).toString("utf8");
+}
+/**
+ * Cut a `tail-with-first-line` body to `maxBytes`: the body's first line, then
+ * its LAST bytes, dropping the middle. The byte stage's half of the same choice
+ * the line-count stage makes — a body cut for length should lose its middle,
+ * not its end, when the direction says the end is what matters.
+ *
+ * The first line is retained INSIDE the budget, not on top of it: the trailing
+ * slice is measured against what remains once the first line and its newline
+ * are paid for. If the first line alone does not fit, it is itself cut. Either
+ * way nothing is appended after the cut — the trailing slice is what fills the
+ * remaining budget, never an extra.
+ */
+function cutKeepingFirstLine(body, maxBytes) {
+    const lineEnd = body.indexOf("\n");
+    // No newline: the body is one line, so there is no tail distinct from its head.
+    if (lineEnd === -1)
+        return cutToByteCap(body, maxBytes);
+    const firstLine = body.slice(0, lineEnd);
+    const firstLineBytes = Buffer.byteLength(firstLine, "utf8");
+    // Paying for the first line and its newline leaves no room for a tail.
+    if (firstLineBytes + 1 >= maxBytes)
+        return cutToByteCap(firstLine, maxBytes);
+    const tail = tailWithinBytes(body.slice(lineEnd + 1), maxBytes - firstLineBytes - 1);
+    return `${firstLine}\n${tail}`;
+}
+/**
+ * Apply the model-facing truncation policy to a tool result body.
+ *
+ * Three stages, in order, each independently reachable: per-line cap,
+ * line-count cap, byte cap. The pipeline reports `truncated: true` when
+ * any stage changed the content. `originalBytes` always reports the
+ * input's full UTF-8 byte length, regardless of which stages fired.
+ *
+ * Direction governs both stages that drop content: the line-count cap keeps
+ * the first N lines (`head`) or the first line plus the last N-1 lines
+ * (`tail-with-first-line`), and the byte cap keeps the leading bytes or the
+ * first line plus the trailing bytes the same way. Within-cap bodies are
+ * returned unchanged regardless of direction.
+ */
+export function truncateForModel(body, opts) {
+    const originalBytes = Buffer.byteLength(body, "utf8");
+    // Split the body into lines once; every cap is checked against the
+    // line-aware view, so we don't pay for `split("\n")` three times.
+    const lines = splitModelLines(body);
+    // Per-line cap is measured in UTF-16 code units — the same metric
+    // `String#length` reports — so a 2_000-character line of single-unit
+    // codepoints is at the cap, not over it. It is independent of the byte
+    // ceiling: stage 3 alone decides which otherwise-valid bytes are retained.
+    const perLineOver = lines.some((l) => l.length > MODEL_MAX_LINE_CHARS);
+    let working = lines;
+    let changed = false;
+    // Stage 1: per-line cap.
+    if (perLineOver) {
+        const capped = applyLineCharCap(working, MODEL_MAX_LINE_CHARS);
+        working = capped.lines;
+        if (capped.changed)
+            changed = true;
+    }
+    // Stage 2: line-count cap. The cap fires only when the body is strictly
+    // over MODEL_MAX_LINES — within-cap bodies must be returned unchanged
+    // per AC1, so no preview is allowed at smaller scales.
+    if (working.length > MODEL_MAX_LINES) {
+        const trimmed = applyLineCountCap(working, MODEL_MAX_LINES, opts.direction);
+        working = trimmed.lines;
+        if (trimmed.changed)
+            changed = true;
+    }
+    // Re-join with newlines. The trailing-newline convention: the "\n" is
+    // preserved only when the body ended in one and NO stage modified it —
+    // `changed` covers a line merely SHORTENED by stage 1 as well as one
+    // DROPPED by stage 2. Gating on "dropped" alone would be wrong: stage 2
+    // fires only at strictly more than MODEL_MAX_LINES, so a stage-1-shortened
+    // body can sit at exactly MODEL_MAX_LINES lines, and re-emitting "\n" there
+    // inflates `split("\n").length` to MODEL_MAX_LINES + 1 — past the cap that
+    // AC4 pins via the naive split. The conservative guard is deliberate: a
+    // modified body has already lost byte-for-byte fidelity, so dropping its
+    // terminator costs nothing the caller can observe, while re-adding it can
+    // break the count.
+    const joined = working.join("\n");
+    let rebuilt = !changed && body.endsWith("\n") && working.length > 0 ? `${joined}\n` : joined;
+    // Stage 3: byte cap. Runs last, so the byte ceiling is unconditional —
+    // nothing is appended after the cut. The direction decides which bytes
+    // survive the cut, exactly as it decided which lines survived stage 2:
+    // `head` keeps the leading bytes, `tail-with-first-line` keeps the first
+    // line plus the trailing bytes and drops the middle.
+    let truncated = changed;
+    if (Buffer.byteLength(rebuilt, "utf8") > MODEL_MAX_BYTES) {
+        rebuilt =
+            opts.direction === "tail-with-first-line"
+                ? cutKeepingFirstLine(rebuilt, MODEL_MAX_BYTES)
+                : cutToByteCap(rebuilt, MODEL_MAX_BYTES);
+        truncated = true;
+    }
+    // Trim a trailing surrogate so the byte cap (or the per-line cap) cannot
+    // leave the body ending on a lone half of a surrogate pair. A cut that
+    // lands on a UTF-16 surrogate code unit is a structural artifact of the
+    // cap — there is no scenario in which ending the body on a surrogate is
+    // intentional, and downstream UTF-8 decoding of such a body produces a
+    // U+FFFD replacement character that the model cannot distinguish from
+    // a real codepoint. We only strip when something above changed the
+    // content; an untruncated body that happens to end on a surrogate is
+    // already what the caller gave us and is left alone.
+    if (truncated && rebuilt.length > 0) {
+        const lastChar = rebuilt.charCodeAt(rebuilt.length - 1);
+        if (lastChar >= 0xd800 && lastChar <= 0xdfff) {
+            let trimmed = rebuilt.length;
+            while (trimmed > 0) {
+                const c = rebuilt.charCodeAt(trimmed - 1);
+                if (c < 0xd800 || c > 0xdfff)
+                    break;
+                trimmed -= 1;
+            }
+            rebuilt = rebuilt.slice(0, trimmed);
+        }
+    }
+    return { content: rebuilt, truncated, originalBytes };
+}

package/dist/tools/types.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Shared vocabulary for nax's own coding tools.
+ *
+ * Deliberately free of any transport type: this module is imported by the
+ * policy, the tools and the runtime, none of which may see `@nathapp/nax-ai`
+ * (check:nax-ai-imports confines that package to src/agents/native/).
+ */
+/**
+ * Policy identity for RunCommand's allowlisted, model-authored argv branch,
+ * and the marker an operation's `tools` declaration uses to request it.
+ * `Exec` is not a registered tool — nothing in `registerBuiltinCodingTools`
+ * carries this name, and it is reserved (`RESERVED_TOOL_NAMES`) precisely so
+ * no third party can register a tool that shadows the identity.
+ */
+export declare const EXEC_TOOL_NAME = "Exec";
+/**
+ * Policy identity of the model-authored shell tool.
+ *
+ * Unlike `Exec`, `Bash` IS a registered tool — but a session-local one
+ * (`createBashTool`), because it needs the project's shell and env-strip list.
+ * Reserved (`RESERVED_TOOL_NAMES`) so no third party can register a tool that
+ * shadows the identity the policy gates.
+ */
+export declare const BASH_TOOL_NAME = "Bash";
+/** The tools nax ships. Third parties register additional names at runtime. */
+export type CodingToolName = "Read" | "Glob" | "Grep" | "Write" | "Edit" | "Delete" | "Git" | "GitCommit" | "RunCommand" | "RequestCapability" | "Exec" | "Bash" | "ScratchpadWrite" | "ScratchpadRead" | "ScratchpadList";
+/**
+ * One declarative permission grant, as produced by resolvePermissions.
+ *
+ * `patterns` is either globs over the tool's path-bearing fields
+ * (`["src/**"]`), or the verb list for a verb-gated tool (`["diff","log"]`).
+ * `["*"]` means unconditional — but never wider than the root.
+ */
+export interface ToolGrant {
+    readonly tool: string;
+    readonly patterns: readonly string[];
+}
+/**
+ * How the policy gates a given tool, declared by the tool itself.
+ *
+ * Declaring the path-bearing fields is what lets the policy gate a tool it has
+ * no special knowledge of, including one registered by a third party. A tool
+ * with no path fields is gated at the tool/verb level instead — the honest
+ * expression for something whose arguments are not paths.
+ *
+ * `arrayPathFields` and `refPathFields` extend the same containment seam to
+ * array-valued inputs — Git is the only current user.
+ *
+ * A verb-gated tool's grant list is overloaded: `["diff","log"]` are verbs, so
+ * matching them against a path denies everything. The policy separates the two
+ * by `allowedVerbs`, a closed set the tool declares — a pattern naming a
+ * permitted verb is a verb, anything else is a path glob. So `Git(diff,src/**)`
+ * grants the `diff` verb over `src/**`, and `Git(diff)` declares no path glob
+ * and is bounded by the root alone.
+ */
+export interface ToolScope {
+    /**
+     * String paths in the input. Dot-separated names address nested object
+     * properties (for example `values.files` in RunCommand).
+     */
+    readonly pathFields: readonly string[];
+    /**
+     * Root-relative subdirectory the tool's path fields are confined to.
+     * Containment runs against `<root>/<confineTo>` instead of `<root>`, so a
+     * path-bearing tool can never reach the rest of the repository even under
+     * an unconditional grant. Grant globs, deny rules and `naxOwnedWriteRefusal`
+     * keep seeing the canonical repo-root-relative spelling: containment is the
+     * single seam, only its ROOT shifts. Tool-declared, never config-declared --
+     * a mis-set `pathFields` grant must not be able to widen the tool's reach.
+     */
+    readonly confineTo?: string;
+    /** Array-valued fields whose every element is a path. */
+    readonly arrayPathFields?: readonly string[];
+    /**
+     * String fields whose value is a whitespace-separated LIST of paths, every
+     * element resolved and grant-checked on its own (`splitPathList`).
+     *
+     * Distinct from `pathFields`, which checks the value as ONE path. That is
+     * sound only while the value also REACHES the shell as one argument: a
+     * multi-element value like `"a.test.ts ../../etc/passwd"` resolves, as a
+     * single path, to a location inside the root, so `pathFields` approves it.
+     * Whole-value quoting is what kept that honest -- and whole-value quoting is
+     * exactly the defect #1998 fixes. So per-element quoting and per-element
+     * checking have to land together: this field is the checking half. Nothing
+     * was exploitable before; splitting without it would have made it so.
+     */
+    readonly listPathFields?: readonly string[];
+    /**
+     * Array-valued fields whose elements are refs that MAY carry a path after a
+     * `:` (git's `<rev>:<path>` syntax). Only the substring after the first `:`
+     * is checked for containment; an element with no `:`, or an empty path
+     * after it, is a pure revision and is left unchecked.
+     */
+    readonly refPathFields?: readonly string[];
+    readonly verbField?: string;
+    readonly allowedVerbs?: readonly string[];
+    /**
+     * The input field holding a model-authored argv (RunCommand's `Exec`
+     * branch). When a call carries this field, the policy checks it under the
+     * `Exec` identity (`EXEC_TOOL_NAME`), matching each grant pattern against
+     * the argv token-by-token, rather than under the tool's own name — an
+     * `Exec(...)` grant is otherwise never consulted and a `RunCommand(*)`
+     * wildcard would silently cover the argv branch too.
+     */
+    readonly argvField?: string;
+    /**
+     * The input field holding a model-authored shell COMMAND STRING (`Bash`).
+     * A call carrying this field is evaluated per shell segment by
+     * `src/tools/policy-bash.ts` rather than by the verb or path branches; a
+     * tool declaring it must be granted explicitly, since no profile grants one.
+     */
+    readonly commandField?: string;
+}
+/**
+ * `breach` separates "you may not write there" from "that path is not in this
+ * repository at all". Both deny; only the latter is logged at warn, because a
+ * path escaping the root can mean prompt injection.
+ *
+ * `outcome` makes the refusal three-state. "ask" means every OTHER gate passed
+ * and an ask rule matched -- an AskResolver may approve it (spec R1). Absent or
+ * "denied" is final. The ask shape is still `allowed: false` on purpose: any
+ * consumer that only reads `allowed` fails closed. `resolvedPaths` is present
+ * only with "ask", describing what an approval would admit.
+ */
+export type PolicyVerdict = {
+    readonly allowed: true;
+    readonly resolvedPaths: readonly string[];
+} | {
+    readonly allowed: false;
+    readonly reason: string;
+    readonly breach: boolean;
+    readonly outcome?: "denied" | "ask";
+    readonly resolvedPaths?: readonly string[];
+    /** Present only with outcome "ask": the matching configured rule expression. */
+    readonly rule?: string;
+    /** See BashCheck.escalatable in policy-bash.ts. `false` on every
+     * non-escalatable denial (the shared deny helper materializes it on
+     * every branch), which reads as not-escalatable. */
+    readonly escalatable?: boolean;
+};
+export interface ToolPolicy {
+    readonly root: string;
+    grantedTools(): readonly string[];
+    check(tool: string, scope: ToolScope, input: Record<string, unknown>): PolicyVerdict;
+}

package/dist/tools/types.js

@@ -0,0 +1,24 @@
+/**
+ * Shared vocabulary for nax's own coding tools.
+ *
+ * Deliberately free of any transport type: this module is imported by the
+ * policy, the tools and the runtime, none of which may see `@nathapp/nax-ai`
+ * (check:nax-ai-imports confines that package to src/agents/native/).
+ */
+/**
+ * Policy identity for RunCommand's allowlisted, model-authored argv branch,
+ * and the marker an operation's `tools` declaration uses to request it.
+ * `Exec` is not a registered tool — nothing in `registerBuiltinCodingTools`
+ * carries this name, and it is reserved (`RESERVED_TOOL_NAMES`) precisely so
+ * no third party can register a tool that shadows the identity.
+ */
+export const EXEC_TOOL_NAME = "Exec";
+/**
+ * Policy identity of the model-authored shell tool.
+ *
+ * Unlike `Exec`, `Bash` IS a registered tool — but a session-local one
+ * (`createBashTool`), because it needs the project's shell and env-strip list.
+ * Reserved (`RESERVED_TOOL_NAMES`) so no third party can register a tool that
+ * shadows the identity the policy gates.
+ */
+export const BASH_TOOL_NAME = "Bash";

package/dist/tools/verb-denial-argv-hint.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The extra clause `policy.ts`'s `verbBranch` appends to a subcommand denial
+ * when the tool also offers an argv escape hatch (`scope.argvField`).
+ *
+ * run-2026-09-14T05-55-54-734Z, Shape B: an agent with argv available still
+ * stuffed raw shell into the verb field repeatedly rather than ever trying
+ * "argv" -- so the structural fact ("this field is never a shell string") is
+ * stated unconditionally. But a bare "use argv instead" would have sent
+ * every one of the audit's four real denials straight into a SECOND one:
+ * the compiled Exec grant was install-only (`bun install`, `bun add*`, ...)
+ * against requests like "bun test ... | head -200" and "wc". So the actual
+ * compiled grant is named here too, using the identical text
+ * `describeExecAllowlist` already renders into the tool description, which
+ * is what lets an agent see in one denial whether argv would help at all
+ * before spending a second turn finding out.
+ *
+ * Extracted from `policy.ts` into its own module so that file (already at
+ * its 600-line limit) can carry this explanation without trimming it.
+ *
+ * The clause names `argvField` explicitly (for "argv", ...) rather than
+ * appending `describeExecAllowlist`'s bare "permitted forms: ..." after the
+ * structural sentence: two unlabelled "permitted ..." lists back to back --
+ * one for `verbField`'s enum, one for argv's grant -- reads as a single
+ * list, and an agent can misread the second half as more legal values for
+ * `verbField`, denying again on the enum (the very second-denial loop this
+ * exists to prevent). `describeExecAllowlist`'s own text is unchanged: the
+ * tool description's surrounding sentence already establishes argv as the
+ * subject there, so this supplies its own framing around the same list
+ * rather than editing shared text to fit one caller. The framing is a bare
+ * attribution ("for \"argv\", ...") precisely so it composes with whichever
+ * of describeExecAllowlist's three forms is returned -- prefixing a verb
+ * such as "accepts:" instead would double the label on the populated form
+ * ("accepts: permitted forms: ...") and misread the empty one.
+ */
+export declare function argvShellHint(verbField: string, argvField: string | undefined, execPatterns: readonly string[]): string;

package/dist/tools/verb-denial-argv-hint.js

@@ -0,0 +1,40 @@
+import { describeExecAllowlist } from "./exec-allowlist-text.js";
+/**
+ * The extra clause `policy.ts`'s `verbBranch` appends to a subcommand denial
+ * when the tool also offers an argv escape hatch (`scope.argvField`).
+ *
+ * run-2026-09-14T05-55-54-734Z, Shape B: an agent with argv available still
+ * stuffed raw shell into the verb field repeatedly rather than ever trying
+ * "argv" -- so the structural fact ("this field is never a shell string") is
+ * stated unconditionally. But a bare "use argv instead" would have sent
+ * every one of the audit's four real denials straight into a SECOND one:
+ * the compiled Exec grant was install-only (`bun install`, `bun add*`, ...)
+ * against requests like "bun test ... | head -200" and "wc". So the actual
+ * compiled grant is named here too, using the identical text
+ * `describeExecAllowlist` already renders into the tool description, which
+ * is what lets an agent see in one denial whether argv would help at all
+ * before spending a second turn finding out.
+ *
+ * Extracted from `policy.ts` into its own module so that file (already at
+ * its 600-line limit) can carry this explanation without trimming it.
+ *
+ * The clause names `argvField` explicitly (for "argv", ...) rather than
+ * appending `describeExecAllowlist`'s bare "permitted forms: ..." after the
+ * structural sentence: two unlabelled "permitted ..." lists back to back --
+ * one for `verbField`'s enum, one for argv's grant -- reads as a single
+ * list, and an agent can misread the second half as more legal values for
+ * `verbField`, denying again on the enum (the very second-denial loop this
+ * exists to prevent). `describeExecAllowlist`'s own text is unchanged: the
+ * tool description's surrounding sentence already establishes argv as the
+ * subject there, so this supplies its own framing around the same list
+ * rather than editing shared text to fit one caller. The framing is a bare
+ * attribution ("for \"argv\", ...") precisely so it composes with whichever
+ * of describeExecAllowlist's three forms is returned -- prefixing a verb
+ * such as "accepts:" instead would double the label on the populated form
+ * ("accepts: permitted forms: ...") and misread the empty one.
+ */
+export function argvShellHint(verbField, argvField, execPatterns) {
+    if (argvField === undefined)
+        return "";
+    return ` -- "${verbField}" never takes a shell string -- for "${argvField}", ${describeExecAllowlist(execPatterns)}`;
+}

package/dist/tools/write.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Write a file whose path the policy already resolved and approved.
+ *
+ * No production op declares this tool: everything that writes also needs to run
+ * tests, which needs Bash, which C1 excludes. It exists so #374's gate has a
+ * concrete subject (design section 3.5) and is exercised by tests alone.
+ */
+import type { CodingTool } from "./registry.ts";
+export declare const writeTool: CodingTool;