@nathapp/nax-agent 0.1.0

package/dist/tools/delete.js

@@ -0,0 +1,154 @@
+/**
+ * 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 { lstat, unlink } from "node:fs/promises";
+import { relative, resolve, sep } from "node:path";
+import { gitWithTimeout } from "#src/internal/git-exec";
+import { matchesDenyPaths } from "./deny-paths.js";
+const GIT_TIMEOUT_MS = 30_000;
+export const deleteTool = {
+    name: "Delete",
+    description: "Delete a file. A tracked file is always removable. An untracked file is removable unless it is gitignored -- a gitignored path was deliberately kept out of git, so removing it is unrecoverable and is refused. Directories are refused. The removal still has to be staged -- pass the same path to GitCommit afterwards.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "Path relative to the repository root" },
+        },
+        required: ["path"],
+    },
+    scope: { pathFields: ["path"] },
+    async run(input, ctx) {
+        if (ctx.resolvedPaths[0] === undefined)
+            return { content: "no path supplied", isError: true };
+        const shown = String(input.path);
+        // The policy uses a realpath to prove containment, which dereferences a
+        // symlink. Deletion must instead act on the requested directory entry: a
+        // tracked symlink is itself recoverable, while its target may be a
+        // different tracked file. The policy has already validated `shown`.
+        const target = resolve(ctx.root, shown);
+        // denyPaths (nax#1972) is a repo-authored narrowing of Delete, and is
+        // checked before anything else this function decides -- including
+        // existence -- because it is a blanket refusal on the path itself, not a
+        // judgment about the path's current state on disk.
+        //
+        // Matched against the CANONICAL entry, never the raw `input.path`. The
+        // policy resolves before it approves, so a denylist consulted on the
+        // caller's own spelling is a different parser than the one that granted
+        // the call -- and every alternate spelling of the same file ("./x",
+        // "x//y", "a/../x", an absolute path) walks straight past it. Deriving
+        // the relative form from `target` collapses all of them to one string.
+        // Deliberately NOT realpath: a symlink's entry is what Delete removes,
+        // and removing a link cannot destroy what it points at, so resolving
+        // through it would refuse deletions the denylist never meant to cover.
+        const denyCandidate = relative(ctx.root, target).split(sep).join("/");
+        if (matchesDenyPaths(denyCandidate, ctx.denyPaths)) {
+            return {
+                content: `"${shown}" matches this repository's denyPaths configuration, so Delete refuses it regardless of tracked status.`,
+                isError: true,
+            };
+        }
+        // Existence and directory come first so each refusal says the true thing.
+        // Tracked-first would report a mistyped path as "not tracked", which is
+        // technically true and diagnostically useless.
+        let isDirectory;
+        try {
+            isDirectory = (await lstat(target)).isDirectory();
+        }
+        catch {
+            return { content: `"${shown}" does not exist`, isError: true };
+        }
+        if (isDirectory) {
+            // Reachable, not defensive: `ls-files --error-unmatch` exits 0 for a
+            // directory holding tracked files, so "tracked" does not imply "file".
+            return { content: `"${shown}" is a directory; Delete removes one file at a time`, isError: true };
+        }
+        const tracked = await gitWithTimeout(["ls-files", "--error-unmatch", "--", target], ctx.root, GIT_TIMEOUT_MS);
+        if (tracked.exitCode !== 0) {
+            // Untracked. Whether it stays refused now turns on the SECOND git
+            // question -- gitignored or not -- rather than stopping here the way
+            // the tracked-only rule used to.
+            //
+            // `check-ignore` has three outcomes and they must NOT be collapsed into
+            // two: 0 means ignored, 1 means definitively not ignored, and anything
+            // else (128) means git could not answer -- no repository, or a broken
+            // one. Only the definitive 1 is an allow. Folding 128 in with 1 would
+            // make a repository-less directory the most permissive environment this
+            // tool has, which inverts the guard exactly where it is least
+            // observable. The pre-nax#1972 code refused "untracked" and "git
+            // failed" through one branch on purpose, and that caution survives the
+            // three-class rewrite even though its original rationale does not.
+            const ignored = await gitWithTimeout(["check-ignore", "-q", "--", target], ctx.root, GIT_TIMEOUT_MS);
+            if (ignored.exitCode === 0) {
+                return {
+                    content: `"${shown}" is gitignored, so it exists only on this machine and is not recoverable once deleted. Delete refuses it for that reason.`,
+                    isError: true,
+                };
+            }
+            if (ignored.exitCode !== 1) {
+                return {
+                    content: `"${shown}" is not tracked, and git could not determine whether it is ignored, so Delete cannot establish that removing it is safe. Check that this is a git repository.`,
+                    isError: true,
+                };
+            }
+        }
+        try {
+            await unlink(target);
+            return { content: `deleted ${shown} -- stage the removal by passing the same path to GitCommit` };
+        }
+        catch (err) {
+            return { content: err instanceof Error ? err.message : String(err), isError: true };
+        }
+    },
+};

package/dist/tools/denial-redirect.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Name the tool that serves the intent behind a denied call.
+ *
+ * `policy.ts` already names the granted argv FORMS, which is the right answer
+ * when the model wanted a different install. It is the wrong answer when the
+ * model wanted `git status`: across three runs, 8 of 32 denied argv calls were
+ * for capabilities the session already held as a first-class tool (nax#1937).
+ *
+ * Lives here rather than in policy.ts because the policy knows the grants but
+ * not which tools were ADVERTISED to this session. Naming a tool the session
+ * never received would reproduce the defect this exists to fix, so every row
+ * is gated on the caller's `available` set.
+ *
+ * ONE table answers both entry points. There used to be two -- one for argv
+ * command lines, one for bare verbs -- covering disjoint command sets, while
+ * `redirectForVerb` routed anything multi-token into the argv table. So which
+ * table answered depended on whether the model typed a flag, and coverage came
+ * out inverted: `ls -la` redirected but `ls` did not, `grep` redirected but
+ * `grep -n x y` did not. 20 of 34 denials in the two runs after #1971 carried
+ * no redirect (nax#1999). A single table cannot drift against itself.
+ */
+export declare function redirectForArgv(argv: readonly string[], available: ReadonlySet<string>, declaredCommands: ReadonlySet<string>): string | undefined;
+/**
+ * Name the tool that serves the intent behind a denied Bash COMMAND.
+ *
+ * Reads the first segment only: that is what the model reached for, and a
+ * later segment's intent is not what to teach when the call is refused. The
+ * split is deliberately its own crude one rather than the lexer's
+ * (`lexBashCommand`): a command REFUSED for an unanalysable construct must
+ * still get a redirect, and the lexer returns nothing to read in that case.
+ */
+export declare function redirectForCommand(command: string, available: ReadonlySet<string>, declaredCommands: ReadonlySet<string>): string | undefined;
+/**
+ * Name the tool that serves the intent behind a denied VERB call.
+ *
+ * `redirectForArgv` is unreachable for RunCommand and Git: they deny through
+ * `verbField`, where the policy sees no argv at all, so every such denial was a
+ * bare refusal (nax#1971). A verb slot carries either a mini command line the
+ * model stuffed there ("ls -la") or a bare word ("grep"); both are tokenized
+ * and answered by the same table, which is what keeps them consistent.
+ */
+export declare function redirectForVerb(deniedTool: string, verb: string, available: ReadonlySet<string>, declaredCommands: ReadonlySet<string>): string | undefined;

