@nathapp/nax-agent 0.1.0

package/dist/tools/policy-match.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Pattern compilation for the tool policy: globs, argv tokens, and the
+ * deny/ask rule maps.
+ *
+ * Extracted from `policy.ts` to keep that file under the 600-line source
+ * limit. `src/` reaches this module only through `policy.ts`, so the barrel
+ * surface is unchanged; tests may import it directly.
+ */
+import type { ToolGrant } from "./types.ts";
+/**
+ * Minimatch-style glob to RegExp: `**` spans separators, `*` does not.
+ *
+ * `**` followed by `/` is zero or more COMPLETE directory segments, which is
+ * why it does not simply compile to `.*`. `.*` both spans separators and
+ * matches the empty string, so emitting it and dropping the separator erased
+ * the boundary: `src/**\/config.ts` became `^src\/.*config\.ts$`, and a grant
+ * for files named `config.ts` also admitted `src/legacyconfig.ts`.
+ *
+ * That was never a root escape -- containment runs before any pattern matching
+ * -- but it made a *scoped* grant wider than its author wrote, which is the one
+ * thing a scoped profile exists to prevent.
+ */
+export declare function globToRegExp(pattern: string): RegExp;
+/** A compiled glob, keeping its source so verb names can be told from paths. */
+export interface CompiledPattern {
+    readonly source: string;
+    readonly re: RegExp;
+}
+/**
+ * A deny/ask rule list compiled for one tool.
+ *
+ * Unlike the allow compiler (last-write-wins per tool, by design),
+ * rules for the same tool MERGE here: patterns are concatenated and any
+ * `"*"` makes the whole entry unconditional. That is safe -- and correct --
+ * because deny/ask are additive; a later rule must never silently drop an
+ * earlier one.
+ */
+export interface CompiledEntry {
+    readonly unconditional: boolean;
+    readonly matchers: CompiledPattern[];
+    readonly argvPatterns: readonly (readonly CompiledPattern[])[];
+    readonly raw: readonly string[];
+    /** Patterns grouped by their original rule expression for ask telemetry. */
+    readonly rulePatterns?: readonly (readonly string[])[];
+}
+export declare function matchesAny(patterns: readonly CompiledPattern[], value: string): boolean;
+/** The source of the first compiled glob matching `value`, for naming a rule. */
+export declare function matchedGlobSource(patterns: readonly CompiledPattern[], value: string): string | undefined;
+/**
+ * Split a grant pattern into whitespace-separated tokens, each compiled
+ * independently. Per-token compilation (rather than joining argv with
+ * spaces and matching one regex against the joined string) is deliberate:
+ * a joined string lets a value containing spaces or glob metacharacters
+ * shift what a later token appears to match. `"bun add*"` must mean "argv[0]
+ * is exactly bun, argv[1] starts with add", never "the space-joined argv
+ * matches this glob".
+ */
+export declare function compileArgvPattern(pattern: string): readonly CompiledPattern[];
+/** A grant pattern's tokens are a PREFIX of argv — trailing argv tokens
+ * (the package name, flags, ...) are the payload a prefix grant like
+ * `bun add*` does not itself constrain. */
+export declare function matchesArgvPattern(tokens: readonly CompiledPattern[], argv: readonly string[]): boolean;
+export declare function matchesArgvGrant(argvPatterns: readonly (readonly CompiledPattern[])[], argv: readonly string[]): boolean;
+/**
+ * Compile a deny/ask list. Deliberately separate from the allow compiler: the
+ * allow map overwrites, and unifying the two would change verdicts for any
+ * config carrying two expressions for one tool (the byte-identity regression
+ * gate pins that). Merging is safe for deny/ask because those lists are new
+ * and additive.
+ */
+export declare function compileRuleMap(rules: readonly ToolGrant[] | undefined): Map<string, CompiledEntry>;
+/** The configured expression-group containing a matched pattern, if any. */
+export declare function matchedRulePatterns(entry: CompiledEntry, source: string): readonly string[];
+/** The original pattern whose tokens matched `argv`, for naming an ask rule. */
+export declare function matchedArgvSource(entry: CompiledEntry, argv: readonly string[]): string | undefined;

package/dist/tools/policy-match.js

