@nathapp/nax-agent 0.1.0

package/dist/tools/policy-bash-raw.js

@@ -0,0 +1,210 @@
+/**
+ * The `raw` bash mode screen (ADR-030).
+ *
+ * `raw` is pass-through: no per-segment grant matching, no root containment,
+ * and — unlike `checkBashCommand` — a command the lexer CANNOT read is ALLOWED
+ * rather than refused. That inversion is the whole point of the mode.
+ *
+ * The one thing this screen still does is catch a naive mistake: if the lexer
+ * CAN parse the command and a segment names or redirects into a path nax owns
+ * (`.nax/config.json`, `.nax/mono/*\/config.json`, `.nax/features/**\/prd.json`,
+ * the root queue-control files), the command is denied.
+ *
+ * ADVISORY BY CONSTRUCTION. A command using substitution is not parsed and
+ * therefore is not screened at all: `sh -c "$(echo rm) .nax/features/f/prd.json"`
+ * passes straight through. This is a mistake-catcher, not a boundary, and it
+ * must never grow into a general gate — gating lives in policy, once
+ * (`src/tools/bash.ts:14-19`). The ONE deliberate exception is the
+ * whole-filesystem `find` refusal below: a COST guard (a root-wide walk runs
+ * into the 300s Bash timeout), not a containment boundary.
+ *
+ * A parseable `cd` moves every LATER segment's frame of reference, exactly as
+ * it does for `checkBashCommand`, so this screen tracks it too via the shared
+ * `cdTargetsFor` / `nextWorkingDirectories` (bash-cwd.ts) -- otherwise
+ * `cd child && echo ABORT > ../.queue.txt` would be screened against the
+ * wrong directory and let a run-control write through unnoticed.
+ *
+ * THE CRITICAL ASYMMETRY, read this before touching the `cd` handling below:
+ * where `checkBashCommand` DENIES a `cd` it cannot model (an option-shaped
+ * target, an opaque one, one that fails to resolve), this screen must NOT --
+ * raw enforces no containment by definition, and denying there would silently
+ * re-gate raw into a containment gate through the back door of `cd` modelling.
+ * A `cd` that leaves the root (`cd ../outside`) is the common case:
+ * `resolvePath` is `resolveWithin(root, ...)`, which returns `null` for
+ * anything outside the root, so it yields no trackable frame at all. Do not
+ * "fix" the unmodelled cases into a denial.
+ *
+ * But failing open on the `cd` is NOT the same as abandoning the screen. An
+ * earlier revision returned `allow` for the WHOLE command on an unmodelled
+ * `cd`, which meant a single everyday idiom disabled the screen for every
+ * later segment: `cd - ; echo ABORT > .queue.txt` wrote the run-control file
+ * unscreened -- strictly worse than the initialPath-pinned code this tracking
+ * replaced, which caught it by accident. So an unmodelled `cd` leaves the
+ * frame set at its LAST KNOWN value and screening continues. The frame is
+ * then an estimate, and the screen may refuse a write that the shell would
+ * actually have placed somewhere harmless. That is the correct trade for an
+ * advisory mistake-catcher: a false refusal costs one turn and says why,
+ * while a false pass can abort the run.
+ */
+import { relative, resolve, sep } from "node:path";
+import { realOrRaw } from "#src/internal/realpath";
+import { lexBashCommand } from "#src/permissions/index";
+import { cdTargetsFor, nextWorkingDirectories } from "./bash-cwd.js";
+import { isNaxConfigFile, naxOwnedBashRefusal, naxOwnedKind } from "./nax-owned-writes.js";
+/**
+ * US-002: the start paths that mean "search the whole filesystem". An exact
+ * token comparison, never a prefix one: `~/proj` and `~user` are scoped and
+ * allowed, while `~` and `~/` are not.
+ */
+const BRACE_HOME = "$" + "{HOME}";
+const WHOLE_FILESYSTEM_STARTS = new Set([
+    "/",
+    "~",
+    "~/",
+    "$HOME",
+    "$HOME/",
+    BRACE_HOME,
+    `${BRACE_HOME}/`,
+]);
+/**
+ * US-002: the whole-filesystem start path of a `find` segment, or undefined.
+ *
+ * The start paths are the tokens after `find` -- and after any leading `-H`,
+ * `-L` or `-P` -- up to the first token that begins with `-`, `(` or `!`. The
+ * comparison uses the token TEXT (opaque tokens included: `$HOME` lexes as
+ * opaque and must still match).
+ */
+function wholeFilesystemFind(tokens) {
+    if (tokens[0]?.text !== "find")
+        return undefined;
+    let index = 1;
+    while (index < tokens.length) {
+        const text = tokens[index]?.text;
+        if (text !== "-H" && text !== "-L" && text !== "-P")
+            break;
+        index += 1;
+    }
+    for (; index < tokens.length; index += 1) {
+        const text = tokens[index]?.text ?? "";
+        if (text.startsWith("-") || text.startsWith("(") || text.startsWith("!"))
+            break;
+        if (WHOLE_FILESYSTEM_STARTS.has(text))
+            return text;
+    }
+    return undefined;
+}
+function deny(reason) {
+    // Never escalatable: a protected-path write is affirmatively out of bounds,
+    // not a command the gate merely could not read.
+    return { kind: "deny", reason, breach: false, escalatable: false };
+}
+/**
+ * A protected path, named for the refusal message, or undefined.
+ *
+ * Returns the KIND it matched alongside the token the agent used, so the caller
+ * can print kind-specific refusal text (`naxOwnedBashRefusal`).
+ *
+ * Checked against EVERY frame in `cwd`, mirroring the conservatism of gated
+ * mode's own `resolveAll`: a `;`-joined `cd` can leave more than one frame
+ * live at once (see `nextWorkingDirectories`), and a candidate that is safe
+ * from one frame but hits a protected path from another must still deny.
+ *
+ * Two passes, in order:
+ *
+ * 1. LEXICAL nax-config check. The raw screen has no typed seam in front of
+ *    it, and `args.resolvePath` (production: `resolveWithin`) returns null
+ *    for `.nax/config.json` exactly because typed tools are SUPPOSED to refuse
+ *    those writes. Falling through to that null would let the entire class
+ *    of nax-config writes go unscreened. Resolve the candidate lexically
+ *    against each frame -- `realOrRaw` walks to the nearest existing ancestor,
+ *    so a not-yet-created file under a symlinked temp root still compares
+ *    equal to `realOrRaw(root)` -- and refuse on `isNaxConfigFile` BEFORE the
+ *    resolver is consulted.
+ *
+ * 2. Typed-seam resolver pass (unchanged). `args.resolvePath` continues to be
+ *    the gate for everything else: a `null` skips this frame, an out-of-root
+ *    path skips this frame, and `isNaxOwnedWritePath` covers the queue file
+ *    and feature PRD set.
+ *
+ * The two checks do not overlap: pass 1 covers nax config files; pass 2 covers
+ * feature PRDs and the queue run-control files. `isNaxConfigFile` is checked
+ * lexically here because the resolver cannot return it, and lexically in
+ * `resolveWithin` for the same reason; `isNaxOwnedWritePath` is unchanged.
+ */
+function protectedHit(args, candidate, cwd) {
+    for (const directory of cwd) {
+        // Pass 1: lexical nax-config check. Independent of the resolver on
+        // purpose -- see the comment above. `realOrRaw` walks to the nearest
+        // existing ancestor so the comparison holds even when the file does not
+        // yet exist on disk (which is the common case: the screen catches the
+        // write BEFORE the file lands).
+        const lexical = realOrRaw(resolve(directory, candidate));
+        if (isNaxConfigFile(args.root, lexical))
+            return { kind: "config", hit: candidate };
+        // Pass 2: typed-seam resolver (unchanged).
+        const resolved = args.resolvePath(candidate, directory);
+        if (resolved === null)
+            continue;
+        const rel = relative(args.root, resolved).split(sep).join("/");
+        if (rel.startsWith(".."))
+            continue;
+        const kind = naxOwnedKind(rel);
+        if (kind !== undefined)
+            return { kind, hit: candidate };
+    }
+    return undefined;
+}
+export function screenRawBashCommand(args) {
+    const { command, tool } = args;
+    if (typeof command !== "string")
+        return deny(`"command" must be a string`);
+    if (command.trim() === "")
+        return deny(`"command" must not be empty`);
+    const lexed = lexBashCommand(command);
+    // The inversion: unreadable means unscreened, and unscreened means allowed.
+    if (lexed.kind === "refused")
+        return { kind: "allow" };
+    let cwd = [args.initialPath];
+    const sandboxWrapped = args.sandboxWrapped === true;
+    for (const segment of lexed.segments) {
+        // US-002 COST GUARD (see the file header): a `find` rooted at the whole
+        // filesystem walks every mount and runs into the 300s Bash timeout. Raw has
+        // no containment, so nothing else stops it. Not a boundary -- a cost guard.
+        const findStart = wholeFilesystemFind(segment.tokens);
+        if (findStart !== undefined) {
+            return deny(`\`find ${findStart}\` searches the whole filesystem and runs into the 300s Bash timeout. ` +
+                `Search within the repository root instead: ${args.root}`);
+        }
+        for (const token of segment.tokens) {
+            if (token.opaque)
+                continue;
+            const hit = protectedHit(args, token.text, cwd);
+            // US-002: sandbox-wrapped, a token that only NAMES a PRD is allowed --
+            // the sandbox is the boundary, so a read costs nothing. Config and queue
+            // are unchanged in both modes.
+            if (hit !== undefined && !(sandboxWrapped && hit.kind === "prd")) {
+                return deny(naxOwnedBashRefusal(tool, hit.kind, hit.hit, "names"));
+            }
+        }
+        for (const redirect of segment.redirects) {
+            if (redirect.opaque)
+                continue;
+            const hit = protectedHit(args, redirect.target, cwd);
+            if (hit !== undefined) {
+                // A redirect WRITES, so even sandbox-wrapped it is refused -- with the
+                // read/write truth for a PRD (US-002), unchanged text elsewhere.
+                return deny(naxOwnedBashRefusal(tool, hit.kind, hit.hit, "redirects into", { sandboxWrapped }));
+            }
+        }
+        // See the file header ("THE CRITICAL ASYMMETRY"). An unmodelled `cd` is
+        // never itself a denial -- that inversion from gated mode is deliberate --
+        // but it does not end the screen either: the frame set simply stays where
+        // it was and the later segments are still checked against it. Returning
+        // `allow` here instead would let `cd - ; echo ABORT > .queue.txt` through.
+        const cdResult = cdTargetsFor(segment, cwd, args.resolvePath);
+        if (cdResult.kind === "resolved") {
+            cwd = nextWorkingDirectories(segment, cwd, cdResult.targets);
+        }
+    }
+    return { kind: "allow" };
+}

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