package/dist/tools/denial-redirect.js

@@ -0,0 +1,266 @@
+/**
+ * Name the tool that serves the intent behind a denied call.
+ *
+ * `policy.ts` already names the granted argv FORMS, which is the right answer
+ * when the model wanted a different install. It is the wrong answer when the
+ * model wanted `git status`: across three runs, 8 of 32 denied argv calls were
+ * for capabilities the session already held as a first-class tool (nax#1937).
+ *
+ * Lives here rather than in policy.ts because the policy knows the grants but
+ * not which tools were ADVERTISED to this session. Naming a tool the session
+ * never received would reproduce the defect this exists to fix, so every row
+ * is gated on the caller's `available` set.
+ *
+ * ONE table answers both entry points. There used to be two -- one for argv
+ * command lines, one for bare verbs -- covering disjoint command sets, while
+ * `redirectForVerb` routed anything multi-token into the argv table. So which
+ * table answered depended on whether the model typed a flag, and coverage came
+ * out inverted: `ls -la` redirected but `ls` did not, `grep` redirected but
+ * `grep -n x y` did not. 20 of 34 denials in the two runs after #1971 carried
+ * no redirect (nax#1999). A single table cannot drift against itself.
+ */
+const GIT_READ_VERBS = new Set(["diff", "log", "show", "status", "blame"]);
+/**
+ * Git verbs that stage or record a commit. Deliberately NOT every write verb:
+ * `git restore` reverts, which `GitCommit` does not do, and naming it would be
+ * the same defect as naming a tool the session never received.
+ */
+const GIT_COMMIT_VERBS = new Set(["add", "commit"]);
+/**
+ * Git verbs that revert tracked paths. Checked separately from the intent
+ * table: when the paths are nax's own `.nax/` run state, no tool serves the
+ * intent, so the refusal teaches instead of naming one (nax#2007).
+ */
+const GIT_REVERT_VERBS = new Set(["checkout", "restore"]);
+const NAX_OWNED_RUN_STATE_EXPLANATION = "`.nax/` is nax's own run state, written by the harness during this run. It is not part of your diff and must not be reverted.";
+/**
+ * The sentence explaining a revert of nax's own run state, or undefined.
+ *
+ * Deliberately NOT an `Intent`: `render()` wraps every hit as "this session
+ * already has `X`", which is false here -- no tool reverts `.nax/`, and the
+ * module's header forbids naming one it does not hold. So this predicate is
+ * checked BEFORE `intentFor` in both entry points and returns its own sentence.
+ *
+ * Verb scope is `checkout` and `restore` only; `git stash` is the agent's own
+ * WIP, not nax's state, and has no operands to gate on. The gate is a `.nax`
+ * path SEGMENT (split on `/`), never a substring, so `src/nax-helpers.ts` and
+ * `docs/.naxignore` stay unanswered. `--` is a separator, not an operand, and a
+ * `timeout N` wrapper is stripped the same way `intentFor` strips it.
+ */
+function naxOwnedRunStateExplanation(tokens) {
+    const av = withoutTimeoutPrefix(tokens);
+    const hasGitPrefix = av[0] === "git";
+    const verb = hasGitPrefix ? av[1] : av[0];
+    if (verb === undefined || !GIT_REVERT_VERBS.has(verb))
+        return undefined;
+    for (const operand of av.slice(hasGitPrefix ? 2 : 1)) {
+        if (operand === "--")
+            continue;
+        if (operand.split("/").includes(".nax"))
+            return NAX_OWNED_RUN_STATE_EXPLANATION;
+    }
+    return undefined;
+}
+const GLOB = { tool: "Glob", how: "Glob lists repository paths by pattern" };
+const GREP = { tool: "Grep", how: "Grep searches file contents" };
+const READ = { tool: "Read", how: "Read returns file contents, by line range with offset/limit" };
+const DELETE = { tool: "Delete", how: "Delete removes one tracked file at a time" };
+const GIT = { tool: "Git", how: `Git runs read-only git (${[...GIT_READ_VERBS].join(", ")})` };
+const GIT_COMMIT = {
+    tool: "GitCommit",
+    how: "GitCommit stages and commits named files -- supply `message` and a `paths` array",
+};
+const TEST_SCOPED = {
+    tool: "RunCommand:testScoped",
+    how: 'RunCommand {"command":"testScoped"} runs the project test command on named files',
+};
+const BASH = {
+    tool: "Bash",
+    how: "Bash runs one shell command string, when a Bash(...) allow rule covers every segment of it",
+};
+/**
+ * Commands whose intent the HEAD token alone decides.
+ *
+ * `rm` and `git` are absent on purpose: their intent is decided by the SECOND
+ * token (`rm a.ts` is a Delete, `rm -r dir` is nothing Delete can do; `git log`
+ * is Git, `git add` is GitCommit), so they are resolved by shape below.
+ */
+const HEAD_INTENTS = new Map([
+    ["ls", GLOB],
+    ["find", GLOB],
+    ["grep", GREP],
+    ["cat", READ],
+    ["bash", BASH],
+    ["sh", BASH],
+    ["zsh", BASH],
+    // No tool counts lines, and Read with no offset/limit returns a byte-bounded
+    // PREFIX -- so counting what it returns under-reports exactly the large files
+    // the question gets asked about. Naming Read beats a bare refusal the model
+    // retries verbatim, but only if the ceiling is stated rather than implied.
+    ["wc", { tool: "Read", how: "Read returns file contents, truncated past a size ceiling -- no tool counts lines" }],
+    // nax-git-env-allow: a [command, redirect] table entry, not an argv
+    ["git", GIT],
+    ...[...GIT_READ_VERBS].map((verb) => [verb, GIT]),
+    // `git.ts` declares `allowedVerbs: GIT_READ_VERBS`, so every Git verb-slot
+    // denial carries a write verb and arrives BARE -- `commit`, never
+    // `git commit`. Reaching these only through the shape branch below would
+    // leave the row unreachable from the one slot Git denials come through.
+    // Safe as head tokens: `add` is an install verb only in TASK_RUNNERS
+    // position (`bun add`), where the head is the runner, not `add`.
+    ...[...GIT_COMMIT_VERBS].map((verb) => [verb, GIT_COMMIT]),
+]);
+/** Task-runner binaries. A detection heuristic ONLY: what gets named comes
+ * entirely from the project's declared commands, never from this list. A runner
+ * missing here degrades to the pre-#1971 message rather than to a wrong one.
+ */
+const TASK_RUNNERS = new Set([
+    "bun",
+    "npm",
+    "pnpm",
+    "yarn",
+    "deno",
+    "npx",
+    "make",
+    "just",
+    "task",
+    "go",
+    "cargo",
+    "uv",
+    "poetry",
+    "pipenv",
+    "tox",
+    "gradle",
+    "mvn",
+]);
+/**
+ * Install subcommands. These runners double as package managers, and an install
+ * attempt wants the granted install FORMS policy.ts already printed -- not a
+ * list of project gates that cannot install anything.
+ */
+const INSTALL_VERBS = new Set(["add", "install", "i", "ci", "get", "sync", "fetch", "mod", "download"]);
+function isSingleFileDelete(tokens, from) {
+    return tokens.length === from + 1 && !tokens[from]?.startsWith("-");
+}
+/** A `timeout N ...` prefix wraps the real command; look past it. */
+function withoutTimeoutPrefix(tokens) {
+    return tokens[0] === "timeout" ? tokens.slice(2) : tokens;
+}
+/**
+ * The one intent table. Shape-dependent heads are resolved first, then the
+ * head-only map -- so a bare verb and the same verb with arguments can never
+ * be answered differently.
+ */
+function intentFor(tokens) {
+    const av = withoutTimeoutPrefix(tokens);
+    const [head, second] = av;
+    if (head === undefined)
+        return undefined;
+    if (head === "rm")
+        return isSingleFileDelete(av, 1) ? DELETE : undefined;
+    if (head === "git" && second !== undefined) {
+        if (second === "rm")
+            return isSingleFileDelete(av, 2) ? DELETE : undefined;
+        if (GIT_READ_VERBS.has(second))
+            return GIT;
+        if (GIT_COMMIT_VERBS.has(second))
+            return GIT_COMMIT;
+        return undefined;
+    }
+    if (head === "bun" && second === "test")
+        return TEST_SCOPED;
+    return HEAD_INTENTS.get(head);
+}
+/**
+ * Name the gates this project declared, for a model that reached for a task
+ * runner and wanted to run one of them. What gets named comes from the
+ * project's declared commands, never from a hardcoded list (nax#1971).
+ */
+function taskRunnerFallback(tokens, available, declaredCommands) {
+    const av = withoutTimeoutPrefix(tokens);
+    const head = av[0];
+    if (head === undefined || !TASK_RUNNERS.has(head))
+        return undefined;
+    const sub = av[1];
+    if (sub !== undefined && INSTALL_VERBS.has(sub))
+        return undefined;
+    if (!available.has("RunCommand") || declaredCommands.size === 0)
+        return undefined;
+    return `this session already has RunCommand with declared commands: ${[...declaredCommands].join(", ")}`;
+}
+function render(hit, available, declaredCommands) {
+    if (hit.tool === TEST_SCOPED.tool) {
+        // Conditioned on the project actually declaring the command, not hardcoded:
+        // naming a command this project never declared is the same defect again.
+        if (!available.has("RunCommand") || !declaredCommands.has("testScoped"))
+            return undefined;
+        return `this session already has ${hit.how}`;
+    }
+    if (!available.has(hit.tool))
+        return undefined;
+    return `this session already has \`${hit.tool}\` -- ${hit.how}`;
+}
+export function redirectForArgv(argv, available, declaredCommands) {
+    const ownedRunState = naxOwnedRunStateExplanation(argv);
+    if (ownedRunState !== undefined)
+        return ownedRunState;
+    const hit = intentFor(argv);
+    if (hit === undefined)
+        return taskRunnerFallback(argv, available, declaredCommands);
+    return render(hit, available, declaredCommands);
+}
+/**
+ * Name the tool that serves the intent behind a denied Bash COMMAND.
+ *
+ * Reads the first segment only: that is what the model reached for, and a
+ * later segment's intent is not what to teach when the call is refused. The
+ * split is deliberately its own crude one rather than the lexer's
+ * (`lexBashCommand`): a command REFUSED for an unanalysable construct must
+ * still get a redirect, and the lexer returns nothing to read in that case.
+ */
+export function redirectForCommand(command, available, declaredCommands) {
+    const [first = ""] = command.split(/&&|\|\||;|\||\n/);
+    const tokens = first
+        .trim()
+        .split(/\s+/)
+        .filter((token) => token.length > 0);
+    if (tokens.length === 0)
+        return undefined;
+    const ownedRunState = naxOwnedRunStateExplanation(tokens);
+    if (ownedRunState !== undefined)
+        return ownedRunState;
+    const hit = intentFor(tokens);
+    if (hit === undefined)
+        return taskRunnerFallback(tokens, available, declaredCommands);
+    // Telling Bash it already has Bash reads as a contradiction of the denial —
+    // the same suppression redirectForVerb applies.
+    if (hit.tool === "Bash")
+        return undefined;
+    return render(hit, available, declaredCommands);
+}
+/**
+ * Name the tool that serves the intent behind a denied VERB call.
+ *
+ * `redirectForArgv` is unreachable for RunCommand and Git: they deny through
+ * `verbField`, where the policy sees no argv at all, so every such denial was a
+ * bare refusal (nax#1971). A verb slot carries either a mini command line the
+ * model stuffed there ("ls -la") or a bare word ("grep"); both are tokenized
+ * and answered by the same table, which is what keeps them consistent.
+ */
+export function redirectForVerb(deniedTool, verb, available, declaredCommands) {
+    const tokens = verb
+        .trim()
+        .split(/\s+/)
+        .filter((token) => token.length > 0);
+    if (tokens.length === 0)
+        return undefined;
+    const ownedRunState = naxOwnedRunStateExplanation(tokens);
+    if (ownedRunState !== undefined)
+        return ownedRunState;
+    const hit = intentFor(tokens);
+    if (hit === undefined)
+        return taskRunnerFallback(tokens, available, declaredCommands);
+    // Telling Git it already has Git reads as a contradiction of the denial.
+    if (hit.tool === deniedTool)
+        return undefined;
+    return render(hit, available, declaredCommands);
+}