@@ -0,0 +1,117 @@
+/**
+ * Pattern compilation for the tool policy: globs, argv tokens, and the
+ * deny/ask rule maps.
+ *
+ * Extracted from `policy.ts` to keep that file under the 600-line source
+ * limit. `src/` reaches this module only through `policy.ts`, so the barrel
+ * surface is unchanged; tests may import it directly.
+ */
+/**
+ * Minimatch-style glob to RegExp: `**` spans separators, `*` does not.
+ *
+ * `**` followed by `/` is zero or more COMPLETE directory segments, which is
+ * why it does not simply compile to `.*`. `.*` both spans separators and
+ * matches the empty string, so emitting it and dropping the separator erased
+ * the boundary: `src/**\/config.ts` became `^src\/.*config\.ts$`, and a grant
+ * for files named `config.ts` also admitted `src/legacyconfig.ts`.
+ *
+ * That was never a root escape -- containment runs before any pattern matching
+ * -- but it made a *scoped* grant wider than its author wrote, which is the one
+ * thing a scoped profile exists to prevent.
+ */
+export 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] === "/") {
+                    // Optional, so `x/**/y` still matches `x/y` -- minimatch's behaviour.
+                    out += "(?:.*/)?";
+                    i += 1;
+                }
+                else {
+                    out += ".*";
+                }
+            }
+            else {
+                out += "[^/]*";
+            }
+            continue;
+        }
+        if (char === "?") {
+            out += "[^/]";
+            continue;
+        }
+        out += char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+    return new RegExp(`^${out}$`);
+}
+export function matchesAny(patterns, value) {
+    return patterns.some((p) => p.re.test(value));
+}
+/** The source of the first compiled glob matching `value`, for naming a rule. */
+export function matchedGlobSource(patterns, value) {
+    return patterns.find((p) => p.re.test(value))?.source;
+}
+/**
+ * Split a grant pattern into whitespace-separated tokens, each compiled
+ * independently. Per-token compilation (rather than joining argv with
+ * spaces and matching one regex against the joined string) is deliberate:
+ * a joined string lets a value containing spaces or glob metacharacters
+ * shift what a later token appears to match. `"bun add*"` must mean "argv[0]
+ * is exactly bun, argv[1] starts with add", never "the space-joined argv
+ * matches this glob".
+ */
+export function compileArgvPattern(pattern) {
+    return pattern
+        .split(/\s+/)
+        .filter((token) => token.length > 0)
+        .map((token) => ({ source: token, re: globToRegExp(token) }));
+}
+/** A grant pattern's tokens are a PREFIX of argv — trailing argv tokens
+ * (the package name, flags, ...) are the payload a prefix grant like
+ * `bun add*` does not itself constrain. */
+export function matchesArgvPattern(tokens, argv) {
+    if (tokens.length > argv.length)
+        return false;
+    return tokens.every((token, i) => token.re.test(argv[i]));
+}
+export function matchesArgvGrant(argvPatterns, argv) {
+    return argvPatterns.some((tokens) => matchesArgvPattern(tokens, argv));
+}
+/**
+ * Compile a deny/ask list. Deliberately separate from the allow compiler: the
+ * allow map overwrites, and unifying the two would change verdicts for any
+ * config carrying two expressions for one tool (the byte-identity regression
+ * gate pins that). Merging is safe for deny/ask because those lists are new
+ * and additive.
+ */
+export function compileRuleMap(rules) {
+    const map = new Map();
+    for (const rule of rules ?? []) {
+        const existing = map.get(rule.tool);
+        const patterns = existing === undefined ? rule.patterns : [...existing.raw, ...rule.patterns];
+        const nonWildcard = patterns.filter((p) => p !== "*");
+        map.set(rule.tool, {
+            unconditional: patterns.includes("*"),
+            matchers: nonWildcard.map((source) => ({ source, re: globToRegExp(source) })),
+            argvPatterns: nonWildcard.map((source) => compileArgvPattern(source)),
+            raw: patterns,
+            rulePatterns: [...(existing?.rulePatterns ?? []), rule.patterns],
+        });
+    }
+    return map;
+}
+/** The configured expression-group containing a matched pattern, if any. */
+export function matchedRulePatterns(entry, source) {
+    return entry.rulePatterns?.find((patterns) => patterns.includes(source)) ?? entry.raw;
+}
+/** The original pattern whose tokens matched `argv`, for naming an ask rule. */
+export function matchedArgvSource(entry, argv) {
+    const index = entry.argvPatterns.findIndex((tokens) => matchesArgvPattern(tokens, argv));
+    if (index === -1)
+        return undefined;
+    return entry.raw.filter((p) => p !== "*")[index];
+}