@@ -0,0 +1,64 @@
+/**
+ * Per-segment evaluation of a model-authored Bash command (spec §4 US-005).
+ *
+ * Precedence, fixed and order-independent within a stage (spec R6 + US-005.3):
+ *   1. the non-string / empty-command guards
+ *   2. ANY segment matches deny   -> deny the whole call (breach false)
+ *   3. payload checks per segment -> DENIED_FLAGS, containment, redirects, cd (breach as today)
+ *   4. the lexer refused the command -> the escalatable lexical refusal
+ *   5. EVERY segment must match an allow rule, else the escalatable grant miss
+ *   6. ANY segment matches ask    -> ask
+ * `escalatable: true` is produced at the two Category A sites above (4 and 5)
+ * plus the one payload refusal the gate also cannot adjudicate: an
+ * option-shaped `cd` (`cd -`, `cd -P dir`), whose target sits in a slot this
+ * reader does not parse (step 3 -- see `checkPayload`). Every OTHER payload
+ * denial is affirmatively out of bounds and non-escalatable, so an
+ * out-of-bounds command never reaches the human on a later grant miss or
+ * refusal. On a refused command the deny and payload checks run over the
+ * lexer's `prefix` -- the part before the unreadable construct -- because that
+ * is the part a deny rule or a containment breach can still name.
+ * Ask is evaluated LAST so it can never grant: an ungranted command that
+ * matches an ask rule is a plain denial, not an approval prompt (the same
+ * rule the path and argv branches follow in policy.ts).
+ *
+ * Containment is INJECTED (`resolvePath`), not imported: `policy.ts` imports
+ * this module, so importing `resolveWithin` back would be a cycle. The single
+ * owner of the root boundary and the `.git/` refusal therefore remains `policy.ts`.
+ */
+import type { CompiledEntry } from "./policy-match.ts";
+export type BashCheck = {
+    readonly kind: "allow";
+} | {
+    readonly kind: "ask";
+    readonly rule: string;
+} | {
+    readonly kind: "deny";
+    readonly reason: string;
+    readonly breach: boolean;
+    /**
+     * True when the gate could not ADJUDICATE the command — the lexer refused
+     * it, no allow rule covered a segment, or a `cd` target is option-shaped
+     * and sits in a slot this reader does not parse. False when the command
+     * is affirmatively out of bounds (root escape, `.git/`, a denied flag, an
+     * explicit deny rule, a `cd` target outside the root). Only the former
+     * may be escalated to the ask tier by `escalate` mode; escalating the
+     * latter would dissolve the `breach` signal into an approval prompt. See
+     * ADR-030.
+     */
+    readonly escalatable: boolean;
+};
+export interface BashCheckArgs {
+    readonly tool: string;
+    readonly command: unknown;
+    /** The stage's compiled ALLOW entry for this tool. */
+    readonly grant: CompiledEntry;
+    readonly denyEntry?: CompiledEntry;
+    readonly askEntry?: CompiledEntry;
+    /** Absolute resolved path, or null when the candidate escapes the root or
+     * enters `.git/`. Supplied by policy.ts (see the header). */
+    /** Resolves a candidate from an effective shell working directory. */
+    readonly resolvePath: (candidate: string, cwd: string) => string | null;
+    /** The shell's initial working directory. */
+    readonly initialPath: string;
+}
+export declare function checkBashCommand(args: BashCheckArgs): BashCheck;

