@nathapp/nax-agent 0.1.0

package/dist/tools/ask-request.js

@@ -0,0 +1,57 @@
+/**
+ * The one-line call description an AskResolver receives, and the reason a
+ * `denied:ask` ledger row carries.
+ *
+ * Summaries are outbound to a human, so they are masked through
+ * `maskForPrompt` before they leave the process; a secret that cannot be
+ * shown safely withholds the arguments entirely (`unshowable`, review #9).
+ */
+import { ASK_CANCELLED_REASON, ASK_DENIED_REASON, ASK_NO_CHANNEL_REASON, ASK_TIMEOUT_REASON, ASK_UNSHOWABLE_REASON, maskForPrompt, } from "#src/permissions/index";
+/** Ceiling for the one-line call description an AskResolver receives. */
+export const MAX_ASK_SUMMARY_CHARS = 200;
+/**
+ * One human-readable line describing the call an `ask` rule matched.
+ *
+ * Built from the scope's DECLARED fields rather than from `JSON.stringify` of
+ * the whole input: the input carries a tool's full payload -- file contents on
+ * a Write, a commit message, whatever a provider tool takes -- and an
+ * AskResolver is by definition an outbound channel to a human. A summary is
+ * what approval needs; the payload is what the audit sink already holds.
+ */
+export function askSummary(tool, scope, input) {
+    const fields = [scope.commandField, scope.argvField, scope.verbField, ...scope.pathFields];
+    const parts = fields.flatMap((field) => {
+        if (field === undefined)
+            return [];
+        const value = input[field];
+        if (typeof value === "string")
+            return [`${field}=${value}`];
+        if (Array.isArray(value))
+            return [`${field}=${value.filter((v) => typeof v === "string").join(" ")}`];
+        return [];
+    });
+    // Mask the FULL line, then cut: cutting first can split a secret so no
+    // pattern matches what is left, and the partial secret would go out.
+    const masked = maskForPrompt(`${tool} ${parts.join(" ")}`.trim());
+    if (!masked.ok)
+        return { summary: `${tool} [arguments withheld: contains a secret]`, unshowable: true };
+    return { summary: masked.masked.slice(0, MAX_ASK_SUMMARY_CHARS), unshowable: false };
+}
+/**
+ * The reason a `denied:ask` ledger row carries, chosen by WHO refused.
+ *
+ * One constant for every ask denial asserted "no approval channel is
+ * configured" even when a human answered (deny) or nobody answered in time
+ * (timeout). Those are materially different facts; see ASK_*_REASON.
+ */
+export function askDenyReason(decidedBy) {
+    if (decidedBy === "timeout")
+        return ASK_TIMEOUT_REASON;
+    if (decidedBy === "human")
+        return ASK_DENIED_REASON;
+    if (decidedBy === "cancelled")
+        return ASK_CANCELLED_REASON;
+    if (decidedBy === "unshowable")
+        return ASK_UNSHOWABLE_REASON;
+    return ASK_NO_CHANNEL_REASON;
+}