package/dist/tools/deny-paths.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Match a Delete candidate against the repo-configurable `denyPaths`
+ * denylist (nax#1972, `execution.denyPaths` in config).
+ *
+ * A separate file rather than an addition to src/tools/policy.ts on purpose:
+ * that file already carries the containment seam and is close to the
+ * project's file-size ratchet, and denyPaths is a narrower, single-tool
+ * concern -- it has nothing to do with resolving or containing a path, only
+ * with refusing one the policy already approved.
+ *
+ * The glob syntax deliberately matches globToRegExp in policy.ts (`**` spans
+ * separators, `*` does not) so a `denyPaths` entry reads the same way a
+ * ToolGrant pattern does elsewhere in config -- one mental model for "what
+ * does a glob mean in nax config", not two subtly different ones. The
+ * implementation is a small, independent copy rather than an export from
+ * policy.ts: that keeps this file free to be read (and reasoned about) on
+ * its own, and keeps policy.ts's containment logic untouched by a change
+ * that has nothing to do with containment.
+ */
+/**
+ * Does `relativePath` match any pattern in `denyPaths`?
+ *
+ * `relativePath` MUST already be canonical and repo-relative -- the caller
+ * derives it from the resolved entry, never from `input.path`. This is not a
+ * stylistic preference: matching the caller's own spelling means the denylist
+ * and the policy that approved the call are reading different strings, and
+ * every alternate spelling of one file ("./x", "x//y", "a/../x") walks past
+ * the denylist (nax#1972, reproduced). Repo-relative rather than absolute so
+ * a pattern is rooted at the repo, not at the filesystem.
+ *
+ * Both sides are NFC-normalized before comparison. macOS stores filenames
+ * decomposed (NFD), so a pattern typed in a config file and the path that
+ * comes back off disk can be byte-different while naming one file.
+ */
+export declare function matchesDenyPaths(relativePath: string, denyPaths: readonly string[] | undefined): boolean;

package/dist/tools/deny-paths.js

@@ -0,0 +1,76 @@
+/**
+ * Match a Delete candidate against the repo-configurable `denyPaths`
+ * denylist (nax#1972, `execution.denyPaths` in config).
+ *
+ * A separate file rather than an addition to src/tools/policy.ts on purpose:
+ * that file already carries the containment seam and is close to the
+ * project's file-size ratchet, and denyPaths is a narrower, single-tool
+ * concern -- it has nothing to do with resolving or containing a path, only
+ * with refusing one the policy already approved.
+ *
+ * The glob syntax deliberately matches globToRegExp in policy.ts (`**` spans
+ * separators, `*` does not) so a `denyPaths` entry reads the same way a
+ * ToolGrant pattern does elsewhere in config -- one mental model for "what
+ * does a glob mean in nax config", not two subtly different ones. The
+ * implementation is a small, independent copy rather than an export from
+ * policy.ts: that keeps this file free to be read (and reasoned about) on
+ * its own, and keeps policy.ts's containment logic untouched by a change
+ * that has nothing to do with containment.
+ */
+function globToRegExp(pattern) {
+    let out = "";
+    for (let i = 0; i < pattern.length; i += 1) {
+        const char = pattern[i];
+        if (char === "*") {
+            if (pattern[i + 1] === "*") {
+                i += 1;
+                if (pattern[i + 1] === "/") {
+                    out += "(?:.*/)?";
+                    i += 1;
+                }
+                else {
+                    out += ".*";
+                }
+            }
+            else {
+                out += "[^/]*";
+            }
+            continue;
+        }
+        if (char === "?") {
+            out += "[^/]";
+            continue;
+        }
+        out += char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+    // Case-insensitive, and both sides NFC-normalized at the call site.
+    // macOS and Windows default to case-insensitive filesystems, where ".ENV"
+    // and ".env" are one file -- a case-sensitive compare there lets a denied
+    // path be deleted by respelling it (nax#1972, reproduced). Applying the
+    // flag unconditionally rather than probing the filesystem keeps the rule
+    // one predictable thing: on a case-sensitive filesystem this over-refuses
+    // a genuinely distinct ".ENV", which is the direction a denylist should
+    // fail in.
+    return new RegExp(`^${out}$`, "i");
+}
+/**
+ * Does `relativePath` match any pattern in `denyPaths`?
+ *
+ * `relativePath` MUST already be canonical and repo-relative -- the caller
+ * derives it from the resolved entry, never from `input.path`. This is not a
+ * stylistic preference: matching the caller's own spelling means the denylist
+ * and the policy that approved the call are reading different strings, and
+ * every alternate spelling of one file ("./x", "x//y", "a/../x") walks past
+ * the denylist (nax#1972, reproduced). Repo-relative rather than absolute so
+ * a pattern is rooted at the repo, not at the filesystem.
+ *
+ * Both sides are NFC-normalized before comparison. macOS stores filenames
+ * decomposed (NFD), so a pattern typed in a config file and the path that
+ * comes back off disk can be byte-different while naming one file.
+ */
+export function matchesDenyPaths(relativePath, denyPaths) {
+    if (denyPaths === undefined || denyPaths.length === 0)
+        return false;
+    const candidate = relativePath.normalize("NFC");
+    return denyPaths.some((pattern) => globToRegExp(pattern.normalize("NFC")).test(candidate));
+}

package/dist/tools/edit-region.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Edit's literal replacement (US-001).
+ *
+ * `String.prototype.replace` reads a string replacement as a template and
+ * expands `$$`, `$&`, `` $` `` and `$'` inside it, so
+ * `source.replace(oldString, newString)` writes something other than the
+ * characters the model supplied whenever `new_string` contains one of those
+ * patterns — `"a".replace("a", "x$$y$&z")` returns `x$yaz`. Composing the
+ * result by hand keeps every character literal.
+ *
+ * File-local on purpose, matching `src/tools/read-continuation.ts`: the
+ * helper is a property of the `Edit` composition, nothing else composes it,
+ * and `src/tools` does not export it from its barrel — `edit.ts` imports it
+ * by relative path.
+ *
+ * US-002 extends the module with `composeEditRegion`, the bounded
+ * Read-compatible view of the region an Edit just wrote: the `[lines a-b of
+ * N]` header and the selected lines, with elision when the replacement spans
+ * more than `MAX_REGION_LINES_SHOWN` lines. Deterministic string composition
+ * — no LLM, no config, no new tool arguments.
+ */
+/**
+ * Inputs to `composeEditRegion`.
+ *
+ * `matchIndex` is the offset `source.indexOf(oldString)` found — the caller
+ * wrote the new text there, so `updated.slice(0, matchIndex)` is identical to
+ * the source prefix and the start line can be counted on either.
+ */
+export interface EditRegionInput {
+    readonly updated: string;
+    readonly matchIndex: number;
+    readonly newStringLength: number;
+}
+/**
+ * The bounded, Read-compatible view of the region an Edit wrote: a
+ * `[lines a-b of N]` header and the selected lines, or `[file is now empty]`
+ * for an emptied file. Has no trailing newline, and cannot throw on any
+ * string input.
+ */
+export declare function composeEditRegion({ updated, matchIndex, newStringLength }: EditRegionInput): string;
+/**
+ * Replace the single occurrence of `oldString` at `matchIndex` with
+ * `newString`, literally.
+ *
+ * The caller has already established uniqueness (`countOccurrences` in
+ * `edit.ts`) and passes the index `source.indexOf(oldString)` found, so this
+ * is pure slicing: everything before the match, the new text verbatim, and
+ * everything after it. No `replace`, and therefore no substitution patterns.
+ */
+export declare function replaceUniqueLiteral(source: string, oldString: string, newString: string, matchIndex: number): string;