one-code-extension 0.4.1 → 0.5.0

package/extensions/auto-mode/shell-analysis.ts

@@ -32,7 +32,24 @@
 
 import { isProtectedPath } from "../permissions/protected-paths.ts";
 import { isExecutionPrimitivePath, isSensitivePath } from "./sensitive.ts";
-import { isWithin, resolveForContainment, toAbsoluteBash } from "./paths.ts";
+import { isWithin, resolveForContainment, toAbsoluteBash, touchesGuardedPath } from "./paths.ts";
+import { checkoutGitRunsProgram, READ_HOOKS } from "./git-checkout-programs.ts";
+import { lstatSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import {
+	GIT_GLOBAL_SAFE,
+	GIT_SUBCOMMAND_SPECS,
+	PATTERN_OPTIONS,
+	READ_ONLY_SPECS,
+	checkFind,
+	checkOptions,
+	gitOperandsAllowed,
+	table,
+	type OptionSpec,
+} from "./read-only-options.ts";
+import { parseCommand, scopedTracker, type Segment, type Token } from "./shell-parse.ts";
+
+export { decodeAnsiC, LOOPS, parseCommand, scopedTracker, type ParseResult, type Segment, type Token } from "./shell-parse.ts";
 
 export type ShellVerdict = "safe" | "escalate";
 
@@ -79,74 +96,33 @@ export interface ShellEvidence {
 	 */
 	readOnlyOutside: boolean;
 	/**
-	 * True when the ONLY reason this escalated is an in-project filesystem
-	 * mutation/deletion — every path is inside the working directory and resolved,
-	 * nothing touches the network, no credential/execution-primitive path, no
-	 * unknown command, interpreter, glob, xargs, `cd`, or unmodelled syntax. The
-	 * containment gate uses this to decide whether a git-recoverability check may
-	 * clear the command (see auto-mode/recoverability.ts). Never true when the
-	 * verdict is "safe" (nothing escalated) — it only qualifies an escalation.
+	 * True when every reason this escalated is a read the classifier should
+	 * see: an outside-cwd read, or a read that names a credential or an
+	 * execution-primitive path (`find -name '*.pem'`, `cat Makefile`). No write,
+	 * mutation, network, unknown command or unmodelled syntax, so nothing here
+	 * can write a file. Never true for a "safe" verdict.
 	 */
-	containedNonNetwork: boolean;
+	readsOnly: boolean;
 	/**
-	 * True for a whole-working-tree destructive git op (`git reset --hard`), whose
-	 * recoverability is judged against the whole tree's cleanliness rather than
-	 * named paths.
+	 * True when the ONLY reason this escalated is Claude Code's acceptEdits file
+	 * commands (`ACCEPT_EDITS_OPTIONS`) on the working space — every path is
+	 * inside the working directory (or a `writableRoots` entry) and resolved,
+	 * nothing touches the network, no credential/execution-primitive path, no
+	 * unknown command, interpreter, glob, xargs, `cd`, or unmodelled syntax.
+	 * Never true when the verdict is "safe" (nothing escalated) — it only
+	 * qualifies an escalation.
 	 */
-	wholeTree: boolean;
+	containedNonNetwork: boolean;
 }
 
-/** Commands that read and do not write, and are safe to fast-path. */
-const READ_ONLY_COMMANDS = new Set([
-	"basename",
-	"cat",
-	"cksum",
-	"column",
-	"comm",
-	"cut",
-	"date",
-	"diff",
-	"dirname",
-	"du",
-	"echo",
-	"false",
-	"file",
-	"fold",
-	"head",
-	"hostname",
-	"id",
-	"join",
-	"jq",
-	"ls",
-	"md5sum",
-	"nl",
-	"od",
-	"paste",
-	// `printenv` and a bare `env` are NOT read-only for this purpose: they dump
-	// the process environment, provider keys included (Claude Code removed both
-	// from its read-only list for the same reason).
-	"printf",
-	"pwd",
-	"readlink",
-	"realpath",
-	"rev",
-	"rg",
-	"sha1sum",
-	"sha256sum",
-	"shasum",
-	"sort",
-	"stat",
-	"tail",
-	"tr",
-	"tree",
-	"true",
-	"uname",
-	"uniq",
-	"wc",
-	"which",
-	"whoami",
-	"yes",
-]);
+/**
+ * Commands that read and do not write, and are safe to fast-path — each only
+ * with the options its table in read-only-options.ts names. `printenv` and a
+ * bare `env` are not here: they dump the process environment, provider keys
+ * included (Claude Code removed both from its read-only list for the same
+ * reason).
+ */
+const READ_ONLY_COMMANDS = new Set(Object.keys(READ_ONLY_SPECS));
 
 /**
  * Read-only commands that take no file operands, so a path-looking positional
@@ -174,32 +150,83 @@ const NO_FILE_OPERANDS = new Set([
 /**
  * `grep` and friends take a pattern before their paths, so the first positional
  * is not a path token. Tracked separately to avoid classifying a regex as a file.
+ * `ag` and `ack` are not fast-pathed at all: both take a pager program, and ack
+ * reads a project `.ackrc` this check never sees.
  */
-const PATTERN_FIRST_COMMANDS = new Set(["grep", "egrep", "fgrep", "rg", "ag", "ack"]);
+const PATTERN_FIRST_COMMANDS = new Set(["grep", "egrep", "fgrep", "rg"]);
+
+interface WrapperSpec {
+	/** Options whose next word is a harmless value, skipped in both readings. */
+	values?: readonly string[];
+	/**
+	 * Options whose value changes where or how the payload runs (`env -C`,
+	 * `time -o`, `script -T`). The strict reading leaves the value in command
+	 * position, so the command escalates; the wide reading skips it.
+	 */
+	unsafeValues?: readonly string[];
+	/** Options whose value is a command line of its own (`flock -c`, `env -S`): the wide reading returns it. */
+	scripts?: readonly string[];
+	/** The first operand is a file, not the command (`flock LOCK cmd`, `script LOG cmd`). */
+	fileFirst?: boolean;
+	/** The first operand is a duration (`timeout 30 cmd`). */
+	durationFirst?: boolean;
+	/**
+	 * Whether an in-project payload stays contained (`containedNonNetwork`).
+	 * xargs takes its targets from stdin, and flock and script write the
+	 * file they are given, which nothing write-checks.
+	 */
+	contained: boolean;
+	/** Peeled only for deny/ask forms; the pre-gate treats it as an unknown command. */
+	denyFormsOnly?: boolean;
+}
 
 /**
- * Commands that run whatever follows them. The original only knew three of
- * these and never looked past them, so `env rm -rf ~/Desktop` classified as a
- * harmless `env` (review finding N5). Every one of these is peeled and the
- * payload command is classified instead.
+ * Commands that run whatever follows them, and how each one takes its own
+ * options. The original only knew three and never looked past them, so `env
+ * rm -rf ~/Desktop` classified as a harmless `env` (review finding N5); one
+ * shared value-option list later read `setsid -c` (a flag) and `stdbuf -o 1M`
+ * wrong, so the real command slipped past deny rules
+ * (PREGATE-REVIEW-2026-09-23 P6). `sudo`/`doas` are peeled for deny forms
+ * only: the pre-gate peeling them would clear `sudo rm` as a contained delete.
  */
-const TRANSPARENT_WRAPPERS = new Set([
-	"command",
-	"env",
-	"flock",
-	"ionice",
-	"nice",
-	"nohup",
-	"script",
-	"setsid",
-	"stdbuf",
-	"time",
-	"timeout",
-	"xargs",
-]);
-
-/** Options of wrapper commands that consume the following token as a value. */
-const WRAPPER_VALUE_OPTIONS = new Set(["-u", "-c", "-n", "-I", "-L", "-P", "--signal", "-s", "-k"]);
+const WRAPPERS: Record<string, WrapperSpec> = {
+	// `builtin cd x` runs the builtin `cd` (PR #12 review: it hid a `cd` from the worktree guard).
+	builtin: { contained: true },
+	// Runs its argument as the command of that name (`busybox rm x`).
+	busybox: { contained: false, denyFormsOnly: true },
+	caffeinate: { values: ["-t", "-w"], contained: true, denyFormsOnly: true },
+	command: { contained: true },
+	doas: { values: ["-u", "-a"], unsafeValues: ["-C"], contained: false, denyFormsOnly: true },
+	exec: { values: ["-a"], contained: false, denyFormsOnly: true },
+	env: { values: ["-u", "--unset"], unsafeValues: ["-C", "--chdir"], scripts: ["-S", "--split-string"], contained: true },
+	flock: { values: ["-w", "--timeout", "-E", "--conflict-exit-code"], scripts: ["-c", "--command"], fileFirst: true, contained: false },
+	ionice: { values: ["-c", "--class", "-n", "--classdata"], contained: true },
+	nice: { values: ["-n", "--adjustment"], contained: true },
+	nohup: { contained: true },
+	script: {
+		values: ["-t", "-E", "--echo", "-m", "--logging-format"],
+		unsafeValues: ["-T", "--log-timing", "-I", "--log-in", "-O", "--log-out", "-B", "--log-io"],
+		scripts: ["-c", "--command"],
+		fileFirst: true,
+		contained: false,
+	},
+	setsid: { contained: true },
+	stdbuf: { values: ["-i", "-o", "-e", "--input", "--output", "--error"], contained: true },
+	sudo: {
+		values: ["-u", "-g", "-h", "-p", "-r", "-t", "-U", "-T", "-a", "--user", "--group", "--host", "--prompt", "--role", "--type", "--other-user", "--command-timeout", "--auth-type"],
+		unsafeValues: ["-C", "-D", "-R", "--close-from", "--chdir", "--chroot"],
+		contained: false,
+		denyFormsOnly: true,
+	},
+	time: { values: ["-f", "--format"], unsafeValues: ["-o", "--output"], contained: true },
+	timeout: { values: ["-s", "--signal", "-k", "--kill-after"], durationFirst: true, contained: true },
+	watch: { values: ["-n", "--interval", "-q", "--equexit"], contained: false, denyFormsOnly: true },
+	xargs: {
+		values: ["-I", "-L", "-n", "-P", "-s", "-E", "-d", "--delimiter", "--max-args", "--max-procs", "--max-chars", "--max-lines", "--eof"],
+		unsafeValues: ["-a", "--arg-file"],
+		contained: false,
+	},
+};
 
 /**
  * Anything here writes, deletes, or fetches-and-writes. The list is only used to
@@ -230,46 +257,44 @@ const MUTATION_COMMANDS = new Set([
 	"zip",
 ]);
 
+/** The delete/truncate commands whose targets are every positional, bare names included. */
+const DELETE_COMMANDS = new Set(["rm", "rmdir", "shred", "truncate"]);
+
 /**
- * The delete/truncate commands whose blast radius is exactly their (in-project,
- * resolved, concrete) path arguments, so an in-project use may be cleared by the
- * containment + git-recoverability gate rather than always reaching the
- * classifier. This is an *allowlist* for the "provably contained" conclusion —
- * omission is safe (the command still escalates to the classifier via the generic
- * mutation path). Overwrite/copy tools (cp, mv, dd, tee) are deliberately left
- * out for now: their destination semantics are subtler, so they keep classifying.
- * Membership here does not clear anything on its own: every target must resolve
- * inside the working directory and the recoverability check must pass.
+ * Claude Code's acceptEdits file commands (2.1.282, findings §36), with the
+ * options this check models; the only mutations that can be marked contained.
+ * Any other option, one carrying a value included (`cp -t dir`,
+ * `--target-directory=dir`, `mkdir -m`), leaves the command uncontained, as do
+ * symlink-following `cp -L`/`-H`. `sed` is on Claude Code's list but left out
+ * until its program is checked the way Claude Code checks it; Claude Code
+ * classified `sed -i '' …` anyway. This is an *allowlist* for the "provably
+ * contained" conclusion: omission only sends a command to the classifier.
  */
-const DELETE_COMMANDS = new Set(["rm", "rmdir", "shred", "truncate"]);
+const ACCEPT_EDITS_OPTIONS: Record<string, OptionSpec> = {
+	rm: table({ none: "-f -R -r -i -v -I -d --force --recursive --verbose --dir --interactive" }),
+	rmdir: table({ none: "-p -v --parents --verbose" }),
+	mkdir: table({ none: "-p -v --parents --verbose" }),
+	touch: table({ none: "-a -c -m --no-create" }),
+	cp: table({ none: "-r -R -f -i -n -p -v -a -P --recursive --force --interactive --no-clobber --verbose --archive --no-dereference" }),
+	mv: table({ none: "-f -i -n -v --force --interactive --no-clobber --verbose" }),
+};
+
+/**
+ * The operands of an acceptEdits file command, or undefined when it carries an
+ * option `ACCEPT_EDITS_OPTIONS` does not model. After `--` every word is an operand.
+ */
+function acceptEditsOperands(name: string, args: Token[]): Token[] | undefined {
+	const spec = ACCEPT_EDITS_OPTIONS[name];
+	if (!spec) return undefined;
+	const check = checkOptions(spec, args);
+	return check.ok ? check.parsed.positionals : undefined;
+}
 
 /** Glob/other shell metacharacters we cannot enumerate, so a target carrying one is not "concrete". */
 function hasGlob(token: string): boolean {
 	return /[*?\[\]]/.test(token);
 }
 
-/** `git reset --hard [ref]` — a whole-working-tree discard of uncommitted changes. */
-function isWholeTreeGitReset(args: Token[]): boolean {
-	const positionals = args.filter((token) => !token.value.startsWith("-"));
-	return positionals[0]?.value === "reset" && args.some((token) => token.value === "--hard");
-}
-
-/**
- * Whether git is being pointed at another repository or tree (`-C dir`,
- * `--git-dir[=]…`, `--work-tree[=]…`, `--namespace`, `--exec-path`). A
- * whole-tree op carrying one of these acts on THAT tree, so judging it against
- * the working directory would clear a reset of some other checkout.
- */
-function hasGitRetargetFlag(args: Token[]): boolean {
-	return args.some((token) => {
-		const value = token.value;
-		if (!value.startsWith("-")) return false;
-		if (GIT_GLOBAL_VALUE_FLAGS.has(value)) return true;
-		const eq = value.indexOf("=");
-		return eq > 0 && GIT_GLOBAL_VALUE_FLAGS.has(value.slice(0, eq));
-	});
-}
-
 /**
  * Interpreters whose *scripts* can write files the token-level pass never sees
  * (review finding N8: `awk 'BEGIN{print > "f"}'`). Their programs are not
@@ -312,32 +337,16 @@ const NETWORK_COMMANDS = new Set([
 ]);
 
 /**
- * git is **default-deny by subcommand**: only these read-only subcommands can be
- * fast-pathed, and everything else escalates. The original enumerated *mutating*
+ * git is **default-deny by subcommand and by option**: only the subcommands in
+ * `GIT_SUBCOMMAND_SPECS` (read-only-options.ts) can be fast-pathed, each only
+ * with the options its table names. The original enumerated *mutating*
  * subcommands and allowed the rest, so `git rm`, `git mv`, `git archive`,
- * `git config`, and `git update-ref` all slipped through (review finding N11).
- * Enumerating the safe set instead means a git subcommand added upstream
- * tomorrow escalates rather than being silently permitted.
+ * `git config`, and `git update-ref` all slipped through (review finding N11);
+ * until 2026-09-23 the options after an allowed subcommand were never looked
+ * at, so `git branch -D`, `git diff --output=f` and `git grep -O<prog>` passed
+ * as reads (SECURITY-REVIEW-2026-09-23 H1). `ls-remote` is not read-only: it
+ * contacts a remote.
  */
-const GIT_READ_ONLY_SUBCOMMANDS = new Set([
-	"blame",
-	"branch", // listing; mutation forms carry flags, and any flag we do not model escalates
-	"cat-file",
-	"describe",
-	"diff",
-	"grep",
-	"log",
-	"ls-files",
-	"ls-remote",
-	"ls-tree",
-	"rev-parse",
-	"shortlog",
-	"show",
-	"show-ref",
-	"status",
-	"tag", // listing only, same reasoning as branch
-]);
-
 /**
  * git global flags that take a value. `git -c k=v <sub>` can turn a read into
  * code execution (`git -c protocol.ext.allow=always clone ext::sh …` — review
@@ -346,283 +355,148 @@ const GIT_READ_ONLY_SUBCOMMANDS = new Set([
  */
 const GIT_GLOBAL_VALUE_FLAGS = new Set(["-C", "--git-dir", "--work-tree", "--namespace", "--exec-path"]);
 
-export interface Token {
-	/** The token with quotes removed and `$'…'` decoded. */
-	value: string;
-	/** True when the token was written with any quoting or expansion syntax. */
-	hadExpansion: boolean;
-}
-
-export interface Segment {
-	tokens: Token[];
-	/** Redirection targets found in this segment, in written order. */
-	redirects: string[];
-	raw: string;
-}
-
-/** Decode the escapes bash understands inside `$'…'`. */
-function decodeAnsiC(body: string): string {
-	return body.replace(/\\(n|t|r|\\|'|"|a|b|f|v|0|x[0-9a-fA-F]{1,2})/g, (match, escape: string) => {
-		switch (escape) {
-			case "n":
-				return "\n";
-			case "t":
-				return "\t";
-			case "r":
-				return "\r";
-			case "\\":
-				return "\\";
-			case "'":
-				return "'";
-			case '"':
-				return '"';
-			case "a":
-				return "\x07";
-			case "b":
-				return "\b";
-			case "f":
-				return "\f";
-			case "v":
-				return "\v";
-			case "0":
-				return "\0";
-			default:
-				return escape.startsWith("x") ? String.fromCharCode(Number.parseInt(escape.slice(1), 16)) : match;
-		}
-	});
-}
-
 /**
- * Syntax through which a command can run something other than what its
- * visible words say. The permission matcher refuses to let a prefix/wildcard
- * allow rule cover a command carrying any of it (the user approved `npm test
- * …`, not whatever `$(…)` evaluates to), and the pre-gate escalates on it.
+ * Commands that only print their arguments, so a command substitution among
+ * them is safe once the substituted command is: its output is printed, not
+ * read as an option, a path or a program (`echo "built $(date)"`). `echo`'s
+ * options only change how it prints. `printf` is not here: `printf $(echo
+ * -v) PATH ./bin` assigns a variable (PR #12 review).
  */
-export function hasInjectionSyntax(command: string): string | undefined {
-	if (/\$\(/.test(command)) return "uses command substitution $( )";
-	if (/(^|[^\\])`/.test(command)) return "uses backtick command substitution";
-	if (/[<>]\(/.test(command)) return "uses process substitution";
-	if (/\beval\b|\bexec\b/.test(command)) return "uses eval/exec";
-	if (/\|\s*(bash|sh|zsh|python|perl|node|ruby)\b/.test(command)) return "pipes into an interpreter";
-	if (/base64\s+(-d|--decode)/.test(command)) return "decodes base64, which can hide the real command";
-	return undefined;
-}
+const PURE_OUTPUT = new Set(["echo"]);
 
-/** Syntax we do not model at all; its presence alone forces escalation. */
-export function hasUnmodelledSyntax(command: string): string | undefined {
-	if (command.includes("\n")) return "spans multiple lines";
-	const injection = hasInjectionSyntax(command);
-	if (injection) return injection;
-	if (/<<</.test(command)) return "uses a here-string";
-	if (/<</.test(command)) return "uses a heredoc";
-	// Brace expansion resolves to paths we cannot enumerate (review finding N3).
-	if (/\{[^{}]*,[^{}]*\}/.test(command)) return "uses brace expansion, whose expanded paths cannot be checked";
-	if (/\$\{?[A-Za-z_]/.test(command)) return "references environment variables, whose values are unknown here";
-	return undefined;
+/** A parameter bash sets itself (`$1`, `$@`, `$$`, `${#}`), as opposed to an environment variable. */
+const SPECIAL_PARAMETER = /\$\{?[0-9@*#?$!-]/;
+
+export interface Payload {
+	command: string;
+	args: Token[];
+	/** The wrappers peeled, outermost first. */
+	peeled: string[];
+	/** Command-position words spelled with a directory (`./cat`, `bin/ls`, `/bin/rm`), as written. */
+	pathNamed: string[];
+	/** Wide reading only: command lines a wrapper option runs (`flock -c '…'`, `env -S '…'`). */
+	scripts: string[];
 }
 
 /**
- * Split a command into pipeline/list segments and tokenize each. Unlike the
- * original, `<`, `>`, `&`, and `|` terminate a token even without surrounding
- * whitespace, so `cmd>file` and `a|b` are seen (review finding N4). An
- * unquoted newline ends a segment too (it is a command separator in bash).
+ * Peel wrappers to the command that actually runs (review finding N5).
+ *
+ * The two readings fail in opposite directions. `"strict"` (the default: the
+ * pre-gate and the guards) peels only what it fully understands, so anything
+ * else stays in command position and escalates. `"wide"` (deny/ask forms)
+ * also skips the values of options that change where the payload runs,
+ * returns the command lines wrapper options carry, and peels `sudo`/`doas`,
+ * because a deny rule should see every command a line might run.
  */
-export function parseCommand(command: string): { segments: Segment[]; parseFailed: boolean } {
-	const segments: Segment[] = [];
-	let tokens: Token[] = [];
-	let redirects: string[] = [];
-	let rawStart = 0;
-
-	let current = "";
-	let hadExpansion = false;
-	let quoted = false;
-	let inSingle = false;
-	let inDouble = false;
-	let escape = false;
-	/** Set while consuming the token that follows a redirection operator. */
-	let pendingRedirect = false;
-
-	const pushToken = () => {
-		if (!current && !quoted) return;
-		if (pendingRedirect) {
-			redirects.push(current);
-			pendingRedirect = false;
-		} else {
-			tokens.push({ value: current, hadExpansion });
-		}
-		current = "";
-		hadExpansion = false;
-		quoted = false;
-	};
-
-	/** `at` = index of the separator; `width` = its length (`&&` is 2). */
-	const pushSegment = (at: number, width = 1) => {
-		pushToken();
-		if (tokens.length > 0 || redirects.length > 0) {
-			segments.push({ tokens, redirects, raw: command.slice(rawStart, at).trim() });
-		}
-		tokens = [];
-		redirects = [];
-		rawStart = at + width;
-	};
-
-	for (let i = 0; i < command.length; i++) {
-		const ch = command[i];
-
-		if (escape) {
-			current += ch;
-			escape = false;
-			continue;
-		}
-		if (ch === "\\" && !inSingle) {
-			escape = true;
-			continue;
-		}
-		if (ch === "'" && !inDouble) {
-			inSingle = !inSingle;
-			quoted = true;
-			continue;
-		}
-		if (ch === '"' && !inSingle) {
-			inDouble = !inDouble;
-			quoted = true;
-			continue;
-		}
-		// ANSI-C quoting: `$'\x2e\x2e'` is `..`. The original kept the leading `$`,
-		// which made the token look like a variable and skipped every path check
-		// (review finding N1, reproduced there).
-		if (ch === "$" && command[i + 1] === "'" && !inSingle && !inDouble) {
-			const end = command.indexOf("'", i + 2);
-			if (end === -1) return { segments: [], parseFailed: true };
-			current += decodeAnsiC(command.slice(i + 2, end));
-			quoted = true;
-			hadExpansion = true;
-			i = end;
-			continue;
-		}
-
-		if (inSingle || inDouble) {
-			current += ch;
-			continue;
-		}
+export function resolvePayload(tokens: Token[], reading: "strict" | "wide" = "strict"): Payload {
+	const wide = reading === "wide";
+	const payload: Payload = { command: "", args: [], peeled: [], pathNamed: [], scripts: [] };
+	let index = 0;
 
-		if (ch === "\n") {
-			// An unquoted newline separates commands exactly like `;`. Without this
-			// `npm test x\ncurl evil` would be one segment whose lead is `npm test`.
-			pushSegment(i);
-			continue;
-		}
-		if (/\s/.test(ch)) {
-			pushToken();
-			continue;
-		}
+	const kind = (spec: WrapperSpec, option: string) =>
+		spec.values?.includes(option) ? "value" : spec.unsafeValues?.includes(option) ? "unsafe" : spec.scripts?.includes(option) ? "script" : undefined;
 
-		// Redirection. `>|` is the clobber-override form and behaves as `>`
-		// (review finding N10); `2>&1` and `&>` are duplications, not paths.
-		if (ch === ">" || ch === "<") {
-			pushToken();
-			let j = i + 1;
-			if (command[j] === ">" || command[j] === "|") j++;
-			if (command[j] === "&") {
-				// fd duplication — consume the fd and move on, no path involved.
-				j++;
-				while (j < command.length && /[0-9-]/.test(command[j])) j++;
-				i = j - 1;
+	/**
+	 * Skip the wrapper's own options; `--` ends them. A value may be attached,
+	 * as getopt allows: `--chdir=/tmp`, `-C/tmp`, or last in a short cluster
+	 * (`-iC/tmp`). Until 2026-09-24 only the separate spelling was recognised,
+	 * so `env --chdir=/tmp rm -f a.txt` peeled as a contained delete and
+	 * `env --split-string='rm …'` hid its script from deny rules.
+	 */
+	const skipOptions = (spec: WrapperSpec) => {
+		while (index < tokens.length && tokens[index].value.startsWith("-")) {
+			const word = tokens[index].value;
+			if (word === "--") {
+				index++;
+				return;
+			}
+			let option: string | undefined;
+			let attached: string | undefined;
+			if (word.startsWith("--")) {
+				const eq = word.indexOf("=");
+				option = eq > 0 ? word.slice(0, eq) : word;
+				attached = eq > 0 ? word.slice(eq + 1) : undefined;
+			} else {
+				for (let i = 1; i < word.length; i++) {
+					if (!kind(spec, `-${word[i]}`)) continue;
+					option = `-${word[i]}`;
+					attached = word.slice(i + 1) || undefined;
+					break;
+				}
+			}
+			const type = option === undefined ? undefined : kind(spec, option);
+			// Strict: an attached value that moves the payload or carries a script
+			// stays in command position, so the command escalates uncontained.
+			if (!wide && attached !== undefined && (type === "unsafe" || type === "script")) return;
+			index++;
+			if (type === undefined || attached !== undefined) {
+				if (wide && type === "script" && attached !== undefined) payload.scripts.push(attached);
 				continue;
 			}
-			pendingRedirect = ch === ">";
-			i = j - 1;
-			continue;
+			if (index >= tokens.length) return;
+			if (type === "value") index++;
+			else if (wide && type === "unsafe") index++;
+			else if (wide && type === "script") payload.scripts.push(tokens[index++].value);
 		}
-
-		if (ch === "|" || ch === ";" || ch === "&") {
-			// `&&`, `||`, `;`, `|`, `&` all end a segment. Any of them means the
-			// next command is separate, which is all we need to know.
-			const doubled = command[i + 1] === ch;
-			pushSegment(i, doubled ? 2 : 1);
-			if (doubled) i++;
-			continue;
-		}
-
-		current += ch;
-	}
-
-	if (escape || inSingle || inDouble) return { segments: [], parseFailed: true };
-	pushSegment(command.length);
-	return { segments, parseFailed: false };
-}
-
-/** Peel wrappers to the command that actually runs (review finding N5). */
-export function resolvePayload(tokens: Token[]): { command: string; args: Token[]; peeled: string[] } {
-	const peeled: string[] = [];
-	let index = 0;
+	};
 
 	for (;;) {
 		// Leading `VAR=value` assignments are not the command.
 		while (index < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[index].value)) index++;
-		if (index >= tokens.length) return { command: "", args: [], peeled };
+		if (index >= tokens.length) return payload;
 
+		if (/[\\/]/.test(tokens[index].value)) payload.pathNamed.push(tokens[index].value);
 		const name = commandName(tokens[index].value);
-		if (!TRANSPARENT_WRAPPERS.has(name)) {
-			return { command: name, args: tokens.slice(index + 1), peeled };
+		const spec = WRAPPERS[name];
+		if (!spec || (spec.denyFormsOnly && !wide)) {
+			payload.command = name;
+			payload.args = tokens.slice(index + 1);
+			return payload;
 		}
 
-		peeled.push(name);
+		payload.peeled.push(name);
 		index++;
-		// Step over the wrapper's own flags and their values.
-		while (index < tokens.length && tokens[index].value.startsWith("-")) {
-			const flag = tokens[index].value;
+		skipOptions(spec);
+		if (spec.fileFirst && index < tokens.length) {
 			index++;
-			if (WRAPPER_VALUE_OPTIONS.has(flag) && index < tokens.length) index++;
+			// `flock LOCK -c '…'`: options may follow the file too.
+			skipOptions(spec);
 		}
-		// `timeout 30 cmd` — a bare duration is not the payload.
-		while (index < tokens.length && /^[0-9]+[smhd]?$/.test(tokens[index].value)) index++;
+		if (spec.durationFirst && index < tokens.length && /^[0-9.]+[smhd]?$/.test(tokens[index].value)) index++;
 	}
 }
 
+/** Whether every peeled wrapper keeps an in-project payload contained (see `WrapperSpec.contained`). */
+function wrappersContained(peeled: readonly string[]): boolean {
+	return peeled.every((name) => WRAPPERS[name]?.contained);
+}
+
+/** Shells whose `-c` argument is a command line of its own. */
+export const INLINE_SCRIPT_SHELLS: ReadonlySet<string> = new Set(["sh", "bash", "zsh", "dash", "ksh", "fish"]);
+
+/** Commands that change the shell's working directory. */
+export const DIRECTORY_MOVERS: ReadonlySet<string> = new Set(["cd", "pushd", "popd"]);
+
+/** Whether a segment's command (past `time` and wrappers) changes the shell's directory. */
+export function movesDirectory(seg: Segment): boolean {
+	return DIRECTORY_MOVERS.has(resolvePayload(leadTokens(seg)).command);
+}
+
 /**
- * A segment's tokens normalised for command-position checks: subshell parens
- * stripped from the head token only (`(cd` → `cd` — a later argument may
- * legitimately begin with `(`), leading `do`/`then`/`else` keywords skipped,
- * and as many trailing `)`s stripped off the last token as `(`s were opened at
- * the head, so `(git stash)` still matches subcommand `stash`. A subshell
- * whose closing paren lands in a *different* segment (`(a && git stash)`) is
- * a known limitation — the closer is only balanced within one segment.
- * Used by the bash/worktree guard pipelines, not by the escalation analyzer.
+ * A segment's tokens from its command word on, for command-position checks.
+ * `time` is a reserved word that the grammar reads as a command, so `time
+ * { rm x; }` arrives as the words `time { rm x` (and a `}` command): a leading
+ * `time`, its `-p`, and the `{`, `(` or `!` it times are skipped. The grammar
+ * has already taken that punctuation out of every other command. Used by the
+ * guards and the deny forms, not by the escalation analyzer.
  */
 export function leadTokens(seg: Segment): Token[] {
-	const tokens = [...seg.tokens];
 	let i = 0;
-	let opened = 0;
-	for (;;) {
-		while (i < tokens.length) {
-			const value = tokens[i].value;
-			const lead = /^[({]+/.exec(value)?.[0] ?? "";
-			if (lead.length === 0) break;
-			opened += (lead.match(/\(/g) ?? []).length;
-			const stripped = value.slice(lead.length);
-			if (stripped.length === 0) {
-				i++;
-				continue;
-			}
-			tokens[i] = { ...tokens[i], value: stripped };
-			break;
-		}
-		if (i < tokens.length && ["do", "then", "else"].includes(tokens[i].value)) {
-			i++;
-			continue;
-		}
-		break;
+	while (seg.tokens[i]?.value === "time") {
+		i++;
+		while (["-p", "--", "{", "(", "!"].includes(seg.tokens[i]?.value)) i++;
 	}
-	if (opened > 0 && tokens.length > i) {
-		const last = tokens.length - 1;
-		const trailing = /\)+$/.exec(tokens[last].value)?.[0];
-		if (trailing) {
-			const strip = Math.min(trailing.length, opened);
-			tokens[last] = { ...tokens[last], value: tokens[last].value.slice(0, tokens[last].value.length - strip) };
-		}
-	}
-	return tokens.slice(i);
+	return seg.tokens.slice(i);
 }
 
 /**
@@ -664,11 +538,137 @@ function looksLikePath(value: string): boolean {
 	return value.startsWith("/") || value.includes("/");
 }
 
-/** `find` actions that execute or write (review finding N7 adds the last four). */
-function findHasAction(args: Token[]): boolean {
-	return args.some(({ value }) =>
-		["-delete", "-exec", "-execdir", "-ok", "-okdir", "-fprintf", "-fls", "-fprint", "-fprint0"].includes(value),
-	);
+/** Leading assignments that change nothing a command runs or reads: locale and display only. */
+const INERT_ASSIGNMENTS = /^(LANG|LANGUAGE|LC_[A-Z]+|TZ|NO_COLOR|FORCE_COLOR|CLICOLOR|CLICOLOR_FORCE|TERM|COLUMNS|LINES)$/;
+
+/**
+ * Whether an inert variable's VALUE keeps it inert. libc reads a file named by
+ * `TZ=:/path` or `TZ=/path`, and a locale name with a `/` is a path too, so
+ * only plain names pass: a zone name made of plain segments (`Asia/Tokyo`,
+ * read from the system zoneinfo) for TZ, and no `/` at all for the rest
+ * (PREGATE-REVIEW-2026-09-23 P4).
+ */
+function isInertValue(name: string, value: string): boolean {
+	if (name === "TZ") return /^([A-Za-z0-9_+-]+(\/[A-Za-z0-9_+-]+)*)?$/.test(value);
+	return /^[A-Za-z0-9_.,@:+-]*$/.test(value);
+}
+
+/**
+ * A `~` word other than `~` and `~/…`: bash expands `~name` to that user's
+ * home and `~-`/`~+` to `$OLDPWD`/`$PWD`, which `toAbsolute` would read as a
+ * directory literally named `~name` inside the working directory.
+ */
+export function isUnknownTilde(value: string): boolean {
+	return value.startsWith("~") && value !== "~" && !value.startsWith("~/");
+}
+
+/**
+ * The paths a shell write must never land on, or take with it when it
+ * removes or moves a directory: protected tooling and agent configuration,
+ * the harness's `protectedDirs`, and credential and execution-primitive
+ * paths. Shared by the bash gate and the PowerShell gate (powershell-tree.ts).
+ */
+export function isGuardedWritePath(path: string, cwd: string, protectedDirs: readonly string[] = []): boolean {
+	return isProtectedPath(path, cwd) || protectedDirs.some((dir) => isWithin(dir, path)) || isSensitivePath(path) || isExecutionPrimitivePath(path);
+}
+
+/**
+ * Whether removing or moving away `resolved` (spelled `absolute`) loses what
+ * git or the gate would keep: a working root, a `.git`, a directory holding
+ * one at any depth, or a guarded path or a directory holding one (`rm -rf .`,
+ * `mv .git x`, `rm -rf vendor` over `vendor/lib/.git`, `rm -rf .claude`).
+ */
+export function removalLoses(absolute: string, resolved: string, roots: readonly string[], cwd: string, protectedDirs: readonly string[] = []): boolean {
+	const lost = (path: string) => path.split(/[\\/]/).includes(".git") || isGuardedWritePath(path, cwd, protectedDirs);
+	return roots.includes(resolved) || lost(absolute) || lost(resolved) || touchesGuardedPath(resolved, resolved, lost);
+}
+
+/** The last component of a bash path word, trailing slashes dropped (`a/b/` is `b`). */
+function bashBasename(word: string): string {
+	const trimmed = word.replace(/\/+$/, "");
+	return trimmed.slice(trimmed.lastIndexOf("/") + 1);
+}
+
+/** Whether a directory entry exists at `absolute` (a dangling symlink counts). */
+function entryExists(absolute: string): boolean {
+	try {
+		lstatSync(absolute);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Whether `resolved` (already realpath'd) is a directory. */
+function isDirectory(resolved: string): boolean {
+	try {
+		return statSync(resolved).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+const FOLLOWS_DIR_ENTRY_SYMLINKS = "reads through symbolic links inside it, which can read outside the working directory";
+
+/**
+ * A bash glob (one path component) as a RegExp: `*`, `?`, `[…]`/`[!…]`,
+ * everything else literal. Undefined when JavaScript cannot compile the
+ * bracket expression (`[z-a]`), which bash accepts and matches nothing with.
+ */
+export function globComponentRegex(glob: string): RegExp | undefined {
+	let out = "";
+	for (let i = 0; i < glob.length; i++) {
+		const ch = glob[i];
+		if (ch === "*") out += "[^/]*";
+		else if (ch === "?") out += "[^/]";
+		else if (ch === "[") {
+			// A `]` first in the set, after any `!`/`^`, is a member, not the end.
+			const negation = glob[i + 1] === "!" || glob[i + 1] === "^" ? 1 : 0;
+			const close = glob.indexOf("]", i + 2 + negation);
+			if (close === -1) {
+				out += "\\[";
+				continue;
+			}
+			let body = glob.slice(i + 1, close);
+			const negated = body.startsWith("!") || body.startsWith("^");
+			if (negated) body = body.slice(1);
+			out += `[${negated ? "^" : ""}${body.replace(/[\\\]]/g, "\\$&")}]`;
+			i = close;
+		} else out += ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	}
+	try {
+		return new RegExp(`^${out}$`);
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * The words bash expands a glob operand to, or undefined when the check cannot
+ * enumerate them: a glob in a directory component, a component starting with
+ * `.` (bash before 5.2 matches `.` and `..` with `.*` or `.?`), a bracket
+ * expression JavaScript cannot compile, or more than 2,000 matches. Only the last component is expanded, as bash would with
+ * `dotglob`, `globstar` and `nocaseglob` off (their non-interactive defaults).
+ * No match leaves the word as written, as bash does without `nullglob`.
+ */
+function expandGlob(cwd: string, pattern: string, home: string): string[] | undefined {
+	const slash = pattern.lastIndexOf("/");
+	const dirPart = slash >= 0 ? pattern.slice(0, slash) : "";
+	const leaf = slash >= 0 ? pattern.slice(slash + 1) : pattern;
+	if (!leaf || /[*?[]/.test(dirPart) || leaf.startsWith(".")) return undefined;
+	if (isUnknownTilde(dirPart)) return undefined;
+	let entries: string[];
+	try {
+		entries = readdirSync(toAbsoluteBash(cwd, slash >= 0 ? dirPart || "/" : ".", home));
+	} catch {
+		return [pattern];
+	}
+	const regex = globComponentRegex(leaf);
+	if (!regex) return undefined;
+	const matches = entries.filter((entry) => !entry.startsWith(".") && regex.test(entry));
+	if (matches.length > 2_000) return undefined;
+	if (matches.length === 0) return [pattern];
+	return matches.map((entry) => (slash >= 0 ? `${dirPart}/${entry}` : entry));
 }
 
 /** The file named by a `-o FILE` / `-oFILE` / `--output=FILE` flag, if present. */
@@ -683,41 +683,103 @@ function outputFlagTarget(args: Token[]): string | undefined {
 }
 
 /**
- * Decide git: only an explicitly read-only subcommand with no flags we cannot
- * account for is safe. Returns undefined when safe, else the reason to escalate.
+ * Decide git: only an explicitly read-only subcommand, preceded by global
+ * options from `GIT_GLOBAL_SAFE` or an in-project `-C`, and carrying only the
+ * options its table names, is safe. Returns undefined when safe, else the
+ * reason to escalate.
  */
-function gitEscalationReason(args: Token[], isDirOutsideCwd: (dir: string) => boolean): string | undefined {
+function gitEscalationReason(args: Token[], isDirOutsideCwd: (dir: string) => boolean, onFileReads: (words: Token[]) => void): string | undefined {
 	let index = 0;
 	while (index < args.length) {
 		const token = args[index].value;
 		if (!token.startsWith("-")) break;
-		// `-c key=value` can reconfigure git into executing an arbitrary helper.
-		if (token === "-c" || token.startsWith("-c=") || token === "--config-env") {
+		// `-c key=value` / `--config-env` can reconfigure git into executing an arbitrary helper.
+		if (token === "-c" || token.startsWith("-c") || token === "--config-env" || token.startsWith("--config-env=")) {
 			return "passes git -c/--config-env, which can turn a read into code execution";
 		}
-		// `--git-dir=/x` spells the same flag as `--git-dir /x`; normalise both.
+		if (token === "-C") {
+			const dir = args[index + 1]?.value;
+			// `-C` retargets git at another directory; outside the working directory
+			// the operation is no longer provably in-project (was review gap: `git
+			// -C /etc status` classified safe).
+			if (!dir || isDirOutsideCwd(dir)) return `runs git -C ${dir ?? ""}, which points outside the working directory`;
+			index += 2;
+			continue;
+		}
+		if (GIT_GLOBAL_SAFE.has(token)) {
+			index++;
+			continue;
+		}
+		// `--git-dir`, `--work-tree`, `--exec-path`, `--namespace` and every other
+		// global option can point git at a repository or configuration this check
+		// has not seen, in-project or not (SECURITY-REVIEW-2026-09-23 H2).
 		const eq = token.indexOf("=");
 		const flag = eq > 0 ? token.slice(0, eq) : token;
-		if (GIT_GLOBAL_VALUE_FLAGS.has(flag)) {
-			const value = eq > 0 ? token.slice(eq + 1) : args[index + 1]?.value;
-			// `-C`/`--git-dir`/`--work-tree` retarget git at another directory. If that
-			// directory escapes the working directory the operation is no longer
-			// provably in-project, so escalate rather than skipping the flag blindly
-			// (was review gap: `git -C /etc status` classified safe).
-			if ((flag === "-C" || flag === "--git-dir" || flag === "--work-tree") && value && isDirOutsideCwd(value)) {
-				return `runs git ${flag} ${value}, which points outside the working directory`;
-			}
-			index += eq > 0 ? 1 : 2;
-			continue;
+		const value = eq > 0 ? token.slice(eq + 1) : undefined;
+		if ((flag === "--git-dir" || flag === "--work-tree") && value !== undefined && isDirOutsideCwd(value)) {
+			return `runs git ${flag} ${value}, which points outside the working directory`;
 		}
-		index++;
+		return `passes git ${flag}, which can point git at another repository or configuration`;
 	}
-	const subcommand = args[index]?.value?.toLowerCase();
+	const subcommand = args[index]?.value;
 	if (!subcommand) return undefined; // bare `git` prints help
-	if (!GIT_READ_ONLY_SUBCOMMANDS.has(subcommand)) return `runs git ${subcommand}, which is not a read-only subcommand`;
+	const spec = GIT_SUBCOMMAND_SPECS[subcommand];
+	if (!spec) return `runs git ${subcommand}, which is not a read-only subcommand`;
+	const check = checkOptions(spec, args.slice(index + 1));
+	if (!check.ok) return `runs git ${subcommand} and ${check.reason}`;
+	if (!gitOperandsAllowed(subcommand, check.parsed)) {
+		return `runs git ${subcommand} with an operand and no --list, which creates a ref`;
+	}
+	if (GIT_FILE_OPERANDS.has(subcommand)) onFileReads(check.parsed.positionals);
 	return undefined;
 }
 
+/** The directory git runs in: `cwd`, then each leading `-C <dir>` in turn, as git applies them. */
+function gitWorkingDirectory(args: Token[], cwd: string, home: string): string {
+	let dir = cwd;
+	for (let index = 0; index < args.length; ) {
+		const token = args[index].value;
+		if (token === "-C") {
+			const next = args[index + 1]?.value;
+			if (next) dir = toAbsoluteBash(dir, next, home);
+			index += 2;
+		} else if (GIT_GLOBAL_SAFE.has(token)) {
+			index++;
+		} else {
+			break;
+		}
+	}
+	return dir;
+}
+
+/**
+ * Subcommands whose operands can be files git reads outside the repository.
+ * `git diff <path> <path>` goes `--no-index` by itself when either path is
+ * outside the work tree or there is no repository, and reads both files
+ * (findings §25). Every operand is read-checked, revisions included: a
+ * revision is not a path unless a file of that name exists, and one that
+ * resolves inside the working directory passes.
+ */
+const GIT_FILE_OPERANDS = new Set(["diff"]);
+
+/**
+ * For a git command the options already proved read-only: why the checkout it
+ * runs in (after every `-C`, each relative to the last) could still make it
+ * run a program (git-checkout-programs.ts), or undefined.
+ */
+function gitCheckoutReason(args: Token[], cwd: string, home: string, seen: Map<string, string | undefined>, hooks: readonly string[] = READ_HOOKS): string | undefined {
+	let dir = cwd;
+	for (let index = 0; index < args.length && args[index].value.startsWith("-"); index++) {
+		if (args[index].value === "-C" && args[index + 1]) dir = toAbsoluteBash(dir, args[++index].value, home);
+	}
+	// Memoized for one analysis only: nothing runs between its segments, but the
+	// model can rewrite `.git/config` between calls.
+	const key = `${hooks.join(",")}\0${dir}`;
+	if (!seen.has(key)) seen.set(key, checkoutGitRunsProgram(dir, home, hooks));
+	const why = seen.get(key);
+	return why && `runs git where ${why}`;
+}
+
 export interface AnalyzeInput {
 	command: string;
 	cwd: string;
@@ -737,12 +799,36 @@ export interface AnalyzeInput {
 	 * only; the write and delete checks never consult this list.
 	 */
 	readableRoots?: string[];
+	/**
+	 * REALPATH-resolved directories a write may land in besides the working
+	 * directory without leaving the working space: the workspace directories,
+	 * passed only for a model that gets Claude Code's fast paths
+	 * (permissions/matcher.ts `DecideInput.claudeCodeFastPaths`).
+	 */
+	writableRoots?: string[];
+}
+
+/**
+ * Whether this simple command's words have the pre-gate's read-only proof.
+ * Reuse the entire analyzer, including option/operand rules and git's checkout
+ * checks, rather than treating a command name as a proof. No expansions,
+ * nested commands or stdin scripts are exempted by this narrower predicate.
+ * Redirects are NOT exempted: callers must still scan them independently.
+ * Pure apart from the analyzer's existing filesystem reads.
+ */
+export function hasReadOnlyShellWords(segment: Segment, cwd: string, home: string): boolean {
+	if (segment.substitution !== undefined || segment.stdin?.length || segment.tokens.some((word) => word.dynamic || word.glob)) return false;
+	const { command, peeled, pathNamed } = resolvePayload(segment.tokens);
+	if (peeled.length || pathNamed.length || !(READ_ONLY_COMMANDS.has(command) || command === "git" || command === "find")) return false;
+	const evidence = analyzeShellCommand({ command: segment.raw, cwd, home });
+	return evidence.commands.length === 1 && evidence.writes.length === 0 && (evidence.verdict === "safe" || evidence.readsOnly);
 }
 
 /**
  * Classify a shell command. Never denies — see the module contract above.
  */
-export function analyzeShellCommand({ command, cwd, home, protectedDirs = [], readableRoots = [] }: AnalyzeInput): ShellEvidence {
+export function analyzeShellCommand({ command, cwd, home, protectedDirs = [], readableRoots = [], writableRoots = [] }: AnalyzeInput): ShellEvidence {
+	const checkoutReasons = new Map<string, string | undefined>();
 	const evidence: ShellEvidence = {
 		verdict: "safe",
 		notes: [],
@@ -754,36 +840,38 @@ export function analyzeShellCommand({ command, cwd, home, protectedDirs = [], re
 		network: [],
 		outsideReads: [],
 		readOnlyOutside: false,
+		readsOnly: false,
 		containedNonNetwork: false,
-		wholeTree: false,
 	};
 	/**
 	 * Set by any escalation reason that is NOT a bare in-project mutation — i.e.
 	 * anything meaning the command reaches outside the project or cannot be fully
 	 * accounted for. When it stays false through an escalation, the only blocker
-	 * was in-project mutation, and the containment gate may consult recoverability.
+	 * was in-project mutation (`containedNonNetwork`).
 	 */
 	let uncontained = false;
 	/** Set by any escalation that is not an outside-cwd read (see readOnlyOutside). */
 	let escalatedBeyondReads = false;
-	const escalate = (note: string, opts?: { contained?: boolean; outsideRead?: boolean }) => {
+	/** Set by any escalation that is neither an outside-cwd read nor a read naming a guarded path (see readsOnly). */
+	let escalatedBeyondNamedReads = false;
+	const escalate = (note: string, opts?: { contained?: boolean; outsideRead?: boolean; namedRead?: boolean }) => {
 		evidence.verdict = "escalate";
 		if (!opts?.contained) uncontained = true;
 		if (!opts?.outsideRead) escalatedBeyondReads = true;
+		if (!opts?.outsideRead && !opts?.namedRead) escalatedBeyondNamedReads = true;
 		if (!evidence.notes.includes(note)) evidence.notes.push(note);
 	};
 
 	const trimmed = command.trim();
 	if (!trimmed) return { ...evidence, verdict: "escalate", notes: ["empty command"] };
 
-	const unmodelled = hasUnmodelledSyntax(trimmed);
-	if (unmodelled) escalate(unmodelled);
-
-	const { segments, parseFailed } = parseCommand(trimmed);
+	const { segments, parseFailed, unavailable, unknownQuoting, complex } = parseCommand(trimmed);
 	if (parseFailed) {
-		escalate("could not be parsed (unbalanced quotes), so nothing about it is known");
+		escalate(unavailable ? `could not be parsed: ${unavailable}` : "could not be parsed as bash, so nothing about it is known");
 		return evidence;
 	}
+	if (unknownQuoting) escalate(unknownQuoting);
+	if (complex) escalate(complex);
 
 	/**
 	 * Containment is checked against the *resolved* working directory. Write
@@ -796,6 +884,8 @@ export function analyzeShellCommand({ command, cwd, home, protectedDirs = [], re
 
 	/** `cd` changes what later relative paths mean; the original never tracked it (F6/N12). */
 	let effectiveCwd = cwd;
+	/** The directory per subshell scope: a `cd` inside `$(…)` or `( … )` does not reach the parent. */
+	const cwdByScope = scopedTracker(cwd);
 
 	/**
 	 * Resolve a write-target token, record it as evidence, and escalate on any
@@ -805,9 +895,16 @@ export function analyzeShellCommand({ command, cwd, home, protectedDirs = [], re
 	 */
 	const checkWriteTarget = (token: string) => {
 		if (token === "/dev/null") return;
+		// A `~name`/`~-` target or a glob lands wherever bash expands it, which
+		// this check cannot know (SECURITY-REVIEW-2026-09-23 M2).
+		if (isUnknownTilde(token) || /[*?[]/.test(token)) {
+			evidence.writes.push({ token, absolute: token, outsideCwd: true });
+			escalate(`writes to ${token}, which bash expands to a path this check cannot resolve`);
+			return;
+		}
 		const absolute = toAbsoluteBash(effectiveCwd, token, home);
 		const resolved = resolveForContainment(absolute);
-		const outsideCwd = resolved === undefined || !isWithin(containmentRoot, resolved);
+		const outsideCwd = resolved === undefined || !(isWithin(containmentRoot, resolved) || writableRoots.some((root) => isWithin(root, resolved)));
 		evidence.writes.push({ token, absolute, resolved, outsideCwd });
 		if (resolved === undefined) {
 			escalate(`writes to ${token}, which could not be resolved to a real path`);
@@ -836,15 +933,104 @@ export function analyzeShellCommand({ command, cwd, home, protectedDirs = [], re
 		}
 	};
 
+	/**
+	 * A word a read-only command reads. It escalates when it resolves outside
+	 * the working directory and the readable roots, or onto a credential path
+	 * — judged where it RESOLVES, so an in-project symlink named `notes` that
+	 * points at a key file is the key file (SECURITY-REVIEW-2026-09-23 M1). A
+	 * `~name`/`~-` word and a glob that could reach `..` are paths bash
+	 * expands to places this check cannot see (M2); an ordinary glob is
+	 * expanded one level here and every match is judged.
+	 */
+	const escalateOutsideRead = (value: string, why: string) => {
+		if (!evidence.outsideReads.includes(value)) evidence.outsideReads.push(value);
+		escalate(`reads ${value}, ${why}`, { outsideRead: true });
+	};
+	// `base` is where the reading program resolves a relative word (git's
+	// final `-C` directory); bash still expands globs from the shell's cwd.
+	const checkRead = (word: { value: string; glob?: boolean }, base = effectiveCwd) => {
+		const value = word.value;
+		if (!value) return;
+		if (isUnknownTilde(value)) {
+			escalateOutsideRead(value, "which bash expands to a directory outside what this check can see");
+			return;
+		}
+		const targets = word.glob ? expandGlob(effectiveCwd, value, home) : [value];
+		if (targets === undefined) {
+			escalateOutsideRead(value, "a glob whose matches cannot be checked");
+			return;
+		}
+		for (const target of targets) {
+			const absolute = toAbsoluteBash(base, target, home);
+			if (!looksLikePath(target) && !entryExists(absolute)) continue;
+			const resolved = resolveForContainment(absolute);
+			if (resolved !== undefined && isSensitivePath(resolved) && !isSensitivePath(absolute)) {
+				if (!evidence.sensitivePaths.includes(value)) evidence.sensitivePaths.push(value);
+				escalate(`reads ${value}, which resolves to a credential or secret path`, { namedRead: true });
+			}
+			if (resolved !== undefined && (isWithin(containmentRoot, resolved) || readableRoots.some((root) => isWithin(root, resolved)))) continue;
+			escalateOutsideRead(value, "which is outside the working directory");
+		}
+	};
+
 	for (const segment of segments) {
+		effectiveCwd = cwdByScope.get(segment);
 		// Redirection targets are writes regardless of the command word: a bare
 		// `> file` truncates/creates it with no command at all, and `git log > file`
 		// writes it too. Check them first so the command-specific `continue`s below
 		// (cd/git) can never skip a redirect (was review gap: bare-redirect writes and
 		// read-only-command redirects were fast-pathed to "safe").
 		for (const token of segment.redirects) checkWriteTarget(token);
+		// An input redirect (`tr a b < f`) opens `f` whatever the command is, so
+		// it is read-checked even for a command that takes no file operands. A
+		// literally named credential file is checked here too: checkRead only
+		// catches one reached through a symlink, leaving the literal name to the
+		// operand scan below, which never sees `inputs` (`cat < .env`).
+		for (const word of segment.inputs) {
+			if (isSensitivePath(word.value) || isSensitivePath(toAbsoluteBash(effectiveCwd, word.value, home))) {
+				if (!evidence.sensitivePaths.includes(word.value)) evidence.sensitivePaths.push(word.value);
+				escalate(`reads ${word.value} on stdin, which is a credential or secret path`, { namedRead: true });
+			}
+			checkRead(word);
+		}
+		if (segment.unknownTarget) escalate("redirects to or from a path an expansion computes, which cannot be resolved here");
+		// `cat <<< "$TOKEN"` prints the environment's value as surely as `echo $TOKEN`.
+		if (segment.expandsIntoInput) escalate("expands a parameter into the command's input, whose value is unknown here");
+
+		// A word bash computes at run time. A parameter's value comes from the
+		// environment (`$@` is empty in a `bash -c` line, so `cat $@/etc/passwd`
+		// read as an in-project path); a substitution's output can be any words,
+		// options included. The substituted commands are segments of their own
+		// and judged below like any other.
+		const dynamicKinds = new Set(segment.tokens.map((token) => token.dynamic).filter((kind) => kind !== undefined));
+		if (dynamicKinds.has("variable")) {
+			escalate(
+				segment.tokens.some((token) => token.dynamic === "variable" && SPECIAL_PARAMETER.test(token.value))
+					? "references a shell special parameter ($1, $@, $$, …), whose value is unknown here"
+					: "references environment variables, whose values are unknown here",
+			);
+		}
 
-		const { command: name, args, peeled } = resolvePayload(segment.tokens);
+		// A leading `NAME=value` changes what the command runs or reads: git takes
+		// its repository and configuration from GIT_* variables (the same
+		// capability `git -c` is refused for), loaders and pagers from others, and
+		// a bare `PATH=./bin` segment changes which program every later word runs.
+		// Only locale and display variables are inert (SECURITY-REVIEW-2026-09-23 H2).
+		for (const token of segment.tokens) {
+			const assigned = /^([A-Za-z_][A-Za-z0-9_]*)=/.exec(token.value)?.[1];
+			if (!assigned) break;
+			const inert = INERT_ASSIGNMENTS.test(assigned) && isInertValue(assigned, token.value.slice(assigned.length + 1));
+			if (!inert) escalate(`sets ${assigned}, which can change what the command runs or reads`);
+		}
+
+		const { command: name, args, peeled, pathNamed } = resolvePayload(segment.tokens);
+		if (dynamicKinds.has("substitution") && !PURE_OUTPUT.has(name)) {
+			escalate(`passes a command substitution's output to ${name || "the shell"}, and its words are unknown here`);
+		}
+		// `diff <(git show HEAD:a) a`: bash hands a read-only command a pipe from a command judged on its own.
+		if (dynamicKinds.has("process-input") && !READ_ONLY_COMMANDS.has(name) && name !== "find") {
+			escalate(`passes a <( ) pipe to ${name || "the shell"}, which is not a read-only command`);
+		}
 		if (!name) {
 			// A wrapper with nothing to wrap is a command of its own: a bare `env`
 			// (or `env -i`, `nice`) prints the whole process environment / state.
@@ -859,12 +1045,15 @@ export function analyzeShellCommand({ command, cwd, home, protectedDirs = [], re
 			continue;
 		}
 		evidence.commands.push(name);
+		// `./cat` or `bin/timeout` runs whatever file sits there, not the command
+		// its basename names; Claude Code matches the command word exactly too.
+		for (const word of pathNamed) escalate(`runs ${word}, a program named by its path, so its name says nothing about what it does`);
 		if (peeled.length > 0) {
 			// A transparent wrapper (timeout, env, nice) leaves the payload's own
-			// arguments visible, so an in-project payload stays contained; xargs is
-			// the exception — its targets come from stdin, unknown to this check.
+			// arguments visible, so an in-project payload stays contained unless a
+			// wrapper's spec says otherwise (xargs, flock, script).
 			escalate(`wraps the real command in ${peeled.join(" → ")}, so ${name} is what actually runs`, {
-				contained: !peeled.includes("xargs"),
+				contained: wrappersContained(peeled),
 			});
 		}
 
@@ -882,11 +1071,11 @@ export function analyzeShellCommand({ command, cwd, home, protectedDirs = [], re
 			if (isSensitivePath(value) || isSensitivePath(absolute)) {
 				// The *original* token, never the resolved/expanded form (N18).
 				if (!evidence.sensitivePaths.includes(value)) evidence.sensitivePaths.push(value);
-				escalate(`names ${value}, which is a credential or secret path`);
+				escalate(`names ${value}, which is a credential or secret path`, { namedRead: true });
 			}
 			if (isExecutionPrimitivePath(absolute)) {
 				if (!evidence.executionPrimitives.includes(value)) evidence.executionPrimitives.push(value);
-				escalate(`touches ${value}, whose contents execute later without further approval`);
+				escalate(`touches ${value}, whose contents execute later without further approval`, { namedRead: true });
 			}
 		}
 
@@ -894,33 +1083,47 @@ export function analyzeShellCommand({ command, cwd, home, protectedDirs = [], re
 			const target = args.find((token) => !token.value.startsWith("-"))?.value;
 			if (target) {
 				effectiveCwd = toAbsoluteBash(effectiveCwd, target, home);
+				cwdByScope.set(segment, effectiveCwd);
 				escalate(`changes directory to ${target}, so later paths in this command resolve elsewhere`);
 			}
 			continue;
 		}
 
-		if (name === "git") {
-			// `git reset --hard` is an in-project whole-tree discard: escalate, but
-			// mark it contained so the recoverability gate can clear it when the tree
-			// is clean. Any other non-read-only git subcommand is uncontained.
-			if (isWholeTreeGitReset(args)) {
-				if (hasGitRetargetFlag(args)) {
-					// The reset acts on whatever -C/--git-dir/--work-tree names, not on
-					// the working directory the recoverability judge would inspect.
-					escalate("runs git reset --hard against another tree (-C/--git-dir/--work-tree), which cannot be judged here");
-					continue;
-				}
-				evidence.wholeTree = true;
-				escalate("runs git reset --hard, which discards uncommitted changes in the working tree", {
-					contained: true,
-				});
-				continue;
+		// Bash expands a glob before the command parses its options, so a match
+		// that starts with `-` arrives as an option no table judged: with a file
+		// named `--output=victim`, `sort *` writes `victim`
+		// (AUTO-MODE-SECURITY-REVIEW-2026-09-24 H4). A glob this check cannot
+		// enumerate escalates when its expansion could start with `-`.
+		for (const token of args) {
+			if (!token.glob) continue;
+			const matches = expandGlob(effectiveCwd, token.value, home);
+			const injects = matches === undefined ? /^[-*?[]/.test(token.value) : matches.some((match) => match !== token.value && match.startsWith("-"));
+			if (injects) {
+				escalate(`passes the glob ${token.value}, which can expand to a filename starting with -, read as an option`);
+				break;
 			}
-			const reason = gitEscalationReason(args, (dir) => {
-				const resolved = resolveForContainment(toAbsoluteBash(effectiveCwd, dir, home));
-				return resolved === undefined || !isWithin(containmentRoot, resolved);
-			});
+		}
+
+		if (name === "git") {
+			const fileReads: Token[] = [];
+			const reason =
+				gitEscalationReason(
+					args,
+					(dir) => {
+						if (isUnknownTilde(dir)) return true;
+						const resolved = resolveForContainment(toAbsoluteBash(effectiveCwd, dir, home));
+						return resolved === undefined || !isWithin(containmentRoot, resolved);
+					},
+					(words) => fileReads.push(...words),
+				) ?? gitCheckoutReason(args, effectiveCwd, home, checkoutReasons);
 			if (reason) escalate(reason);
+			// git resolves a relative operand from its final `-C` directory, not
+			// the shell's: `git -C sub diff ../../x/data.txt a.txt` can climb out
+			// from `sub` where the same word stays inside from the working directory.
+			else {
+				const gitCwd = gitWorkingDirectory(args, effectiveCwd, home);
+				for (const word of fileReads) checkRead(word, gitCwd);
+			}
 			continue;
 		}
 
@@ -928,53 +1131,124 @@ export function analyzeShellCommand({ command, cwd, home, protectedDirs = [], re
 			escalate(`runs ${name}, whose script can read and write files this check cannot see`);
 		}
 
-		if (name === "find" && findHasAction(args)) {
-			escalate("uses a find action that executes commands or writes files");
-		}
-
 		const isMutation = MUTATION_COMMANDS.has(name);
 		const isDelete = DELETE_COMMANDS.has(name);
-		// A delete confined to in-project paths is what the containment gate exists
-		// to clear (subject to recoverability); any other mutation (cp/mv/tar/…)
-		// stays uncontained and reaches the classifier as before.
-		if (isMutation) escalate(`runs ${name}, which modifies the filesystem`, { contained: isDelete });
-
-		if (!isMutation && !READ_ONLY_COMMANDS.has(name) && !PATTERN_FIRST_COMMANDS.has(name) && name !== "find") {
-			escalate(`runs ${name}, which is not on the read-only allowlist`);
-		}
-
-		// A read-only command's path operands are read: one that resolves outside
-		// the working directory escalates (Claude Code asks for every read outside
-		// it — filesystem.ts — and removed env/printenv from its read-only list).
-		// Bare names (`cat notes.txt`) resolve inside the cwd and stay fast-pathed;
-		// a pattern-first command's first positional is its pattern, not a path.
-		if (!isMutation && !NO_FILE_OPERANDS.has(name)) {
-			const positionals = args.filter((token) => !token.value.startsWith("-")).map((token) => token.value);
-			// The first positional is the pattern only when no flag supplies it:
-			// with `-e PAT` / `-f FILE` (`--regexp`, `--file`) every positional is a
-			// path, and `-f`'s value is itself a file read.
-			const patternByFlag = args.some(({ value }) => /^(-[a-zA-Z]*[ef][a-zA-Z]*|--regexp(=.*)?|--file(=.*)?)$/.test(value));
-			if (PATTERN_FIRST_COMMANDS.has(name) && !patternByFlag) positionals.shift();
-			// `--file=FILE` carries its read inside the flag token.
-			for (const { value } of args) {
-				if (value.startsWith("--file=")) positionals.push(value.slice("--file=".length));
-			}
-			for (const value of positionals) {
-				if (!looksLikePath(value)) continue;
-				const resolved = resolveForContainment(toAbsoluteBash(effectiveCwd, value, home));
-				if (resolved !== undefined && (isWithin(containmentRoot, resolved) || readableRoots.some((root) => isWithin(root, resolved)))) continue;
-				if (!evidence.outsideReads.includes(value)) evidence.outsideReads.push(value);
-				escalate(`reads ${value}, which is outside the working directory`, { outsideRead: true });
+		// Claude Code's acceptEdits file commands with modelled options are the
+		// contained mutations, their targets checked below; any other mutation
+		// (tar/dd/ln/…) stays uncontained.
+		const fileOperands = acceptEditsOperands(name, args);
+		if (isMutation) escalate(`runs ${name}, which modifies the filesystem`, { contained: fileOperands !== undefined });
+
+
+		// A read-only command is proved read-only by its options, not its name:
+		// each option must be in the command's table (read-only-options.ts), so
+		// `rg --pre=<prog>`, `tree -o f` and `uniq in out` escalate
+		// (SECURITY-REVIEW-2026-09-23 H1). Its operands, and the files named by
+		// options such as `grep -f`, are then read-checked.
+		if (name === "find") {
+			const find = checkFind(args);
+			if (!find.ok) escalate(find.reason);
+			else for (const word of find.paths) checkRead(word);
+		} else if (READ_ONLY_COMMANDS.has(name)) {
+			const check = checkOptions(READ_ONLY_SPECS[name], args);
+			if (!check.ok) {
+				escalate(`runs ${name} and ${check.reason}`);
+			} else {
+				const spec = READ_ONLY_SPECS[name];
+				const operandReason = spec.operandReason?.(check.parsed.positionals);
+				if (operandReason) escalate(operandReason);
+				const operands = [...check.parsed.positionals];
+				// A pattern-first command's first operand is its pattern, unless an
+				// option (`-e PAT`, `-f FILE`) supplies it; jq's first is its program.
+				// `rg --files` lists files and takes no pattern, so every operand is a
+				// path (PREGATE-REVIEW-2026-09-23 P3).
+				const patternFirst =
+					PATTERN_FIRST_COMMANDS.has(name) && !check.parsed.seen.has("--files") && ![...check.parsed.seen].some((option) => PATTERN_OPTIONS.has(option));
+				// A glob where the pattern, program or format goes becomes that operand
+				// only in its first match; the rest are operands this check never saw
+				// (`grep *` reads every match but the first, jq's program is a filename).
+				const lead = operands[0];
+				if (lead?.glob && (patternFirst || spec.programFirst || spec.operandReason)) {
+					escalate(`runs ${name} with the glob ${lead.value} as its first operand, which ${name} does not read as a file, so the other matches go unchecked`);
+				}
+				if (patternFirst || spec.programFirst) operands.shift();
+				const reads = NO_FILE_OPERANDS.has(name) ? check.parsed.fileValues : [...operands, ...check.parsed.fileValues];
+				for (const word of reads) checkRead(word);
+				// A command that dereferences the entries of a directory operand
+				// (`diff dir1 dir2`) reads through any symlink one level inside it,
+				// which the operand's own containment check never sees (A1).
+				if (spec.dereferencesDirEntries && !spec.dereferencesDirEntries.some((option) => check.parsed.seen.has(option))) {
+					for (const word of operands) {
+						// A glob could expand to a directory this check cannot enumerate, so
+						// it escalates rather than being skipped (code-review 2026-09-24).
+						if (word.glob) {
+							escalate(`runs ${name} on the glob ${word.value}, which could name a directory that ${FOLLOWS_DIR_ENTRY_SYMLINKS}`);
+							break;
+						}
+						const resolved = resolveForContainment(toAbsoluteBash(effectiveCwd, word.value, home));
+						if (resolved !== undefined && isDirectory(resolved)) {
+							escalate(`runs ${name} on the directory ${word.value}, which ${FOLLOWS_DIR_ENTRY_SYMLINKS}`);
+							break;
+						}
+					}
+				}
 			}
+		} else if (!isMutation) {
+			escalate(`runs ${name}, which is not on the read-only allowlist`);
 		}
 
 		// The positional destinations of writing commands are the paths that get
 		// written. (Redirections were already handled at the top of the loop.)
 		const writeTokens: string[] = [];
-		if (isDelete) {
+		if (fileOperands !== undefined) {
+			// Every operand is a path, bare names included. cp and mv write their
+			// last operand and read the rest, so a source outside the working space
+			// (or a credential) is an outside read and leaves the line uncontained.
+			const copies = name === "cp" || name === "mv";
+			const reads = copies ? fileOperands.slice(0, -1) : [];
+			// The paths the write checks guard, beneath a directory operand as well
+			// as at it: they protect the files, not the directory holding them.
+			const guarded = (path: string) => isGuardedWritePath(path, effectiveCwd, protectedDirs);
+			// Removing or moving away a working root, a `.git`, or a guarded path,
+			// or a directory holding one, is never contained (`removalLoses`).
+			for (const token of name === "mv" ? reads : name === "rm" || name === "rmdir" ? fileOperands : []) {
+				const absolute = toAbsoluteBash(effectiveCwd, token.value, home);
+				const resolved = resolveForContainment(absolute);
+				if (resolved === undefined) continue;
+				if (removalLoses(absolute, resolved, [containmentRoot, ...writableRoots], effectiveCwd, protectedDirs)) {
+					escalate(`${name === "mv" ? "moves" : "removes"} ${token.value}, which is a working root, or is or holds a git repository or a protected, credential or execution-primitive path`);
+				}
+			}
+			for (const token of reads) {
+				if (isSensitivePath(toAbsoluteBash(effectiveCwd, token.value, home))) {
+					if (!evidence.sensitivePaths.includes(token.value)) evidence.sensitivePaths.push(token.value);
+					escalate(`copies or moves ${token.value}, a credential or secret path`);
+				}
+				checkRead(token);
+			}
+			const destination = copies ? fileOperands.at(-1) : undefined;
+			if (destination === undefined) {
+				writeTokens.push(...fileOperands.map((token) => token.value));
+			} else if (reads.length === 0) {
+				writeTokens.push(destination.value);
+			} else {
+				// Into an existing directory, each source lands beneath it (`cp
+				// settings.json .claude` writes `.claude/settings.json`), and a
+				// directory source brings its whole tree along.
+				const intoDirectory = destination.value.endsWith("/") || isDirectory(toAbsoluteBash(effectiveCwd, destination.value, home));
+				for (const source of reads) {
+					const target = intoDirectory ? `${destination.value.replace(/\/+$/, "")}/${bashBasename(source.value)}` : destination.value;
+					writeTokens.push(target);
+					const sourceResolved = resolveForContainment(toAbsoluteBash(effectiveCwd, source.value, home));
+					if (sourceResolved !== undefined && touchesGuardedPath(sourceResolved, toAbsoluteBash(effectiveCwd, target, home), guarded)) {
+						escalate(`${name === "cp" ? "copies" : "moves"} ${source.value} to ${target}, which puts files on a protected, credential or execution-primitive path`);
+					}
+				}
+			}
+		} else if (isDelete) {
 			// A delete's targets are every non-flag positional, bare names included
-			// (`rm notes.txt` has no slash but is still a real target the
-			// recoverability gate must see). A glob target cannot be enumerated, so
+			// (`rm notes.txt` has no slash but is still a real target that
+			// must be resolved). A glob target cannot be enumerated, so
 			// it drops out of containment — the command then reaches the classifier.
 			for (const token of args) {
 				if (token.value.startsWith("-")) continue;
@@ -1013,11 +1287,11 @@ export function analyzeShellCommand({ command, cwd, home, protectedDirs = [], re
 		for (const token of writeTokens) checkWriteTarget(token);
 	}
 
-	// The command escalated, but every reason was an in-project delete/whole-tree
-	// reset — nothing reached outside the project, the network, or the unknown. The
-	// containment gate may now consult git-recoverability (auto-mode/recoverability).
+	// The command escalated, but every reason was an acceptEdits file command on
+	// the working space: nothing reached outside it, the network, or the unknown.
 	evidence.containedNonNetwork = evidence.verdict === "escalate" && !uncontained;
 	evidence.readOnlyOutside = evidence.verdict === "escalate" && !escalatedBeyondReads;
+	evidence.readsOnly = evidence.verdict === "escalate" && !escalatedBeyondNamedReads;
 
 	return evidence;
 }