@event4u/agent-config 16.5.0 → 17.0.0

package/src/scripts/hooks/block_credential_reads.ts

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse guard: refuse reading a credential-class file, and refuse a
+ * command that prints the process environment — road-to-one-detector-and-the-
+ * senders-we-own 1.1.
+ *
+ * Prevention ahead of the egress stage: a value that is never read cannot reach
+ * a model provider through any later bug, and everything the session reads goes
+ * into the conversation, so a `.env` read is a `.env` sent. It is a best-effort
+ * guard over the shapes it recognises, not a boundary: it allows what it cannot
+ * decide (`fail_closed: false`), and the residue below is not caught.
+ *
+ * What it refuses, with the class list in `_lib/credential_files.ts` (shared
+ * with the installer's native deny tier):
+ *
+ *   - a file tool (Read, Edit, Grep, …) whose target path is an environment
+ *     file (`.env`, `.env.*`, `.envrc` — `.env.example` and the other template
+ *     names pass), a private key, a cloud or CLI credential file, or a
+ *     package-registry credential file;
+ *   - a shell command that hands such a path — as an argument, a redirect or an
+ *     option value (`--config=.env`) — to anything but a short list of commands
+ *     that neither print nor run it (`ls`, `rm`, `chmod`, …), looking through
+ *     `sudo`/`command`/`nice`-style wrappers, `sh -c`, `eval` and command
+ *     substitutions;
+ *   - a shell command that prints the environment (`env`, `printenv`, a bare
+ *     `export`, a bare `set`, `declare -x`).
+ *
+ * What it allows: a write-only tool (the value is the model's own), a tool that
+ * returns names rather than content (Glob, LS), and a guard it cannot decide —
+ * a malformed envelope or any crash allows (`fail_closed: false`), so this
+ * guard is never the reason an unrelated call fails. Not caught, and recorded
+ * as the residue `tests/fixtures/egress-prevention-gaps/` names: a program that
+ * reads the file itself (`node -e "…readFileSync('.env')"`), a value printed by
+ * a running process, a secret typed by the user — and a search or glob that
+ * never names the file (`Grep path=.`, `grep -r KEY .`, `rg KEY`, `cat .e*`).
+ * The last returns the file's lines as tool output, which is the
+ * `program-output` fixture's channel: the stage sees it, this guard does not.
+ *
+ * Kill switch: `AGENT_CONFIG_ALLOW_CREDENTIAL_READS=1`.
+ *
+ * Only a host that binds `pre_tool_use` AND honours a deny refuses; elsewhere
+ * the dispatcher lowers the block to a warning (`host_semantics.ts`), and
+ * `agent-config hooks:status` answers which applies on the host in use.
+ *
+ * Exit codes (docs/contracts/hook-architecture-v1.md): 0 allow · 1 block.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import {
+    CREDENTIAL_CLASS_LABEL,
+    credentialBasename,
+    credentialFileClass,
+    HOST,
+    segmentVerdict,
+    type CredentialFileClass,
+    type PathHost,
+} from '../_lib/credential_files.js';
+import { isEnvKillSwitchActive } from '../_lib/env_kill_switch.js';
+import { invokedSegments } from './git_command_classifier.js';
+import { readHookStdin } from './hook_stdin.js';
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+export const KILL_SWITCH = 'AGENT_CONFIG_ALLOW_CREDENTIAL_READS';
+
+const PATH_KEYS: ReadonlySet<string> = new Set([
+    'file_path', 'path', 'target_file', 'filename', 'filePath', 'notebook_path', 'paths', 'files', 'file_paths',
+]);
+
+/** Every string held under a path key, at any depth and inside arrays. */
+function pathValues(v: JsonValue | undefined, underPathKey: boolean, out: string[]): string[] {
+    if (typeof v === 'string') {
+        if (underPathKey && v !== '') out.push(v);
+    } else if (Array.isArray(v)) {
+        for (const x of v) pathValues(x, underPathKey, out);
+    } else if (isObject(v)) {
+        for (const [k, x] of Object.entries(v)) pathValues(x, underPathKey || PATH_KEYS.has(k), out);
+    }
+    return out;
+}
+
+/** Tools that write a value the model already has, or list names without content. */
+const NON_READING_TOOLS: ReadonlySet<string> = new Set(['write', 'create_file', 'glob', 'ls', 'list_dir', 'file_search']);
+
+function isObject(v: JsonValue | undefined): v is JsonObject {
+    return v !== null && v !== undefined && typeof v === 'object' && !Array.isArray(v);
+}
+
+export interface Refusal {
+    readonly class: CredentialFileClass;
+    readonly what: string;
+}
+
+/** The refusal for one tool call, or null. Pure: the host whose paths are judged is an argument. */
+export function verdictFor(toolName: string, input: JsonObject, host: PathHost = HOST): Refusal | null {
+    const tool = toolName.trim().toLowerCase();
+    if (!NON_READING_TOOLS.has(tool)) {
+        for (const v of pathValues(input, false, [])) {
+            const cls = credentialFileClass(v, host);
+            if (cls !== null) return { class: cls, what: `\`${credentialBasename(v)}\`` };
+        }
+    }
+    const cmd = input['command'];
+    if (typeof cmd === 'string' && cmd !== '') {
+        for (const segment of invokedSegments(cmd)) {
+            const r = segmentVerdict(segment, host);
+            if (r !== null) return r;
+        }
+    }
+    return null;
+}
+
+export function denyMessage(r: Refusal): string {
+    const alternative =
+        r.class === 'process-environment'
+            ? 'Print one variable you need by name, and only one that holds no secret.'
+            : 'Reference the variable by name (`$NAME`, `process.env.NAME`) instead of reading its value; `.env.example` lists the keys.';
+    return (
+        `Blocked: ${r.what} is ${CREDENTIAL_CLASS_LABEL[r.class]}. What a session reads is sent to the model ` +
+        `provider, so a credential read is a credential sent. ${alternative} ` +
+        `(block-credential-reads; maintainer override: ${KILL_SWITCH}=1)\n`
+    );
+}
+
+export function main(): number {
+    if (isEnvKillSwitchActive(KILL_SWITCH)) return 0;
+    let envelope: JsonObject;
+    try {
+        const raw = readHookStdin();
+        if (!raw) return 0;
+        envelope = JSON.parse(raw) as JsonObject;
+    } catch {
+        return 0;
+    }
+    try {
+        const payload = isObject(envelope['payload']) ? envelope['payload'] : envelope;
+        const input = isObject(payload['tool_input']) ? payload['tool_input'] : isObject(envelope['tool_input']) ? envelope['tool_input'] : null;
+        if (input === null) return 0;
+        const rawTool = payload['tool_name'] ?? envelope['tool_name'];
+        const r = verdictFor(typeof rawTool === 'string' ? rawTool : '', input);
+        if (r === null) return 0;
+        process.stderr.write(denyMessage(r));
+        return 1;
+    } catch {
+        return 0;
+    }
+}
+
+function isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/hooks/block_no_verify.ts

@@ -62,6 +62,19 @@ const _GIT_GLOBAL_OPTS_WITH_VALUE: ReadonlySet<string> = new Set([
     '--exec-path',
     '--super-prefix',
 ]);
+/** Refusal fragments shared by the three hook-bypass branches, stored once. */
+const _BYPASSES = ' bypasses git hooks (git-history-discipline).';
+const _REMEDY =
+    ' Let the hooks run and fix what they report; that is the only path this guard leaves open.';
+/**
+ * Builtins where `git <sub> -h` verified short `-n` cannot bypass a hook.
+ * An ALLOWLIST, not a denylist of `commit`/`am`: with `ci = commit` aliased,
+ * `git ci -n` resolves to `ci`, which a denylist would miss. Git never lets
+ * an alias shadow a builtin, so aliases stay blocked. `am` is absent on
+ * purpose — unverified is not safe, and it carries `--no-verify`.
+ */
+const _SHORT_N_UNRELATED =
+    /^(add|branch|cherry-pick|clean|fetch|grep|log|merge|mv|pull|push|rebase|revert|rev-list|rm|shortlog|show|tag)$/;
 const _CONFIG_READ_OR_RESTORE: ReadonlySet<string> = new Set([
     '--get',
     '--get-all',
@@ -258,6 +271,24 @@ function _git_base(tokens: string[]): string[] | null {
     return null;
 }
 
+/**
+ * Index of the subcommand inside `git`'s arguments: the first token that is
+ * neither a global option nor the VALUE of one, so `git -C /repo config …`
+ * resolves to `config` and not to `/repo`. -1 when there is none.
+ */
+function _git_subcommand_index(rest: string[]): number {
+    for (let k = 0; k < rest.length; k += 1) {
+        const tok = rest[k] as string;
+        if (!tok.startsWith('-')) {
+            return k;
+        }
+        if (_GIT_GLOBAL_OPTS_WITH_VALUE.has(tok)) {
+            k += 1; // consume its value
+        }
+    }
+    return -1;
+}
+
 /**
  * `git config … core.hooksPath <value>` — the subcommand form of the hooksPath
  * override, distinct from the `-c` / `--config` global-option form handled in
@@ -281,20 +312,7 @@ function _git_base(tokens: string[]): string[] | null {
  */
 function _is_config_hookspath_write(git_tokens: string[]): [boolean, string] {
     const rest = git_tokens.slice(1);
-    // The subcommand is the first token that is neither a global option nor
-    // the VALUE of one — `git -C /repo config …` must still resolve to
-    // `config`, not to `/repo`.
-    let subIdx = -1;
-    for (let k = 0; k < rest.length; k += 1) {
-        const tok = rest[k] as string;
-        if (!tok.startsWith('-')) {
-            subIdx = k;
-            break;
-        }
-        if (_GIT_GLOBAL_OPTS_WITH_VALUE.has(tok)) {
-            k += 1; // consume its value
-        }
-    }
+    const subIdx = _git_subcommand_index(rest);
     if (subIdx === -1 || rest[subIdx] !== 'config') {
         return [false, ''];
     }
@@ -332,26 +350,32 @@ function _is_blocked(git_tokens: string[]): [boolean, string] {
     if (cfgBlocked) {
         return [cfgBlocked, cfgReason];
     }
+    // The long `--no-verify` stays unscoped below; only the SHORT forms are
+    // read against the subcommand, because only there does `-n` mean
+    // something else. An unresolved subcommand (`git -n`) is not in the set,
+    // so it stays blocked: unresolved is not safe.
+    const rest = git_tokens.slice(1);
+    const subIdx = _git_subcommand_index(rest);
+    const shortNIsUnrelated = subIdx !== -1 && _SHORT_N_UNRELATED.test(rest[subIdx] as string);
     let i = 1; // skip 'git'
     while (i < git_tokens.length) {
         const tok = git_tokens[i] as string;
-        if (_NO_VERIFY_FLAGS.has(tok)) {
-            return [true, `'${tok}' bypasses git hooks (git-history-discipline).`
-                    + ' Let the hooks run and fix what they report; that is the only path this guard leaves open.'];
+        // git resolves any unambiguous prefix of a long option, so `--no-verif`
+        // is `--no-verify`; an ambiguous one git refuses itself.
+        if (_NO_VERIFY_FLAGS.has(tok) || (tok.length > 5 && '--no-verify'.startsWith(tok))) {
+            return [true, `'${tok}'` + _BYPASSES + _REMEDY];
         }
-        if (_NO_VERIFY_SHORT.has(tok)) {
+        if (!shortNIsUnrelated && _NO_VERIFY_SHORT.has(tok)) {
             return [
                 true,
-                `'${tok}' is short for --no-verify and bypasses git hooks (git-history-discipline).`
-                    + ' Let the hooks run and fix what they report; that is the only path this guard leaves open.',
+                `'${tok}' is short for --no-verify and` + _BYPASSES + _REMEDY,
             ];
         }
         // Short flag bundles containing 'n': -nm, -mn, etc.
-        if (/^-[a-zA-Z]*n[a-zA-Z]*$/.test(tok) && !tok.startsWith('--')) {
+        if (!shortNIsUnrelated && /^-[a-zA-Z]*n[a-zA-Z]*$/.test(tok) && !tok.startsWith('--')) {
             return [
                 true,
-                `'${tok}' contains -n (--no-verify) and bypasses git hooks (git-history-discipline).`
-                    + ' Let the hooks run and fix what they report; that is the only path this guard leaves open.',
+                `'${tok}' contains -n (--no-verify) and` + _BYPASSES + _REMEDY,
             ];
         }
         if (tok === '-c') {

package/src/scripts/hooks/block_speaking_inbox_dir.ts

@@ -37,8 +37,9 @@
  * 2. **A directory that already exists.** Blocking every later write into an
  *    already-created speaking directory would wedge a session mid-round without
  *    removing the name — the fix there is a rename, which the deny message of
- *    the creating call already asked for. This is the one filesystem read the
- *    guard performs.
+ *    the creating call already asked for. A path-keyed tool's relative path
+ *    is probed against the tool's own `cwd` and nothing else; a shell
+ *    command's token is probed only when absolute.
  * 3. **An opaque round identifier** — `isOpaqueRoundId` in
  *    `_lib/source_shape.ts` is the single authority, shared with the gate, so
  *    the guard and the CI check can never disagree about what "opaque" means.
@@ -363,9 +364,14 @@ export function denyMessage(dir: string): string {
         '  round-a91f3c         content-free hex (also set-, src-set-, source-set-)\n' +
         '  S17                  a set number\n' +
         '\n' +
-        'Record the true source ONCE, encrypted, in the round\'s intake note:\n' +
+        'Record the true source ONCE, encrypted, in the round\'s intake note — the source\n' +
+        'itself (its URL or name), never an agents/tmp path, which this guard judges:\n' +
         "  printf '%s' '<the real source>' | ./scripts-run src/scripts/_lib/link_crypto encrypt\n" +
         '\n' +
+        'Already created? Rename it. Until then, this guard recognizes it in shell commands\n' +
+        'only when referenced by absolute path; relative arguments may resolve elsewhere\n' +
+        'and are judged as new.\n' +
+        '\n' +
         'Naming rule: /analyze:inbox Phase 1. Rule: src/rules/source-confidentiality.md.\n' +
         `Maintainer kill switch: ${KILL_SWITCH}=1.\n`
     );
@@ -395,7 +401,16 @@ export function main(): number {
         if (ti === null) {
             return 0;
         }
-        const repoRoot = typeof envelope['project_dir'] === 'string' ? envelope['project_dir'] : '';
+        // The base a relative path resolves against is the tool's own working
+        // directory: the native payload's `cwd`, where a path-keyed tool's
+        // relative path lands. `project_dir` (no producer sets it)
+        // and the dispatcher's `workspace_root` (the hook's cwd, the parent
+        // checkout in a worktree session) name other trees, and a field that
+        // can outrank the real base lets `mkdir` create in one tree what the
+        // probe found in another — so neither is read. No `cwd` → '' → the
+        // hook process cwd, the behaviour before this field was read.
+        const rawCwd = payload['cwd'];
+        const cwd = typeof rawCwd === 'string' && path.isAbsolute(rawCwd) ? rawCwd : '';
         const rawTool = payload['tool_name'] ?? envelope['tool_name'];
         const toolName = typeof rawTool === 'string' ? rawTool.trim().toLowerCase() : '';
         const candidates: string[] = [];
@@ -417,13 +432,29 @@ export function main(): number {
         // decision logic is shared rather than duplicated — see
         // `creatableTokens` for why "every whitespace token" was too many.
         const cmd = ti['command'] ?? (_isObject(envelope['payload']) ? (envelope['payload'] as JsonObject)['command'] : undefined);
+        // A shell command's relative token gets no exists-probe: whatever it
+        // invokes may change directory first (a script, a function, an alias),
+        // so its existence under `cwd` says nothing about where it lands. An
+        // absolute token names its own base and is probed.
+        const shellTokens: string[] = [];
         if (typeof cmd === 'string' && cmd) {
-            candidates.push(...creatableTokens(cmd));
+            shellTokens.push(...creatableTokens(cmd));
         }
-        for (const v of candidates) {
-            const verdict = verdictFor(v, (p) => fs.existsSync(p), repoRoot);
+        const judge = (v: string, exists: (p: string) => boolean): boolean => {
+            const verdict = verdictFor(v, exists, cwd);
             if (verdict.block && verdict.dir !== null) {
                 process.stderr.write(denyMessage(verdict.dir));
+                return true;
+            }
+            return false;
+        };
+        for (const v of shellTokens) {
+            if (judge(v, (p) => path.isAbsolute(v) && fs.existsSync(p))) {
+                return 1;
+            }
+        }
+        for (const v of candidates) {
+            if (judge(v, (p) => fs.existsSync(p))) {
                 return 1;
             }
         }

package/src/scripts/hooks/category_a.ts

@@ -23,6 +23,7 @@
  * grant — the host's own strings record `permissionDecision=allow ignored: a
  * confined session takes grants only from its command line`.
  */
+import * as fs from "node:fs";
 import * as path from "node:path";
 
 /** A JSON-ish tool input as it arrives in the dispatcher envelope. */
@@ -145,7 +146,46 @@ export function isInsideWorkingTree(candidate: string, root: string): boolean {
     const abs = path.resolve(root, candidate);
     const rel = path.relative(path.resolve(root), abs);
     if (rel === "") return true;
-    return !rel.startsWith("..") && !path.isAbsolute(rel);
+    // `..` as a whole first segment escapes; `...` or `..cache` is a name.
+    const escapes = rel === ".." || rel.startsWith(`..${path.sep}`);
+    return !escapes && !path.isAbsolute(rel);
+}
+
+/** `p` with every symlink in its longest existing prefix resolved. */
+function _real(p: string): string {
+    try {
+        return fs.realpathSync(p);
+    } catch (e) {
+        const code = (e as NodeJS.ErrnoException).code;
+        if (code !== "ENOENT" && code !== "ENOTDIR") return "";
+        // A dangling link is not a missing suffix: its target is unknowable.
+        try {
+            if (code === "ENOENT" && fs.lstatSync(p, { throwIfNoEntry: false })?.isSymbolicLink()) return "";
+        } catch {
+            return "";
+        }
+        const parent = path.dirname(p);
+        if (parent === p) return p;
+        const up = _real(parent);
+        return up && path.join(up, path.basename(p));
+    }
+}
+
+/**
+ * {@link isInsideWorkingTree}, and still inside once symlinks are followed.
+ *
+ * The one place the classifier reads the filesystem, and it can only withhold:
+ * an in-tree symlink to `~/.ssh` is lexically inside and really outside. A
+ * missing suffix keeps its lexical answer; a dangling link and any other
+ * resolution failure (`EACCES`, `ELOOP`) resolve to `""`, which is never inside. The check runs
+ * before the command does, so a link swapped in between is not seen — the
+ * OS sandbox is the boundary, this is a guardrail.
+ */
+function _reallyInside(candidate: string, root: string): boolean {
+    if (!isInsideWorkingTree(candidate, root)) return false;
+    const real = _real(path.resolve(root, candidate));
+    const realRoot = _real(path.resolve(root));
+    return real !== "" && realRoot !== "" && isInsideWorkingTree(real, realRoot);
 }
 
 /** Split a command on whitespace; the caller has already refused metacharacters. */
@@ -182,7 +222,7 @@ const GIT_VALUE_FLAGS: ReadonlySet<string> = new Set([
 ]);
 
 /**
- * The `git` subcommand, with global options skipped.
+ * The `git` subcommand and its argv index, with global options skipped.
  *
  * Returns `""` when a global option's VALUE escapes the working tree — an
  * absolute path or a `..` traversal. The check is textual rather than resolved
@@ -190,21 +230,127 @@ const GIT_VALUE_FLAGS: ReadonlySet<string> = new Set([
  * can decide is exactly the property that matters, and a relative path with no
  * `..` cannot escape.
  */
-function _gitSubcommand(argv: readonly string[]): string {
+function _gitSubcommandAt(argv: readonly string[]): { sub: string; index: number } {
     for (let i = 1; i < argv.length; i++) {
         const token = argv[i] as string;
-        if (!_isFlag(token)) return token;
+        if (!_isFlag(token)) return { sub: token, index: i };
         const [flag, inlineValue] = token.includes("=")
             ? [token.slice(0, token.indexOf("=")), token.slice(token.indexOf("=") + 1)]
             : [token, null];
         const value = inlineValue ?? (GIT_VALUE_FLAGS.has(flag) ? argv[++i] : undefined);
         if (value !== undefined && (path.isAbsolute(value) || value.split("/").includes(".."))) {
-            return "";
+            return { sub: "", index: -1 };
         }
     }
-    return "";
+    return { sub: "", index: -1 };
+}
+
+/**
+ * `git branch` is category A only in its observational forms — an allowlist,
+ * like the rest of this file. Every other form writes a ref: `-d`/`-D` and
+ * `-f`/`-m`/`-M`/`-C` can lose one, and a bare `git branch <name>`, `-c`,
+ * `-u` or `--edit-description` create or rewrite one. A positional operand is
+ * admitted only under `-l`/`--list`, where it is a pattern, or as the value of
+ * a filter flag.
+ */
+const GIT_BRANCH_OBSERVES =
+    /^(-[arlvi]+|--(all|remotes|list|verbose|show-current|(no-)?color)(=.*)?)$/;
+const GIT_BRANCH_FILTER = /^--((no-)?(contains|merged)|points-at|sort|format|abbrev)(=|$)/;
+
+function _gitBranchOnlyObserves(argv: readonly string[], index: number): boolean {
+    const rest = argv.slice(index + 1);
+    const listing = rest.some((t) => /^(-[arvi]*l[arlvi]*|--list)$/.test(t));
+    for (let i = 0; i < rest.length; i++) {
+        const token = rest[i] as string;
+        if (!_isFlag(token)) {
+            if (!listing) return false;
+        } else if (GIT_BRANCH_FILTER.test(token)) {
+            if (!token.includes("=") && !_isFlag(rest[i + 1] ?? "-")) i++;
+        } else if (!GIT_BRANCH_OBSERVES.test(token)) {
+            return false;
+        }
+    }
+    return true;
 }
 
+/**
+ * Heads that never open their arguments, so a path-shaped argument is a string
+ * and confining it would only put a prompt on `echo /tmp`. Not `date`: its
+ * `-f`/`--file` and `-r`/`--reference` open a path.
+ */
+const NON_OPENING_HEADS = /^(pwd|echo|basename|dirname|which)$/;
+
+/**
+ * Output-writing flags (0.3). Their target is a path like any other, and the
+ * walk below confines every spelling: a separate value token (`--output x`,
+ * `-fprint x`, `--outDir x`) is a positional, `--output=x` is an inline value,
+ * a glued short value (`sort -o/path`) is the tail of a single-dash token, and
+ * the value-less writers (`--write`/`-w`, `--fix`) write their positionals. So
+ * no per-head table is needed; one was measured inert and removed.
+ *
+ * For `grep`/`rg` the first positional, or an `-e`/`--regexp` value, is a
+ * pattern and therefore data; an `-f`/`--file` value is a path.
+ */
+const PATTERN_GIVEN = /^(-e|--regexp|-f|--file)(=|$)/;
+
+/**
+ * Every argument of a Bash command that may name a filesystem location.
+ *
+ * Positionals, flag inline values and the tail of a single-dash token
+ * (`-o/path`, `-f/path`) are all candidates: one that stays inside is harmless
+ * to check, and missing one is not. After `--` every token is a positional.
+ * Shell quote removal is applied; every other expansion is refused upstream by
+ * the metacharacter rule.
+ */
+function _pathArguments(argv: readonly string[], head: string): string[] {
+    const out: string[] = [];
+    const grep = head === "grep" || head === "rg";
+    let patternPending = grep && !argv.some((t) => PATTERN_GIVEN.test(t));
+    let endOfOptions = false;
+    for (let i = 1; i < argv.length; i++) {
+        const raw = argv[i] as string;
+        // An unquoted glob is expanded after this check, so what it selects
+        // (`.*` to `..`, `le*` to an outward symlink) is never seen. "*" is a
+        // candidate nothing confines.
+        if (/[*?[]/.test(raw.replace(/'[^']*'|"[^"]*"/g, ""))) out.push("*");
+        const token = raw.replace(/["']/g, "");
+        if (!endOfOptions && token === "--") {
+            endOfOptions = true;
+        } else if (endOfOptions || !_isFlag(token)) {
+            if (patternPending) patternPending = false;
+            else out.push(token);
+        } else if (grep && /^(-e|--regexp)$/.test(token)) {
+            i++;
+        } else if (grep && /^(-f|--file)$/.test(token)) {
+            out.push((argv[++i] ?? "").replace(/["']/g, ""));
+        } else {
+            // A dash-led token may itself be the value of the option before it
+            // (`sort -o --/../x`), so one that contains `/` is a path too.
+            if (token.includes("/")) out.push(token);
+            const eq = token.indexOf("=");
+            if (eq >= 0) out.push(token.slice(eq + 1));
+            else if (!token.startsWith("--") && token.length > 2) out.push(token.slice(2));
+        }
+    }
+    return out;
+}
+
+/** Stands in for the tree when the caller has none: absolute and `..` still escape it. */
+const UNROOTED = path.resolve("/agent-config-unrooted");
+
+function _confined(candidate: string, workingTree: string): boolean {
+    if (candidate.startsWith("~") || candidate === "*") return false;
+    return _reallyInside(candidate, workingTree.trim() ? workingTree : UNROOTED);
+}
+
+/** What the classifier decided, and whether a path confinement actually ran. */
+export interface CategoryAVerdict {
+    categoryA: boolean;
+    confined: boolean;
+}
+
+const NOT_A: CategoryAVerdict = { categoryA: false, confined: false };
+
 /** Non-flag token after the subcommand, or `""`. */
 function _secondSubcommand(argv: readonly string[]): string {
     const nonFlags = argv.slice(1).filter((t) => !_isFlag(t));
@@ -231,20 +377,14 @@ export function namesConsequenceOperation(command: string): boolean {
     return false;
 }
 
-/** Is this Bash command string category A? */
-export function isCategoryABashCommand(command: string): boolean {
-    if (typeof command !== "string" || !command.trim()) return false;
-    if (SHELL_METACHARACTERS.test(command)) return false;
-    if (namesConsequenceOperation(command)) return false;
-
-    const argv = _argv(command);
-    const head = (argv[0] ?? "").toLowerCase();
-    if (!head) return false;
-
+/** Does the head and its subcommand name a read, build, test or lint? */
+function _namesASafeOperation(argv: readonly string[], head: string): boolean {
     if (SAFE_HEADS.has(head)) return true;
 
     if (head === "git") {
-        return GIT_READ_SUBCOMMANDS.has(_gitSubcommand(argv));
+        const { sub, index } = _gitSubcommandAt(argv);
+        if (!GIT_READ_SUBCOMMANDS.has(sub)) return false;
+        return sub !== "branch" || _gitBranchOnlyObserves(argv, index);
     }
 
     const allowed = RUNNER_SUBCOMMANDS[head];
@@ -258,6 +398,36 @@ export function isCategoryABashCommand(command: string): boolean {
     return true;
 }
 
+/**
+ * Classify a Bash command string.
+ *
+ * `workingTree` is the root every path argument must resolve inside. Without
+ * one, the command is judged against a stand-in root, so an absolute, `~` or
+ * `..`-escaping argument still disqualifies it.
+ */
+export function bashCategoryAVerdict(command: string, workingTree = ""): CategoryAVerdict {
+    if (typeof command !== "string" || !command.trim()) return NOT_A;
+    if (SHELL_METACHARACTERS.test(command)) return NOT_A;
+    if (namesConsequenceOperation(command)) return NOT_A;
+
+    const argv = _argv(command);
+    const head = (argv[0] ?? "").toLowerCase();
+    if (!head) return NOT_A;
+    if (!_namesASafeOperation(argv, head)) return NOT_A;
+
+    if (NON_OPENING_HEADS.test(head)) return { categoryA: true, confined: false };
+    const candidates = _pathArguments(argv, head);
+    for (const candidate of candidates) {
+        if (!_confined(candidate, workingTree)) return NOT_A;
+    }
+    return { categoryA: true, confined: candidates.length > 0 };
+}
+
+/** Is this Bash command string category A? */
+export function isCategoryABashCommand(command: string, workingTree = ""): boolean {
+    return bashCategoryAVerdict(command, workingTree).categoryA;
+}
+
 /**
  * Is this tool call category A?
  *
@@ -265,27 +435,34 @@ export function isCategoryABashCommand(command: string): boolean {
  * root means the dispatcher could not establish one, and an unestablished
  * boundary is not a boundary — the call is not category A.
  */
-export function isCategoryA(
+export function categoryAVerdict(
     toolName: string,
     toolInput: ToolInput,
     workingTree: string,
-): boolean {
-    if (!workingTree.trim()) return false;
-    if (typeof toolName !== "string" || !toolName) return false;
+): CategoryAVerdict {
+    if (!workingTree.trim()) return NOT_A;
+    if (typeof toolName !== "string" || !toolName) return NOT_A;
 
     if (READ_ONLY_TOOLS.has(toolName)) {
+        let checked = false;
         for (const key of PATH_KEYS) {
             const value = toolInput?.[key];
             if (typeof value !== "string") continue;
-            if (!isInsideWorkingTree(value, workingTree)) return false;
+            if (!_reallyInside(value, workingTree)) return NOT_A;
+            checked = true;
         }
-        return true;
+        return { categoryA: true, confined: checked };
     }
 
     if (toolName === "Bash") {
         const command = toolInput?.["command"];
-        return typeof command === "string" && isCategoryABashCommand(command);
+        return typeof command === "string" ? bashCategoryAVerdict(command, workingTree) : NOT_A;
     }
 
-    return false;
+    return NOT_A;
+}
+
+/** Is this tool call category A? */
+export function isCategoryA(toolName: string, toolInput: ToolInput, workingTree: string): boolean {
+    return categoryAVerdict(toolName, toolInput, workingTree).categoryA;
 }