package/dist/tools/policy-bash.js

@@ -0,0 +1,232 @@
+/**
+ * Per-segment evaluation of a model-authored Bash command (spec §4 US-005).
+ *
+ * Precedence, fixed and order-independent within a stage (spec R6 + US-005.3):
+ *   1. the non-string / empty-command guards
+ *   2. ANY segment matches deny   -> deny the whole call (breach false)
+ *   3. payload checks per segment -> DENIED_FLAGS, containment, redirects, cd (breach as today)
+ *   4. the lexer refused the command -> the escalatable lexical refusal
+ *   5. EVERY segment must match an allow rule, else the escalatable grant miss
+ *   6. ANY segment matches ask    -> ask
+ * `escalatable: true` is produced at the two Category A sites above (4 and 5)
+ * plus the one payload refusal the gate also cannot adjudicate: an
+ * option-shaped `cd` (`cd -`, `cd -P dir`), whose target sits in a slot this
+ * reader does not parse (step 3 -- see `checkPayload`). Every OTHER payload
+ * denial is affirmatively out of bounds and non-escalatable, so an
+ * out-of-bounds command never reaches the human on a later grant miss or
+ * refusal. On a refused command the deny and payload checks run over the
+ * lexer's `prefix` -- the part before the unreadable construct -- because that
+ * is the part a deny rule or a containment breach can still name.
+ * Ask is evaluated LAST so it can never grant: an ungranted command that
+ * matches an ask rule is a plain denial, not an approval prompt (the same
+ * rule the path and argv branches follow in policy.ts).
+ *
+ * Containment is INJECTED (`resolvePath`), not imported: `policy.ts` imports
+ * this module, so importing `resolveWithin` back would be a cycle. The single
+ * owner of the root boundary and the `.git/` refusal therefore remains `policy.ts`.
+ */
+import { lexBashCommand } from "#src/permissions/index";
+import { cdTargetsFor, nextWorkingDirectories } from "./bash-cwd.js";
+import { deniedFlag } from "./exec-guard.js";
+function deny(reason, breach = false, escalatable = false) {
+    return { kind: "deny", reason, breach, escalatable };
+}
+/**
+ * Prefix match, token-wise, with the two rules Exec's `matchesArgvPattern`
+ * does not have:
+ *
+ * - a TRAILING `*` is OPTIONAL, because the spec requires `Bash(bun test *)`
+ *   to admit bare `bun test` as well as `bun test src/x.test.ts`;
+ * - an OPAQUE token (one that contained `$`-expansion) can match only a bare
+ *   `*` pattern token during grant evaluation. Payload validation then refuses
+ *   it, because its runtime value cannot be contained safely.
+ */
+function matchesTokens(patternTokens, tokens) {
+    const required = patternTokens.length > 0 && patternTokens[patternTokens.length - 1]?.source === "*"
+        ? patternTokens.slice(0, -1)
+        : patternTokens;
+    if (tokens.length < required.length)
+        return false;
+    return required.every((pattern, index) => {
+        const token = tokens[index];
+        if (token.opaque && pattern.source !== "*")
+            return false;
+        return pattern.re.test(token.text);
+    });
+}
+function matchesSegment(entry, segment) {
+    if (entry.unconditional)
+        return true;
+    return entry.argvPatterns.some((tokens) => matchesTokens(tokens, segment.tokens));
+}
+/** `Tool` for an unconditional entry, else `Tool(<the pattern that matched>)`. */
+function ruleExpr(tool, entry, segment) {
+    if (entry.unconditional)
+        return tool;
+    const sources = entry.raw.filter((pattern) => pattern !== "*");
+    const index = segment === undefined ? -1 : entry.argvPatterns.findIndex((tokens) => matchesTokens(tokens, segment.tokens));
+    const matched = index === -1 ? undefined : sources[index];
+    return `${tool}(${matched ?? entry.raw.join(", ")})`;
+}
+function render(segment) {
+    return segment.tokens.map((token) => token.text).join(" ");
+}
+/**
+ * The filesystem path a word can actually address, once a prefix is stripped.
+ *
+ * A word carrying a separator is not necessarily the path: `--output=/etc/passwd`
+ * and `-o/etc/passwd` both hide one behind a flag, and `resolveWithin` reads the
+ * whole word as a RELATIVE path (`<root>/--output=/etc/passwd`), so the escape
+ * lives in the embedded value while the raw word looks contained. Extract it:
+ *
+ *   --output=/etc/passwd -> /etc/passwd   (value after an `=` that precedes a separator)
+ *   -o/etc/passwd        -> /etc/passwd   (from the first separator on a `-`-led word)
+ *   ../etc/passwd        -> ../etc/passwd (no prefix: the word itself)
+ *   link                 -> link          (no prefix: a bare word can be a symlink out)
+ *
+ * The last line is why this runs on EVERY non-opaque word rather than only the
+ * separator-bearing ones: a bare `link` can be a symlink to a target outside the
+ * root, and a word that does not exist safely joins under the root because
+ * `realOrRaw` walks up to the nearest existing ancestor and never throws.
+ */
+function containmentTarget(text) {
+    // The value after `=` is the target whether or not it contains a separator:
+    // `--output-dir=..` escapes just as `--output-dir=../x` does, and reading the
+    // whole word instead resolves `<root>/--output-dir=..` -- a literal segment
+    // that is trivially inside the root while the command receives `..`.
+    const equals = text.indexOf("=");
+    const slash = text.indexOf("/");
+    if (equals !== -1 && (slash === -1 || equals < slash))
+        return text.slice(equals + 1);
+    if (slash === -1)
+        return text;
+    if (text.startsWith("-"))
+        return text.slice(slash);
+    return text;
+}
+function hasUnmodelledExpansion(text) {
+    return ["*", "?", "[", "]", "{", "}"].some((character) => text.includes(character));
+}
+function resolveAll(args, candidate, cwd) {
+    const resolved = cwd.map((directory) => args.resolvePath(candidate, directory));
+    return resolved.every((path) => path !== null) ? resolved : undefined;
+}
+function checkPayload(args, segment, cwd) {
+    const words = segment.tokens.map((token) => token.text);
+    // Same list and normalizer as Exec: a prefix grant gates the verb, never the
+    // payload, so `bun add x --registry https://evil` satisfies `bun add *`.
+    const flag = deniedFlag(words);
+    if (flag !== undefined)
+        return { refusal: deny(`flag ${flag} is not permitted in a Bash command`) };
+    for (const token of segment.tokens) {
+        if (token.opaque || hasUnmodelledExpansion(token.text)) {
+            return { refusal: deny(`token "${token.text}" depends on shell expansion this gate cannot resolve`) };
+        }
+        const target = containmentTarget(token.text);
+        if (target.startsWith("~")) {
+            return {
+                refusal: deny(`token "${token.text}" addresses "${target}", which starts with "~" and depends on expansion this gate cannot resolve`),
+            };
+        }
+        if (resolveAll(args, target, cwd) === undefined) {
+            return {
+                refusal: deny(`token "${token.text}" addresses "${target}", which resolves outside the permitted root, or into .git/`, true),
+            };
+        }
+    }
+    let cdTargets;
+    // `cd` moves every LATER segment's frame of reference, so its target is
+    // containment-checked even when it carries no separator (`cd ..`). The
+    // resolution and the WHY-unmodellable reasoning are shared with the raw
+    // screen via `cdTargetsFor` (bash-cwd.ts). Gated denies every unmodelled
+    // case, because containment is the whole point of this mode.
+    const cdResult = cdTargetsFor(segment, cwd, args.resolvePath);
+    switch (cdResult.kind) {
+        case "no-target":
+            return { refusal: deny("`cd` with no target is refused") };
+        case "option-shaped":
+            // `cd -`, `cd -P dir`: the path sits in a slot this reader does not
+            // parse, so the gate CANNOT ADJUDICATE where the shell lands. That is
+            // Category A, like the lexer's own refusal -- not the affirmative
+            // out-of-bounds of a `cd` target that resolves outside the root, which
+            // stays a non-escalatable breach below. Marking it escalatable keeps a
+            // refusal the gate cannot model from preempting the (equally
+            // unadjudicable) grant miss when the reorder runs payload checks first.
+            return {
+                refusal: deny(`cd target "${cdResult.text}" is option-shaped, and this gate does not model it`, false, true),
+            };
+        case "opaque":
+        case "unresolved":
+            return { refusal: deny(`cd target "${cdResult.text}" is not inside the permitted root`, true) };
+        case "resolved":
+            cdTargets = cdResult.targets;
+            break;
+        case "not-cd":
+            break;
+    }
+    for (const redirect of segment.redirects) {
+        if (redirect.opaque) {
+            return { refusal: deny(`redirect target "${redirect.target}" depends on expansion this gate cannot resolve`) };
+        }
+        // Redirect targets are NOT in `segment.tokens`, and `resolveWithin` does not
+        // expand `~`: it would read `~/evil.txt` as the literal `<root>/~/evil.txt`
+        // and wave it through, while `/bin/sh` writes to `$HOME/evil.txt`. Mirrors
+        // the `~` guard on the token loop above.
+        if (redirect.target.startsWith("~")) {
+            return {
+                refusal: deny(`redirect target "${redirect.target}" starts with "~", which depends on expansion this gate cannot resolve`),
+            };
+        }
+        if (hasUnmodelledExpansion(redirect.target)) {
+            return {
+                refusal: deny(`redirect target "${redirect.target}" depends on shell expansion this gate cannot resolve`),
+            };
+        }
+        if (resolveAll(args, redirect.target, cwd) === undefined) {
+            return { refusal: deny(`redirect target "${redirect.target}" resolves outside the permitted root`, true) };
+        }
+    }
+    return { cdTargets };
+}
+export function checkBashCommand(args) {
+    const { command, tool } = args;
+    if (typeof command !== "string")
+        return deny(`"command" must be a string`);
+    if (command.trim() === "")
+        return deny(`"command" must not be empty`);
+    const lexed = lexBashCommand(command);
+    // On a refusal the gate still runs its deny and payload checks -- over the
+    // lexable prefix, the part before the unreadable construct. The prefix is
+    // empty when the refusal preceded any completed word, leaving the checks a
+    // no-op and the escalatable lexical refusal intact (Category A).
+    const segments = lexed.kind === "ok" ? lexed.segments : lexed.prefix;
+    for (const segment of segments) {
+        if (args.denyEntry !== undefined && matchesSegment(args.denyEntry, segment)) {
+            return deny(`${tool} segment "${render(segment)}" is denied for this stage by rule ${ruleExpr(tool, args.denyEntry, segment)}`);
+        }
+    }
+    let cwd = [args.initialPath];
+    for (const segment of segments) {
+        const result = checkPayload(args, segment, cwd);
+        if (result.refusal !== undefined)
+            return result.refusal;
+        cwd = nextWorkingDirectories(segment, cwd, result.cdTargets);
+    }
+    if (lexed.kind === "refused") {
+        return deny(`command contains ${lexed.construct}, which cannot be analysed and is therefore refused -- ` +
+            "rewrite it without that construct, or use a structured tool", false, true);
+    }
+    for (const segment of segments) {
+        if (args.grant.unconditional || matchesSegment(args.grant, segment))
+            continue;
+        const granted = args.grant.raw.filter((pattern) => pattern !== "*").join(", ");
+        const alternatives = granted === "" ? "no command forms are granted for this stage" : `granted forms: ${granted}`;
+        return deny(`${tool} is not granted "${render(segment)}" -- ${alternatives}`, false, true);
+    }
+    for (const segment of segments) {
+        if (args.askEntry !== undefined && matchesSegment(args.askEntry, segment)) {
+            return { kind: "ask", rule: ruleExpr(tool, args.askEntry, segment) };
+        }
+    }
+    return { kind: "allow" };
+}

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