package/dist/tools/bash-cwd.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Per-segment shell working-directory tracking, shared by the two Bash
+ * payload screens (`policy-bash.ts`'s `checkBashCommand` and
+ * `policy-bash-raw.ts`'s `screenRawBashCommand`).
+ *
+ * A `cd` in one segment moves the frame of reference for every LATER segment
+ * in the same command (`cd child && cat ../secret` reads `<root>/secret`, not
+ * `<root>/child/secret`), so both screens must track it identically to avoid
+ * being fooled by it. This module is the ONE definition of "what does a `cd`
+ * segment resolve to, and how do separators fold that into the running set
+ * of candidate working directories" -- mirroring `isNaxOwnedWritePath` in
+ * `nax-owned-writes.ts`, which is the same one-definition-two-callers shape
+ * for a different seam.
+ *
+ * What this module does NOT decide: what happens when a `cd` cannot be
+ * modelled (an option-shaped target, an opaque one, one that fails to
+ * resolve). The two callers have OPPOSITE answers to that question --
+ * `checkBashCommand` denies (containment is the whole point of gated mode),
+ * `screenRawBashCommand` must fail open (raw enforces no containment by
+ * definition; see the caller's own docblock for why). `cdTargetsFor` reports
+ * WHY a `cd` could not be modelled and leaves the verdict to the caller.
+ */
+import type { BashSegment } from "#src/permissions/index";
+/**
+ * The outcome of inspecting one segment for a `cd`:
+ *
+ * - `not-cd`: the segment does not start with `cd`; nothing to track.
+ * - `resolved`: a `cd` whose target resolved against EVERY current frame.
+ * - `no-target`: `cd` with no argument at all.
+ * - `option-shaped`: the target starts with `-` (`cd -`, `cd -P dir`) and
+ *   puts the path in a slot this reader does not parse.
+ * - `opaque`: the target contains `$`-expansion; its runtime value is
+ *   unknown here.
+ * - `unresolved`: the target failed to resolve from at least one current
+ *   frame (root escape, `.git/`, or whatever `resolvePath` itself refuses).
+ */
+export type CdTargetResult = {
+    readonly kind: "not-cd";
+} | {
+    readonly kind: "resolved";
+    readonly targets: readonly string[];
+} | {
+    readonly kind: "no-target";
+} | {
+    readonly kind: "option-shaped";
+    readonly text: string;
+} | {
+    readonly kind: "opaque";
+    readonly text: string;
+} | {
+    readonly kind: "unresolved";
+    readonly text: string;
+};
+/**
+ * Reads a segment as a possible `cd`, resolving its target against every
+ * frame in `cwd` via the caller-supplied `resolvePath` (the same containment
+ * callback both policy modules already receive from `policy.ts`).
+ *
+ * Resolves against ALL frames, not just the first, for the same reason
+ * `checkPayload`'s old `resolveAll` did: after a `;`-joined `cd`, more than
+ * one frame can be live at once (see `nextWorkingDirectories` below), and a
+ * target that is safe from one frame but escapes from another must not be
+ * silently narrowed to the safe one.
+ */
+export declare function cdTargetsFor(segment: BashSegment, cwd: readonly string[], resolvePath: (candidate: string, cwd: string) => string | null): CdTargetResult;
+/**
+ * Folds a segment's `cd` targets (if any) into the running set of candidate
+ * working directories, per the separator that FOLLOWS it:
+ *
+ * - `&&`: the shell only reaches the next segment if this one succeeded, and
+ *   a successful `cd` REPLACES the working directory outright.
+ * - `;`: the next segment runs regardless of whether the `cd` succeeded, so
+ *   both the old and new frames stay live -- the command might still be
+ *   sitting in the OLD directory when the next segment runs.
+ * - anything else (`||`, `|`, `&`, or no separator / the last segment): a
+ *   `cd`'s effect on a LATER segment is not modelled, so the frame set is
+ *   left unchanged.
+ *
+ * `cdTargets` is `undefined` for a non-`cd` segment (or one this reader could
+ * not resolve, per `cdTargetsFor`), in which case the frame set never changes.
+ */
+export declare function nextWorkingDirectories(segment: BashSegment, current: readonly string[], cdTargets: readonly string[] | undefined): readonly string[];

package/dist/tools/bash-cwd.js

@@ -0,0 +1,55 @@
+/**
+ * Reads a segment as a possible `cd`, resolving its target against every
+ * frame in `cwd` via the caller-supplied `resolvePath` (the same containment
+ * callback both policy modules already receive from `policy.ts`).
+ *
+ * Resolves against ALL frames, not just the first, for the same reason
+ * `checkPayload`'s old `resolveAll` did: after a `;`-joined `cd`, more than
+ * one frame can be live at once (see `nextWorkingDirectories` below), and a
+ * target that is safe from one frame but escapes from another must not be
+ * silently narrowed to the safe one.
+ */
+export function cdTargetsFor(segment, cwd, resolvePath) {
+    const words = segment.tokens.map((token) => token.text);
+    if (words[0] !== "cd")
+        return { kind: "not-cd" };
+    const target = segment.tokens[1];
+    if (target === undefined)
+        return { kind: "no-target" };
+    // `cd -` returns to $OLDPWD and `cd -P x` puts the path in a later slot:
+    // both leave a naive reader tracking `<root>/-` as the new frame of
+    // reference while the shell is somewhere else. Option-shaped, not modelled.
+    if (target.text.startsWith("-"))
+        return { kind: "option-shaped", text: target.text };
+    if (target.opaque)
+        return { kind: "opaque", text: target.text };
+    const resolved = cwd.map((directory) => resolvePath(target.text, directory));
+    if (!resolved.every((path) => path !== null))
+        return { kind: "unresolved", text: target.text };
+    return { kind: "resolved", targets: resolved };
+}
+/**
+ * Folds a segment's `cd` targets (if any) into the running set of candidate
+ * working directories, per the separator that FOLLOWS it:
+ *
+ * - `&&`: the shell only reaches the next segment if this one succeeded, and
+ *   a successful `cd` REPLACES the working directory outright.
+ * - `;`: the next segment runs regardless of whether the `cd` succeeded, so
+ *   both the old and new frames stay live -- the command might still be
+ *   sitting in the OLD directory when the next segment runs.
+ * - anything else (`||`, `|`, `&`, or no separator / the last segment): a
+ *   `cd`'s effect on a LATER segment is not modelled, so the frame set is
+ *   left unchanged.
+ *
+ * `cdTargets` is `undefined` for a non-`cd` segment (or one this reader could
+ * not resolve, per `cdTargetsFor`), in which case the frame set never changes.
+ */
+export function nextWorkingDirectories(segment, current, cdTargets) {
+    if (cdTargets === undefined)
+        return current;
+    if (segment.separator === "&&")
+        return cdTargets;
+    if (segment.separator === ";")
+        return [...new Set([...current, ...cdTargets])];
+    return current;
+}

package/dist/tools/bash.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The model-authored shell tool (spec §4 US-004).
+ *
+ * Session-local like `RunCommand`, not a global registry entry: it needs the
+ * project's shell and secret-strip list, which are per-config. Created only
+ * when the operation DECLARED it (see coding-tool-support.ts) — a tool the
+ * global registry held would be callable by an op that never declared it,
+ * because `callTool` looks a name up before it consults advertisement.
+ *
+ * WHERE IT RUNS: `ctx.root`, the hop's permitted root and the same root the
+ * policy resolved every path against. Never the runtime's workdir — under `-d`
+ * those differ, and that difference is the #1794 defect.
+ *
+ * WHAT GATES IT: nothing here. The command string reached this function only
+ * because `policy.check` already lexed it, matched every segment against the
+ * stage's `Bash(...)` rules and containment-checked its paths and redirects
+ * (src/tools/policy-bash.ts). This module must never be given a "safe enough"
+ * check of its own: two gates in two places drift, and the second one is the
+ * one nobody tests. The launcher (P4) changes HOW the command runs -- inside
+ * an OS sandbox when enabled -- never WHETHER.
+ */
+import { runArgv } from "#src/internal/argv-exec";
+import type { BashApprovalMode } from "../config/bash-approval.ts";
+import { type CommandLauncher } from "../sandbox/index.ts";
+import type { CodingTool } from "./registry.ts";
+/**
+ * Deadline for a Bash spawn — the same ceiling the Exec branch uses
+ * (`EXEC_TIMEOUT_MS`, src/tools/run-command-exec.ts). A model-authored command
+ * may legitimately be a build or a full test run, and a shorter default would
+ * be worked around rather than respected.
+ */
+export declare const BASH_TIMEOUT_MS = 300000;
+export declare const DEFAULT_BASH_SHELL = "/bin/sh";
+export interface BashToolOptions {
+    /** `quality.shell`. */
+    readonly shell?: string;
+    /** `quality.stripEnvVars` — secrets removed before the spawn. */
+    readonly stripEnvVars?: readonly string[];
+    /** The stage's granted patterns, for the DESCRIPTION only. The policy is the
+     * gate; naming the granted forms here is what stops the model spending a
+     * turn discovering them by denial. Ignored under `raw` (see
+     * `rawDescription` below) -- there is no per-pattern grant to name. */
+    readonly patterns?: readonly string[];
+    /**
+     * ADR-030 mode this description should reflect. Defaults to `gated`, the
+     * conservative posture, matching `compileToolPolicy`'s own default so an
+     * omitted mode never advertises a capability the policy would not actually
+     * grant.
+     */
+    readonly bashApproval?: BashApprovalMode;
+    /**
+     * Whether a human can answer an escalated command (ADR-030, amended for P4).
+     * Read only under `escalate`; absent or false keeps `gated`'s wording, since
+     * a run with no interaction channel denies every ask as `unavailable`.
+     */
+    readonly humanApproval?: boolean;
+    /**
+     * P4: how the command runs. Absent = today's direct spawn through
+     * `_bashToolDeps.runArgv` (unit tests). Production always passes one --
+     * disabled, available or unavailable -- and its state also shapes the
+     * description, so the agent always knows whether it is sandboxed.
+     */
+    readonly launcher?: CommandLauncher;
+}
+/** Injectable spawn seam, mirroring `_argvExecDeps`. */
+export declare const _bashToolDeps: {
+    runArgv: typeof runArgv;
+};
+export declare function createBashTool(opts?: BashToolOptions): CodingTool;

package/dist/tools/bash.js

@@ -0,0 +1,283 @@
+/**
+ * The model-authored shell tool (spec §4 US-004).
+ *
+ * Session-local like `RunCommand`, not a global registry entry: it needs the
+ * project's shell and secret-strip list, which are per-config. Created only
+ * when the operation DECLARED it (see coding-tool-support.ts) — a tool the
+ * global registry held would be callable by an op that never declared it,
+ * because `callTool` looks a name up before it consults advertisement.
+ *
+ * WHERE IT RUNS: `ctx.root`, the hop's permitted root and the same root the
+ * policy resolved every path against. Never the runtime's workdir — under `-d`
+ * those differ, and that difference is the #1794 defect.
+ *
+ * WHAT GATES IT: nothing here. The command string reached this function only
+ * because `policy.check` already lexed it, matched every segment against the
+ * stage's `Bash(...)` rules and containment-checked its paths and redirects
+ * (src/tools/policy-bash.ts). This module must never be given a "safe enough"
+ * check of its own: two gates in two places drift, and the second one is the
+ * one nobody tests. The launcher (P4) changes HOW the command runs -- inside
+ * an OS sandbox when enabled -- never WHETHER.
+ */
+import { interceptShell } from "#src/command-interceptor/index";
+import { agentOutputOverlay } from "#src/internal/agent-output-env";
+import { runArgv } from "#src/internal/argv-exec";
+import { formatExecBody } from "#src/internal/exec-framing";
+import { rawBashRefusalReason, sandboxSentence, unsandboxedSentence } from "../sandbox/index.js";
+import { cutToByteCap, READ_CEILING } from "./truncate.js";
+import { BASH_TOOL_NAME } from "./types.js";
+/**
+ * Deadline for a Bash spawn — the same ceiling the Exec branch uses
+ * (`EXEC_TIMEOUT_MS`, src/tools/run-command-exec.ts). A model-authored command
+ * may legitimately be a build or a full test run, and a shorter default would
+ * be worked around rather than respected.
+ */
+export const BASH_TIMEOUT_MS = 300_000;
+/** Floor for a caller-requested deadline: below this, a real command cannot
+ * even start, and a 0 would disable the deadline entirely. */
+const MIN_BASH_TIMEOUT_MS = 1_000;
+export const DEFAULT_BASH_SHELL = "/bin/sh";
+/** Injectable spawn seam, mirroring `_argvExecDeps`. */
+export const _bashToolDeps = {
+    runArgv,
+};
+function describeGrants(patterns) {
+    const named = (patterns ?? []).filter((pattern) => pattern !== "*");
+    if (patterns?.includes("*") === true)
+        return "every command form is granted for this stage";
+    if (named.length === 0)
+        return "no command forms are granted for this stage";
+    return `granted command forms: ${named.join(", ")}`;
+}
+const PREFER_STRUCTURED_TOOLS_SENTENCE = "PREFER the structured tools when they express the task -- Read, Glob, Grep, Git and RunCommand return " +
+    "bounded, parseable output, and Bash exists for what they cannot express. ";
+/**
+ * US-001: a background process holding a pipe keeps the shell from exiting
+ * cleanly, so the runtime SIGKILLs the whole process group after a short
+ * drain grace. Every description variant states this so the model knows its
+ * `&`ed processes will not outlive the call.
+ */
+const BACKGROUND_PROCESSES_KILLED_SENTENCE = "background processes still holding the command's output are killed when the command exits. ";
+/**
+ * `gated`'s description, also used verbatim for `escalate` when no human is
+ * reachable -- see the `escalate` branch of `bashToolDescription`.
+ */
+function gatedDescription(shell, patterns) {
+    return (`Run one shell command string under ${shell}. ${PREFER_STRUCTURED_TOOLS_SENTENCE}` +
+        `${describeGrants(patterns)}; anything else is refused. ` +
+        "Each segment of a `&&`/`||`/`;`/`|` chain is checked separately, and command substitution ($(...), backticks), " +
+        "process substitution, here-documents and `2>&1` are refused outright because they cannot be analysed. " +
+        "Paths and redirect targets must stay inside the repository root. " +
+        BACKGROUND_PROCESSES_KILLED_SENTENCE);
+}
+function capitalize(text) {
+    return text.charAt(0).toUpperCase() + text.slice(1);
+}
+/**
+ * `escalate`'s description when a human is reachable (ADR-030, amended
+ * 2026-09-23 and again for US-001). It states checkBashCommand's ACTUAL order:
+ * the out-of-bounds payload checks and the deny matcher run BEFORE the
+ * escalatable sites -- a lexer refusal, a grant miss, and the one payload
+ * refusal the gate cannot adjudicate, an option-shaped `cd` -- so an
+ * out-of-bounds command never reaches the human; on a refused command those
+ * checks cover the lexable prefix -- the part before the unreadable construct
+ * -- and an approved command runs as written. Pinned against the policy in
+ * coding-tool-bash-escalate-truth.test.ts.
+ */
+function escalateDescription(shell, patterns) {
+    return (`Run one shell command string under ${shell}. ${PREFER_STRUCTURED_TOOLS_SENTENCE}` +
+        `${capitalize(describeGrants(patterns))}. Every command, granted or not, is checked first: paths ` +
+        "and redirect targets must stay inside the repository root, and `.git/` access, denied flags, unexpanded " +
+        "`$VAR`, glob or brace characters, `~`, a bare `cd`, and a command matching a deny rule are " +
+        "refused without asking. For a command using a construct that cannot be analysed (e.g. command or process " +
+        "substitution, backticks, here-documents, subshells, `2>&1`, `#` comments, an option-shaped `cd`), these " +
+        "checks cover the part before that construct. A command outside the granted forms, or one using a construct " +
+        "that cannot be analysed, is not refused: it is sent to a human for approval (unless an identical command " +
+        "was already approved and remembered) and, if they allow it, runs exactly as written; it is refused if they " +
+        "deny it or do not answer in time, so prefer the granted forms. Each segment of a `&&`/`||`/`;`/`|` chain is " +
+        "checked separately. " +
+        BACKGROUND_PROCESSES_KILLED_SENTENCE);
+}
+/**
+ * `raw`'s description (ADR-030 / F3). Under `raw`, `checkBashCommand` is
+ * never consulted at all -- `commandBranch` in policy-command-branch.ts
+ * dispatches to `screenRawBashCommand` and returns before it ever reads
+ * `denyBy`/`askBy` -- so every clause of `gatedDescription` above is false
+ * under this mode, and advertising it would push the model toward the exact
+ * workaround (reading whole files instead of piping/grepping them) this ADR
+ * exists to stop paying for.
+ */
+const RAW_UNCONTAINED = "The command runs from the repository root, but paths are NOT contained to it: a command may read or write anywhere the nax process " +
+    "itself can reach, inside the repository or outside it. ";
+function rawDescription(shell, containment = RAW_UNCONTAINED) {
+    return (`Run one shell command string under ${shell}. ${PREFER_STRUCTURED_TOOLS_SENTENCE}` +
+        "This stage runs under raw mode (ADR-030): pipes, redirects, command substitution ($(...), backticks), " +
+        "process substitution, here-documents and subshells all work here -- nothing is refused for being unparseable, " +
+        "and Bash allow/deny/ask rules configured for this stage are NOT consulted. " +
+        containment +
+        "One refusal is a command the lexer CAN parse that names or redirects into one of the exact file " +
+        "paths nax owns -- .nax/config.json, .nax/mono/*/config.json, " +
+        ".nax/features/**/prd.json, or the root queue-control files -- change those through nax rather than by " + // nax-feature-dir-allow: prose naming the raw-mode protected-path screen, not a path construction
+        "writing them directly. That screen is advisory, not a boundary: it matches exact file paths only, so a " +
+        "command using command substitution, a directory target (cp x .nax/), a glob, a nested shell (sh -c '...'), " +
+        "tar -C or dd of=, or a symlink alias all skip it; use the sandbox for a boundary. " +
+        "A `find` whose start path is `/`, `~` or `$HOME` is refused -- search within the repository instead. " +
+        BACKGROUND_PROCESSES_KILLED_SENTENCE);
+}
+function rawUnavailableDescription(shell, reason) {
+    return (`Run one shell command string under ${shell} -- but on this machine ${rawBashRefusalReason(reason)} ` +
+        "Under raw mode every call is refused; use the structured tools (Read, Glob, Grep, Git, RunCommand) instead. " +
+        BACKGROUND_PROCESSES_KILLED_SENTENCE);
+}
+function bashToolDescription(shell, opts) {
+    const state = opts.launcher?.state ?? { kind: "disabled" };
+    if (opts.bashApproval === "raw") {
+        if (state.kind === "available")
+            return rawDescription(shell, `The command runs from the repository root ${sandboxSentence(state.network, state.sharedTmp !== false)} `);
+        if (state.kind === "unavailable")
+            return rawUnavailableDescription(shell, state.reason);
+        return rawDescription(shell);
+    }
+    // `escalate` describes escalation ONLY when a human is reachable (ADR-030,
+    // amended for P4). Reachability is a separate config axis -- is an
+    // interaction channel configured? -- resolved at the execution stage and
+    // passed in as data. Without one every ask resolves `unavailable` and
+    // denies, so the wording stays byte-identical to `gated`'s: promising a
+    // human there would be the D13a fail-open shape stated in prose.
+    const policyDescription = opts.bashApproval === "escalate" && opts.humanApproval === true
+        ? escalateDescription(shell, opts.patterns)
+        : gatedDescription(shell, opts.patterns);
+    if (state.kind === "available") {
+        return `${policyDescription} Commands that pass run ${sandboxSentence(state.network, state.sharedTmp !== false)}`;
+    }
+    if (state.kind === "unavailable")
+        return `${policyDescription} ${unsandboxedSentence(state.reason)}`;
+    return policyDescription;
+}
+/**
+ * Intercept, launch, post-process — everything that decides WHICH command ran.
+ * `run` keeps only the framing.
+ *
+ * The interception belongs HERE and not above the tool: `callTool` has already
+ * lexed and gated the model's ORIGINAL string against the stage's `Bash(...)`
+ * rules, and this is the first point after that verdict. The rewrite is
+ * therefore never the string the policy judged, which is exactly why
+ * `interceptShell` re-validates the provider's answer rather than trusting it.
+ */
+async function launchIntercepted({ command, shell, opts, ctx, timeoutMs, }) {
+    // The run's interceptor arrives on the context (S1 spec port 7), immutable
+    // for this call, so the launch below and `postProcess` see the same object.
+    const interceptor = ctx.interceptor;
+    const intercepted = await interceptShell(command, ctx.root, interceptor);
+    const executed = [shell, "-c", intercepted.command];
+    // US-004: opt the child into agent-friendly output. The same rule the
+    // quality and verification runners apply, just at the agent-facing spawn
+    // site. Marker presence is read from the nax process environment (via
+    // `_agentOutputEnvDeps.processEnv`), so an inherited CLAUDECODE/REPL_ID is
+    // left to speak for itself, and a stripped AGENT stays stripped. The overlay
+    // is a small record layered on top of `process.env` — undefined when there
+    // is nothing to add, so the child inherits its parent untouched.
+    const agentOverlay = agentOutputOverlay(opts.stripEnvVars ?? []);
+    const common = {
+        cwd: ctx.root,
+        timeoutMs,
+        stripEnvVars: [...(opts.stripEnvVars ?? [])],
+        ...(agentOverlay !== undefined ? { env: agentOverlay } : {}),
+        ...(ctx.signal !== undefined ? { signal: ctx.signal } : {}),
+    };
+    const launched = opts.launcher !== undefined
+        ? await opts.launcher.run({
+            spec: { kind: "shell", shell, command: intercepted.command },
+            root: ctx.root,
+            ...common,
+        })
+        : { ...(await _bashToolDeps.runArgv({ argv: executed, ...common })), executed, sandbox: undefined };
+    if (!intercepted.rewritten)
+        return { launched, stdout: launched.stdout };
+    // The request describes the command the MODEL wrote — the same shape
+    // `interceptShell` sent — so post-processing stays keyed to the original,
+    // mirroring the Git site, which passes the original argv.
+    const req = { kind: "shell", command, cwd: ctx.root, site: "bash" };
+    try {
+        const processed = interceptor?.postProcess?.(launched.stdout, req)?.output;
+        return { launched, stdout: processed ?? launched.stdout };
+    }
+    catch {
+        // Advisory, like the rewrite-time fail-open: a sick post-processor must not
+        // discard the output of a command that actually ran.
+        return { launched, stdout: launched.stdout };
+    }
+}
+export function createBashTool(opts = {}) {
+    const shell = opts.shell ?? DEFAULT_BASH_SHELL;
+    return {
+        name: BASH_TOOL_NAME,
+        // A non-zero exit from a command the model wrote is its own red/green loop,
+        // not a fault worth an operator's attention — the same reason RunCommand
+        // sets this.
+        routineErrors: true,
+        description: bashToolDescription(shell, opts),
+        inputSchema: {
+            type: "object",
+            properties: {
+                command: { type: "string", description: 'The shell command to run, e.g. "bun test src/a.test.ts"' },
+                timeoutMs: {
+                    type: "number",
+                    description: `Deadline in milliseconds (default and maximum ${BASH_TIMEOUT_MS}).`,
+                },
+                description: { type: "string", description: "One short line on what this command is for." },
+            },
+            required: ["command"],
+        },
+        // `commandField` is what routes this call to the Bash branch of the policy
+        // (src/tools/policy-bash.ts). No pathFields: the paths are inside the
+        // command string, where only that branch can see them.
+        scope: { pathFields: [], commandField: "command" },
+        async run(input, ctx) {
+            const command = input.command;
+            if (typeof command !== "string" || command.trim() === "") {
+                return { content: '"command" must be a non-empty string', isError: true };
+            }
+            const requested = typeof input.timeoutMs === "number" && Number.isFinite(input.timeoutMs) ? input.timeoutMs : BASH_TIMEOUT_MS;
+            const timeoutMs = Math.min(Math.max(Math.trunc(requested), MIN_BASH_TIMEOUT_MS), BASH_TIMEOUT_MS);
+            try {
+                const { launched, stdout } = await launchIntercepted({ command, shell, opts, ctx, timeoutMs });
+                // Same framing ladder as RunCommand (Exec) via the shared
+                // `formatExecBody`: an aborted call opens with the cancellation line
+                // and surfaces whatever partial output the readers captured before the
+                // process group was SIGKILLed (AC14); an orphansKilled call appends the
+                // "[nax] background processes ..." footer so the model can tell that a
+                // `&`ed process held the pipe and was reaped (AC15). Both are
+                // independent of the regular `timed out` / `exit N` framing.
+                const body = formatExecBody({ ...launched, stdout }, timeoutMs);
+                // The tool's own bound is the I/O ceiling, not the model-facing cap:
+                // `maxBytes` shapes what the model is told and belongs to the session's
+                // truncation policy (which also spills what it cuts), while this one
+                // only keeps a runaway command from being buffered without limit. The
+                // full size still rides out on `resultBytesPreTruncation`.
+                return {
+                    content: cutToByteCap(body, ctx.readCeiling ?? READ_CEILING),
+                    isError: launched.timedOut || launched.exitCode !== 0 || launched.aborted === true,
+                    // The ledger records what actually ran, not what was requested.
+                    // `exitCode` is recorded only when nax did not kill the process
+                    // group: under `timedOut` or `aborted` the code is nax's own kill
+                    // (128+signal) or the -1 never-spawned sentinel, not the command's.
+                    // `orphansKilled` still records it -- the shell exited by itself and
+                    // only background processes holding the pipe were reaped afterward.
+                    audit: {
+                        executed: launched.executed,
+                        ...(launched.sandbox !== undefined ? { sandbox: launched.sandbox } : {}),
+                        ...(!launched.timedOut && launched.aborted !== true ? { exitCode: launched.exitCode } : {}),
+                    },
+                    resultBytesPreTruncation: Buffer.byteLength(body, "utf8"),
+                };
+            }
+            catch (err) {
+                // A spawn-time failure (an unresolvable cwd, a missing shell) rejects
+                // rather than resolving with an exit code; surfaced as an ordinary tool
+                // error so it is indistinguishable from any other refusal above.
+                return { content: err instanceof Error ? err.message : String(err), isError: true };
+            }
+        },
+    };
+}

package/dist/tools/delete.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Delete a file whose path the policy already resolved and approved.
+ *
+ * nax#1972: this used to be tracked-only, on the theory that a tracked
+ * file's content is in git history (an undo away) while an untracked file
+ * exists only on disk and is therefore unrecoverable. That rationale is
+ * retired -- it made the guard unsatisfiable for a file the agent itself
+ * wrote this session, which is untracked by construction. Paired with the
+ * #1937 denial redirect (Exec `rm` bounces back to Delete), the agent had no
+ * legal way to remove its own scratch output, and its fallback was to blank
+ * files to 0 bytes with Write -- which the auto-commit sweep then carried
+ * into history anyway. Refusing the deletion did not make anything more
+ * recoverable; it just moved the damage to a different tool.
+ *
+ * The new rule follows the three states git actually puts a path in:
+ *
+ *   - tracked                        -> allow (unchanged)
+ *   - untracked AND gitignored       -> refuse (unchanged verdict, new reason)
+ *   - untracked and NOT gitignored   -> allow (the fix)
+ *
+ * Both untracked classes are equally unrecoverable -- neither is in git
+ * history -- so recoverability alone no longer explains the split. What
+ * distinguishes them is declared intent. A gitignored path has a rule
+ * somebody wrote on purpose, saying "this lives only on this machine"
+ * (`.env`, `.nax-pids`, `.claude/settings.local.json`, the fragments and
+ * plan-log directories under `.nax` are real examples in this repo) --
+ * deleting it is
+ * unrecoverable AND was never meant to be sent anywhere else, so the refusal
+ * stays, but the message now says why instead of telling the agent to commit
+ * a file its own author chose to keep out of git. An untracked-and-not-
+ * ignored path has no such rule attached to it at all: nobody has said
+ * anything about it one way or the other. In practice that is agent scratch
+ * or work in progress, so it is allowed.
+ *
+ * Accepted cost: a genuine new source file the agent wrote and has not yet
+ * committed is untracked-and-not-ignored too, so this permission also makes
+ * IT deletable -- there is no signal in git alone that separates "my own
+ * throwaway probe" from "a real file I just haven't committed yet". That is
+ * deliberate, not an oversight: it is the same permission that lets an agent
+ * clean up after itself, and the completion-phase auto-commit sweep
+ * (`autoCommitIfDirty`, `src/utils/git.ts`) is the backstop if something
+ * real gets removed before it was staged.
+ *
+ * `.git/` never reaches this point at all -- `resolveWithin`
+ * (`src/tools/policy.ts`) excludes it for every path-bearing tool, so
+ * `ctx.resolvedPaths` cannot contain a `.git/` path in the first place
+ * (nax#1943). Re-checking it here would be exactly the per-tool
+ * re-remembering that issue exists to prevent.
+ *
+ * Not `git rm`: gitTool documents a deliberate read/write split, and `git rm`
+ * both deletes and stages, folding two capabilities into one call. Plain
+ * unlink plus the existing GitCommit keeps each seam doing one thing --
+ * `git add -- <deleted path>` stages a deletion, so no change to GitCommit is
+ * needed.
+ */
+import type { CodingTool } from "./registry.ts";
+export declare const deleteTool: CodingTool;