package/dist/tools/policy-paths-branch.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The policy's path branch: containment first, then deny -> ask -> allow per
+ * resolved path, across the four kinds of path-bearing input field.
+ *
+ * Split out of `policy.ts` (cognitive-complexity drain A8). Each field kind is
+ * its own named handler, and the per-path sequence all four share — resolve,
+ * refuse containment breaches, apply rules, glob-check, record — is one helper
+ * whose arguments name the only things that differ between the loops: the
+ * denial's subject spelling, and whether a glob miss denies.
+ *
+ * Behavioural shape worth naming because the handlers must not be "unified":
+ * `pathFields` and `listPathFields` deny on a glob miss whenever the grant is
+ * conditional (`enforcePathGlobs`), while `arrayPathFields` and `refPathFields`
+ * deny only when the grant is conditional AND carries at least one path glob
+ * (`restrictPaths`). A verb-only grant therefore DENIES string path fields but
+ * leaves array/ref paths bounded by the root alone — pinned by `policy.test.ts`
+ * ("a verb-only grant leaves paths bounded by the root alone") and
+ * `policy-paths-branch-edges.test.ts`.
+ *
+ * Everything here is reached through `policy.ts`; this module imports nothing
+ * from it (the collaborators it shares — deny, askVerdict, applyPathRules —
+ * arrive by reference in `PathsBranchContext`, read at call time).
+ */
+import { type CompiledEntry } from "./policy-match.ts";
+import type { PolicyVerdict, ToolScope } from "./types.ts";
+/** Mutable scratch shared by `check()`'s branch helpers: first ask rule matched. */
+export interface RuleState {
+    ask?: string;
+}
+/**
+ * Per-policy collaborators the path branch shares with the rest of the policy.
+ * Passed by reference; every member is read at call time, so a caller that
+ * rebuilds or reassigns between checks stays authoritative.
+ */
+export interface PathsBranchContext {
+    /** The policy's containment root, symlink-resolved at compile time. */
+    readonly resolvedRoot: string;
+    readonly deny: (reason: string, breach?: boolean, escalatable?: boolean) => PolicyVerdict;
+    readonly askVerdict: (resolvedPaths: readonly string[], rule: string) => PolicyVerdict;
+    readonly applyPathRules: (tool: string, rel: string, state: RuleState) => PolicyVerdict | undefined;
+}
+/**
+ * Absolute, symlink-resolved form of `candidate` if it lies inside `root`,
+ * is not itself (and does not lie under) `.git/`, and is not one of nax's own
+ * config files.
+ *
+ * The single containment seam. Multi-root support (a future configurable
+ * extension) changes this function and nothing else, which is why every tool
+ * receives an already-resolved path rather than resolving one itself. The
+ * `.git/` exclusion lives here for the same reason: it applies to every
+ * path-bearing tool uniformly, reads included, rather than being
+ * re-remembered per tool -- which is exactly the failure mode a declaration
+ * on `ToolScope` would reintroduce (nax#1943). `.git/` sits INSIDE the root,
+ * so containment alone never bars it, and an unconditional ("*") grant --
+ * what every non-Exec tool gets under the default `unrestricted` profile --
+ * skips glob matching entirely, so nothing downstream of this function would
+ * catch it either.
+ *
+ * Pre-single-frame, this seam carried one exception: an `execTouchedPaths` set
+ * (Task 10) admitted a workspace install's repo-ROOT manifest/lockfile even
+ * though it sat outside the containment root, which was then the story's
+ * package dir. The root move made the containment root the repo root, so the
+ * manifest is in-root by construction and that carve-out was retired
+ * (PR2/Task 13). There is no exception to this seam now.
+ */
+export declare function resolveWithin(root: string, candidate: string): string | null;
+/**
+ * Containment runs before any pattern matching and wins over everything.
+ * Each resolved path is then evaluated deny -> ask -> allow. A verb-only
+ * grant declares no path globs, leaving the root as the only bound --
+ * unchanged behaviour, now an authoring choice rather than something the
+ * grant syntax could not express.
+ *
+ * `confineTo` (tool-declared, see `ToolScope`) shifts the root passed to
+ * `resolveWithin` from `<root>` to `<root>/<confineTo>`: containment stays
+ * the one seam, and only its ROOT changes. `relativeTo` keeps rooting at
+ * `resolvedRoot` so grant globs, deny rules and `naxOwnedWriteRefusal`
+ * continue to see the canonical repo-root-relative spelling -- authors
+ * write `.nax/scratchpad/**`, never `**`, regardless of `confineTo`.
+ *
+ * `confineTo` is bound to stay INSIDE `resolvedRoot`: an authoring typo of
+ * `..` or `../shared` would otherwise widen the containment root past the
+ * policy boundary and re-scope `resolveWithin`'s `.git/`-metadata and
+ * `isNaxConfigFile` protections to a root that no longer aligns with the
+ * segments those checks assume -- the repo's own `.nax/config.json` would
+ stop being segment-matched against `.nax`. The boundary is the policy
+ root's invariant, so an out-of-root confineTo refuses the call outright
+ rather than silently widening.
+ */
+export declare function pathsBranch(args: {
+    readonly ctx: PathsBranchContext;
+    readonly tool: string;
+    readonly scope: ToolScope;
+    readonly input: Record<string, unknown>;
+    readonly grant: CompiledEntry;
+    readonly state: RuleState;
+}): PolicyVerdict;