@@ -0,0 +1,32 @@
+/**
+ * The Bash branch of the tool policy, extracted from `policy.ts` to keep that
+ * file under its 600-line source limit. `src/` reaches this module only
+ * through `policy.ts`, so the barrel surface is unchanged.
+ *
+ * The Bash branch. Checked in policy-bash.ts, or policy-bash-raw.ts under the
+ * `raw` mode, and never falling through: a command string is not a verb and
+ * not a path, so neither of the other branches can judge it. Containment is
+ * handed over as a callback because policy.ts imports this module, so
+ * reaching `resolveWithin` back would close a cycle.
+ */
+import type { BashApprovalMode } from "#src/config/bash-approval";
+import type { CompiledEntry } from "./policy-match.ts";
+import type { PolicyVerdict, ToolScope } from "./types.ts";
+export interface BashCommandBranchArgs {
+    readonly tool: string;
+    readonly scope: ToolScope;
+    readonly input: Record<string, unknown>;
+    readonly grant: CompiledEntry;
+    readonly bashApproval: BashApprovalMode;
+    /** P4: when set, the enabled sandbox is unavailable and `raw` denies every call (spec S5). */
+    readonly rawBashRefusal?: string;
+    /** US-002: true when the sandbox wraps the command, so `raw` no longer refuses a PRD it only reads. */
+    readonly sandboxWrapped?: boolean;
+    readonly resolvedRoot: string;
+    readonly denyBy: ReadonlyMap<string, CompiledEntry>;
+    readonly askBy: ReadonlyMap<string, CompiledEntry>;
+    readonly resolvePath: (candidate: string, cwd: string) => string | null;
+    readonly deny: (reason: string, breach?: boolean, escalatable?: boolean) => PolicyVerdict;
+    readonly askVerdict: (resolvedPaths: readonly string[], rule: string) => PolicyVerdict;
+}
+export declare function commandBranch(args: BashCommandBranchArgs): PolicyVerdict | undefined;

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