package/dist/tools/policy-paths-branch.js

@@ -0,0 +1,314 @@
+/**
+ * The policy's path branch: containment first, then deny -> ask -> allow per
+ * resolved path, across the four kinds of path-bearing input field.
+ *
+ * Split out of `policy.ts` (cognitive-complexity drain A8). Each field kind is
+ * its own named handler, and the per-path sequence all four share — resolve,
+ * refuse containment breaches, apply rules, glob-check, record — is one helper
+ * whose arguments name the only things that differ between the loops: the
+ * denial's subject spelling, and whether a glob miss denies.
+ *
+ * Behavioural shape worth naming because the handlers must not be "unified":
+ * `pathFields` and `listPathFields` deny on a glob miss whenever the grant is
+ * conditional (`enforcePathGlobs`), while `arrayPathFields` and `refPathFields`
+ * deny only when the grant is conditional AND carries at least one path glob
+ * (`restrictPaths`). A verb-only grant therefore DENIES string path fields but
+ * leaves array/ref paths bounded by the root alone — pinned by `policy.test.ts`
+ * ("a verb-only grant leaves paths bounded by the root alone") and
+ * `policy-paths-branch-edges.test.ts`.
+ *
+ * Everything here is reached through `policy.ts`; this module imports nothing
+ * from it (the collaborators it shares — deny, askVerdict, applyPathRules —
+ * arrive by reference in `PathsBranchContext`, read at call time).
+ */
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { isInside, realOrRaw } from "#src/internal/realpath";
+import { isNaxConfigFile } from "./nax-owned-writes.js";
+import { pathListElements } from "./path-list.js";
+import { pathFieldValue } from "./policy-input.js";
+import { matchesAny } from "./policy-match.js";
+/**
+ * Does `resolved` (already absolute and symlink-resolved) enter a `.git`
+ * directory anywhere along its path relative to `root`?
+ *
+ * A path-SEGMENT match, never a prefix or substring one: `.gitignore` and
+ * `.github/` are ordinary tracked names a tool must still be able to reach,
+ * and `startsWith(".git")` would wrongly swallow both -- the exact defect
+ * this function exists to avoid (nax#1943).
+ *
+ * Matches ANY segment, not only a leading one. A nested repository or a
+ * submodule checked into the tree (`vendor/some-lib/.git`, which may be a
+ * directory or, for a submodule, a file pointing at the real gitdir
+ * elsewhere) carries the same integrity and containment risk `.git/` at the
+ * root does -- the ruling behind this function is "no path-bearing tool ever
+ * addresses git metadata", not "only the top-level repository's".
+ */
+function entersGitMetadata(root, resolved) {
+    const rel = relative(realOrRaw(root), resolved);
+    if (rel === "" || rel.startsWith(".."))
+        return false;
+    return rel.split(sep).includes(".git");
+}
+/**
+ * Absolute, symlink-resolved form of `candidate` if it lies inside `root`,
+ * is not itself (and does not lie under) `.git/`, and is not one of nax's own
+ * config files.
+ *
+ * The single containment seam. Multi-root support (a future configurable
+ * extension) changes this function and nothing else, which is why every tool
+ * receives an already-resolved path rather than resolving one itself. The
+ * `.git/` exclusion lives here for the same reason: it applies to every
+ * path-bearing tool uniformly, reads included, rather than being
+ * re-remembered per tool -- which is exactly the failure mode a declaration
+ * on `ToolScope` would reintroduce (nax#1943). `.git/` sits INSIDE the root,
+ * so containment alone never bars it, and an unconditional ("*") grant --
+ * what every non-Exec tool gets under the default `unrestricted` profile --
+ * skips glob matching entirely, so nothing downstream of this function would
+ * catch it either.
+ *
+ * Pre-single-frame, this seam carried one exception: an `execTouchedPaths` set
+ * (Task 10) admitted a workspace install's repo-ROOT manifest/lockfile even
+ * though it sat outside the containment root, which was then the story's
+ * package dir. The root move made the containment root the repo root, so the
+ * manifest is in-root by construction and that carve-out was retired
+ * (PR2/Task 13). There is no exception to this seam now.
+ */
+export function resolveWithin(root, candidate) {
+    const absolute = isAbsolute(candidate) ? candidate : resolve(root, candidate);
+    if (isInside(root, absolute)) {
+        const resolved = realOrRaw(absolute);
+        if (entersGitMetadata(root, resolved) || isNaxConfigFile(root, resolved))
+            return null;
+        return resolved;
+    }
+    return null;
+}
+/**
+ * The reason text for a path `resolveWithin` refused (fix round 1, Task 10;
+ * `.git/` case added for nax#1943).
+ *
+ * A bare "resolves outside the permitted root" taught the model nothing
+ * the last time this shape of denial mattered: in the run that motivated
+ * this whole feature, that message is what led an agent to delete a
+ * tsconfig entry instead of installing the package it needed. The design's
+ * own rule is that a denial returns the reason AND what would have been
+ * allowed.
+ *
+ * A `.git/`-metadata refusal gets its own branch, checked first: unlike
+ * every other refusal this function handles, the candidate is genuinely
+ * INSIDE the root, so "resolves outside the permitted root" would be
+ * actively misleading rather than merely unhelpful.
+ *
+ * Every other refused path keeps the plain message. The GitCommit-specific
+ * manifest/lockfile message and its `isKnownManifestOrLockfileName` table
+ * were retired with the `execTouchedPaths` carve-out (PR2/Task 13): that
+ * message existed only to explain the carve-out's rule, and post root move
+ * a repo-root manifest is inside the root by construction, so there is no
+ * distinct rule left to explain.
+ *
+ * This must never get chattier for ordinary containment denials, and must
+ * never reveal repository structure for a path the model never touched.
+ *
+ * The root itself IS named, deliberately. The rule above -- never reveal
+ * repository structure -- is about paths the model never touched; this path is
+ * one the model just passed, and telling it where the boundary is is the
+ * difference between "adapt" and "work around". The dispatch preamble
+ * (src/prompts/sections/agent-scope.ts) states the same boundary only as a
+ * package-relative label (`packages/api`), never as an absolute path, so this
+ * message is where the agent first sees the absolute containment root -- and
+ * naming a path the model itself handed in is the right disclosure.
+ */
+function outOfRootReason(root, candidate) {
+    const absolute = isAbsolute(candidate) ? candidate : resolve(root, candidate);
+    if (isInside(root, absolute) && isNaxConfigFile(root, realOrRaw(absolute))) {
+        return ("is one of nax's own config files, which every tool is refused regardless of grant -- " +
+            "`quality.commands` and `acceptance.command` are run through a shell WITHOUT passing the " +
+            "permission gate because a human wrote them, so editing this file is a route to running " +
+            "an ungated command on the next run");
+    }
+    if (isInside(root, absolute) && entersGitMetadata(root, realOrRaw(absolute))) {
+        return ("targets git metadata under .git/, which every tool is refused regardless of grant -- " +
+            "writing there can corrupt the repository beyond git's own recovery, and reading its " +
+            "config is a route to influencing what nax executes without passing through Exec (nax#1943)");
+    }
+    return `resolves outside the permitted root (${root}), which is the only directory this tool can reach`;
+}
+/**
+ * The path globs in a grant, which for a verb-gated tool means the patterns
+ * that are not verb names.
+ *
+ * A grant list is overloaded -- verbs for Git, path globs for Write -- so
+ * matching every pattern against a path denied everything for Git, and
+ * matching none left its paths bounded by the root alone. `allowedVerbs` is a
+ * closed set the tool declares, so the two kinds separate without guessing.
+ */
+function pathMatchers(matchers, scope) {
+    const verbs = scope.allowedVerbs;
+    return verbs === undefined ? matchers : matchers.filter((m) => !verbs.includes(m.source));
+}
+/** Canonical repo-root-relative spelling grant globs and rules are matched against. */
+function repoRelative(resolvedRoot, resolved) {
+    return relative(resolvedRoot, resolved).split(sep).join("/");
+}
+/**
+ * A path spelled with the confined prefix the tool is already bound to
+ * (`.nax/scratchpad/spill/x.txt`) has it removed before `resolveWithin`
+ * runs, so both spellings reach the same file. This is a prefix REMOVAL,
+ * not a second containment root: what is left is still resolved inside
+ * the effective root, so a `..` after the prefix remains a breach.
+ */
+function stripConfinePrefix(confinePrefix, value) {
+    return confinePrefix !== "" && value.startsWith(confinePrefix) ? value.slice(confinePrefix.length) : value;
+}
+/**
+ * Resolve one candidate inside the effective root, then evaluate
+ * deny -> ask -> glob -> record. Returns a verdict to stop the walk with, or
+ * undefined when the candidate is admitted and the walk continues.
+ * `enforceGlobs` is the CALLER's glob predicate (`enforcePathGlobs` for string
+ * fields, `restrictPaths` for array/ref fields — see the module comment).
+ */
+function checkPathSegment(frame, candidate, enforceGlobs) {
+    const resolved = resolveWithin(frame.effectiveRoot, stripConfinePrefix(frame.confinePrefix, candidate.path));
+    if (resolved === null) {
+        return frame.ctx.deny(`${candidate.denialSubject} ${outOfRootReason(frame.effectiveRoot, candidate.outOfRootTarget)}`, true);
+    }
+    const rel = repoRelative(frame.ctx.resolvedRoot, resolved);
+    const ruleDenial = frame.ctx.applyPathRules(frame.tool, rel, frame.state);
+    if (ruleDenial !== undefined)
+        return ruleDenial;
+    if (enforceGlobs && !matchesAny(frame.globs, rel)) {
+        return frame.ctx.deny(`${frame.tool} is not granted "${rel}" for this stage`);
+    }
+    frame.resolvedPaths.push(resolved);
+    return undefined;
+}
+/** `scope.pathFields`: each field holds ONE path, checked as a whole. */
+function runPathFields(frame) {
+    for (const field of frame.scope.pathFields) {
+        const value = pathFieldValue(frame.input, field);
+        if (value === undefined)
+            continue;
+        if (typeof value !== "string")
+            return frame.ctx.deny(`"${field}" must be a string path`);
+        const denial = checkPathSegment(frame, { path: value, denialSubject: `path "${value}"`, outOfRootTarget: value }, frame.enforcePathGlobs);
+        if (denial !== undefined)
+            return denial;
+    }
+    return undefined;
+}
+/** `scope.listPathFields`: each field holds a whitespace-separated list, or an array, of paths. */
+function runListPathFields(frame) {
+    for (const field of frame.scope.listPathFields ?? []) {
+        const value = pathFieldValue(frame.input, field);
+        if (value === undefined)
+            continue;
+        const elements = typeof value === "string"
+            ? pathListElements(value, frame.effectiveRoot)
+            : Array.isArray(value) && value.every((element) => typeof element === "string")
+                ? value
+                : null;
+        if (elements === null)
+            return frame.ctx.deny(`"${field}" must be a string path or an array of string paths`);
+        for (const element of elements) {
+            const denial = checkPathSegment(frame, { path: element, denialSubject: `path "${element}"`, outOfRootTarget: element }, frame.enforcePathGlobs);
+            if (denial !== undefined)
+                return denial;
+        }
+    }
+    return undefined;
+}
+/** `scope.arrayPathFields`: each field holds an array whose every element is a path. */
+function runArrayPathFields(frame) {
+    for (const field of frame.scope.arrayPathFields ?? []) {
+        const values = frame.input[field];
+        if (values === undefined)
+            continue;
+        if (!Array.isArray(values))
+            return frame.ctx.deny(`"${field}" must be an array of string paths`);
+        for (const value of values) {
+            if (typeof value !== "string")
+                return frame.ctx.deny(`"${field}" entries must be strings`);
+            const denial = checkPathSegment(frame, { path: value, denialSubject: `"${field}" entry "${value}"`, outOfRootTarget: value }, frame.restrictPaths);
+            if (denial !== undefined)
+                return denial;
+        }
+    }
+    return undefined;
+}
+/** `scope.refPathFields`: each field holds an array of refs that MAY carry a `<rev>:<path>` path half. */
+function runRefPathFields(frame) {
+    for (const field of frame.scope.refPathFields ?? []) {
+        const values = frame.input[field];
+        if (values === undefined)
+            continue;
+        if (!Array.isArray(values))
+            return frame.ctx.deny(`"${field}" must be an array of string refs`);
+        for (const value of values) {
+            if (typeof value !== "string")
+                return frame.ctx.deny(`"${field}" entries must be strings`);
+            const colonAt = value.indexOf(":");
+            if (colonAt === -1)
+                continue; // pure revision, no path to check
+            const candidatePath = value.slice(colonAt + 1);
+            if (candidatePath === "")
+                continue; // e.g. "HEAD:" — no path to check
+            const denial = checkPathSegment(frame, { path: candidatePath, denialSubject: `"${field}" entry "${value}"`, outOfRootTarget: candidatePath }, frame.restrictPaths);
+            if (denial !== undefined)
+                return denial;
+        }
+    }
+    return undefined;
+}
+/**
+ * Containment runs before any pattern matching and wins over everything.
+ * Each resolved path is then evaluated deny -> ask -> allow. A verb-only
+ * grant declares no path globs, leaving the root as the only bound --
+ * unchanged behaviour, now an authoring choice rather than something the
+ * grant syntax could not express.
+ *
+ * `confineTo` (tool-declared, see `ToolScope`) shifts the root passed to
+ * `resolveWithin` from `<root>` to `<root>/<confineTo>`: containment stays
+ * the one seam, and only its ROOT changes. `relativeTo` keeps rooting at
+ * `resolvedRoot` so grant globs, deny rules and `naxOwnedWriteRefusal`
+ * continue to see the canonical repo-root-relative spelling -- authors
+ * write `.nax/scratchpad/**`, never `**`, regardless of `confineTo`.
+ *
+ * `confineTo` is bound to stay INSIDE `resolvedRoot`: an authoring typo of
+ * `..` or `../shared` would otherwise widen the containment root past the
+ * policy boundary and re-scope `resolveWithin`'s `.git/`-metadata and
+ * `isNaxConfigFile` protections to a root that no longer aligns with the
+ * segments those checks assume -- the repo's own `.nax/config.json` would
+ stop being segment-matched against `.nax`. The boundary is the policy
+ root's invariant, so an out-of-root confineTo refuses the call outright
+ rather than silently widening.
+ */
+export function pathsBranch(args) {
+    const { ctx, tool, scope, input, grant, state } = args;
+    const globs = pathMatchers(grant.matchers, scope);
+    let effectiveRoot = ctx.resolvedRoot;
+    if (scope.confineTo !== undefined) {
+        effectiveRoot = realOrRaw(join(ctx.resolvedRoot, scope.confineTo));
+        if (!isInside(ctx.resolvedRoot, effectiveRoot)) {
+            return ctx.deny(`${tool} declares confineTo "${scope.confineTo}" which resolves outside the policy root "${ctx.resolvedRoot}" -- confineTo must be a path INSIDE the policy root, never one that widens it`);
+        }
+    }
+    const frame = {
+        ctx,
+        tool,
+        scope,
+        input,
+        globs,
+        effectiveRoot,
+        state,
+        resolvedPaths: [],
+        confinePrefix: scope.confineTo === undefined ? "" : `${scope.confineTo}/`,
+        enforcePathGlobs: !grant.unconditional,
+        restrictPaths: !grant.unconditional && globs.length > 0,
+    };
+    const denial = runPathFields(frame) ?? runListPathFields(frame) ?? runArrayPathFields(frame) ?? runRefPathFields(frame);
+    if (denial !== undefined)
+        return denial;
+    return state.ask === undefined
+        ? { allowed: true, resolvedPaths: frame.resolvedPaths }
+        : ctx.askVerdict(frame.resolvedPaths, state.ask);
+}

package/dist/tools/policy.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Compile declarative grants into a policy, and answer one call at a time.
+ *
+ * nax-permission-mode-allow: applies grants resolved by resolvePermissions;
+ * decides no permission of its own.
+ *
+ * Containment runs BEFORE pattern matching and is not expressible in config:
+ * the root is a boundary no PROFILE can widen. `unrestricted` means "any
+ * tool, any path within the root", never "any path on the machine".
+ *
+ * The `execTouchedPaths` carve-out (Task 10) was retired in the single-frame
+ * root move (PR2/Task 13): the containment root became the repo root, so a
+ * workspace install's root manifest is in-root by construction and no
+ * exception to the boundary is needed.
+ */
+import type { BashApprovalMode } from "#src/config/bash-approval";
+import { resolveWithin } from "./policy-paths-branch.ts";
+import { type ToolGrant, type ToolPolicy } from "./types.ts";
+/** The single containment seam now lives beside the path branch that drives it. */
+export { resolveWithin };
+export interface ToolPolicyOptions {
+    /**
+     * Stage deny rules (spec R6). Same {tool, patterns} shape as grants; matched
+     * per branch and evaluated BEFORE ask and allow. A tool's unconditional
+     * deny rule also de-advertises it (see `grantedTools`).
+     */
+    readonly denyRules?: readonly ToolGrant[];
+    /**
+     * Stage ask rules (spec R1/R6). An ask match does not grant or refuse on its
+     * own: it marks a call the stage already granted as needing approval. An ask
+     * on an ungranted call is a plain denial.
+     */
+    readonly askRules?: readonly ToolGrant[];
+    /**
+     * The ONE nax-owned path this session may write despite `naxOwnedWriteRefusal`
+     * (nax#2115): the ABSOLUTE `fileOutput` path the dispatching op declared. It is
+     * canonicalised into this policy's own root-relative frame below rather than by
+     * the caller, so alternate spellings of the same file cannot diverge from the
+     * string the guard compares. Only the feature-PRD refusal honours it; the nax
+     * CONFIG refusal is deliberately not exempted.
+     */
+    readonly ownedWriteExemption?: string;
+    /** nax#2260: `execution.sandbox.filesystem.allowWrite`; a listed top-level `.nax/` entry becomes writable. */
+    readonly naxAllowWrite?: readonly string[];
+    /**
+     * How a bash command string is adjudicated (ADR-030). Absent means `gated` —
+     * today's behaviour — so every caller that does not opt in is unchanged.
+     *
+     * `raw` is a COMPILE-TIME input rather than a post-check transform on
+     * purpose: `checkBashCommand` lexes before it evaluates grants, so a `Bash(*)`
+     * grant cannot produce pass-through, and a post-check deny→allow would widen
+     * genuine containment denials too.
+     */
+    readonly bashApproval?: BashApprovalMode;
+    /**
+     * P4: set when `execution.sandbox.enabled` is true and the probe found the
+     * sandbox unavailable. Under `raw`, every Bash call is then denied with this
+     * reason -- raw requires the sandbox once it is enabled, and a silent
+     * fallback to unsandboxed raw would be a posture downgrade (spec S5).
+     * Ignored under gated/escalate, which run unwrapped with a warning.
+     */
+    readonly rawBashRefusal?: string;
+    readonly sandboxWrapped?: boolean;
+}
+export declare function compileToolPolicy(grants: readonly ToolGrant[], root: string, options?: ToolPolicyOptions): ToolPolicy;