@@ -0,0 +1,63 @@
+/**
+ * The Bash branch of the tool policy, extracted from `policy.ts` to keep that
+ * file under its 600-line source limit. `src/` reaches this module only
+ * through `policy.ts`, so the barrel surface is unchanged.
+ *
+ * The Bash branch. Checked in policy-bash.ts, or policy-bash-raw.ts under the
+ * `raw` mode, and never falling through: a command string is not a verb and
+ * not a path, so neither of the other branches can judge it. Containment is
+ * handed over as a callback because policy.ts imports this module, so
+ * reaching `resolveWithin` back would close a cycle.
+ */
+import { checkBashCommand } from "./policy-bash.js";
+import { screenRawBashCommand } from "./policy-bash-raw.js";
+export function commandBranch(args) {
+    const { tool, scope, input, grant, bashApproval, rawBashRefusal, sandboxWrapped, resolvedRoot, denyBy, askBy, resolvePath, deny, askVerdict, } = args;
+    if (scope.commandField === undefined)
+        return undefined;
+    if (bashApproval === "raw") {
+        if (rawBashRefusal !== undefined)
+            return deny(rawBashRefusal, false, false);
+        const screened = screenRawBashCommand({
+            tool,
+            command: input[scope.commandField],
+            initialPath: resolvedRoot,
+            root: resolvedRoot,
+            sandboxWrapped: sandboxWrapped === true,
+            resolvePath,
+        });
+        if (screened.kind === "deny")
+            return deny(screened.reason, screened.breach, screened.escalatable);
+        return { allowed: true, resolvedPaths: [] };
+    }
+    const denyEntry = denyBy.get(tool);
+    const askEntry = askBy.get(tool);
+    const result = checkBashCommand({
+        tool,
+        command: input[scope.commandField],
+        grant,
+        ...(denyEntry !== undefined ? { denyEntry } : {}),
+        ...(askEntry !== undefined ? { askEntry } : {}),
+        initialPath: resolvedRoot,
+        resolvePath,
+    });
+    if (result.kind === "deny") {
+        // `escalate` converts only a denial the gate could not ADJUDICATE. A
+        // breach, a denied flag or an explicit deny rule stays a hard refusal:
+        // escalating those would dissolve the `breach` signal into an approval
+        // prompt. See ADR-030 and `BashCheck.escalatable` in policy-bash.ts for
+        // the sites that set it.
+        if (bashApproval === "escalate" && result.escalatable) {
+            // NOT `askVerdict(...)`: that helper REWRITES reason as
+            // `matched ask rule "<rule>"`, which is false here — no ask rule
+            // matched. Build the verdict directly so the original denial reason
+            // survives into the ledger and into the human prompt. `rule` is
+            // omitted; `runtime.ts` falls back to `verdict.reason`.
+            return { allowed: false, reason: result.reason, breach: false, outcome: "ask", resolvedPaths: [] };
+        }
+        return deny(result.reason, result.breach, result.escalatable);
+    }
+    if (result.kind === "ask")
+        return askVerdict([], result.rule);
+    return { allowed: true, resolvedPaths: [] };
+}

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

@@ -0,0 +1,2 @@
+/** Read a top-level or dot-addressed path-bearing input field. */
+export declare function pathFieldValue(input: Record<string, unknown>, field: string): unknown;

package/dist/tools/policy-input.js

@@ -0,0 +1,10 @@
+/** Read a top-level or dot-addressed path-bearing input field. */
+export function pathFieldValue(input, field) {
+    let value = input;
+    for (const part of field.split(".")) {
+        if (typeof value !== "object" || value === null || Array.isArray(value))
+            return undefined;
+        value = value[part];
+    }
+    return value;
+}