@gotgenes/pi-permission-system 35.0.2 → 35.0.3

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [35.0.3](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v35.0.2...pi-permission-system-v35.0.3) (2026-09-29)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** a quoted withdrawing option keeps a wrapped find, fd, or sort floored ([d60653a](https://github.com/gotgenes/pi-packages/commit/d60653a3e53847851e889e8133a7fdab143b8cbb)), closes [#924](https://github.com/gotgenes/pi-packages/issues/924)
+* **pi-permission-system:** sed that only prints resolves on the read surface ([274ba89](https://github.com/gotgenes/pi-packages/commit/274ba8963d899f97306bfcfd2ece10ca2720d29d)), closes [#924](https://github.com/gotgenes/pi-packages/issues/924)
+* **pi-permission-system:** sed substitutions and regex addresses resolve on the read surface ([fbbc940](https://github.com/gotgenes/pi-packages/commit/fbbc94099fd7f0b31155b73c5c46b99359482ab9)), closes [#924](https://github.com/gotgenes/pi-packages/issues/924)
+* **pi-permission-system:** awk that only reads its input resolves on the read surface ([136c739](https://github.com/gotgenes/pi-packages/commit/136c739e2025d3d47bfcfc72929533411e515232)), closes [#924](https://github.com/gotgenes/pi-packages/issues/924)
+* **pi-permission-system:** a brace-expanded argument withdraws sed's and awk's read claim ([5b38dd3](https://github.com/gotgenes/pi-packages/commit/5b38dd3fb6e87ffa011dd25a80df372a955b4696)), closes [#924](https://github.com/gotgenes/pi-packages/issues/924)
+
+### Documentation
+
+* **pi-permission-system:** document sed and awk as presumed readers ([d3d0314](https://github.com/gotgenes/pi-packages/commit/d3d0314bf1a2940db237f384d1f377f727a3ea66)), closes [#924](https://github.com/gotgenes/pi-packages/issues/924)
+* **pi-permission-system:** name brace expansion among the computed spellings ([e4fee09](https://github.com/gotgenes/pi-packages/commit/e4fee09286705c898dd211ed5618ab4c040472d1)), closes [#924](https://github.com/gotgenes/pi-packages/issues/924)
+
 ## [35.0.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v35.0.1...pi-permission-system-v35.0.2) (2026-09-28)
 
 

package/docs/configuration.md

@@ -879,12 +879,12 @@ A path token owned by one of them consults the `_read` surface alone:
 
 <!-- BEGIN PURE_READER_CORE -->
 
-`basename`, `cat`, `cd`, `diff`, `dirname`, `echo`, `egrep`, `fd`, `fgrep`, `find`, `grep`, `head`, `ls`, `pwd`, `realpath`, `rg`, `sort`, `stat`, `tail`, `wc`, `which`
+`awk`, `basename`, `cat`, `cd`, `diff`, `dirname`, `echo`, `egrep`, `fd`, `fgrep`, `find`, `grep`, `head`, `ls`, `pwd`, `realpath`, `rg`, `sed`, `sort`, `stat`, `tail`, `wc`, `which`
 
 <!-- END PURE_READER_CORE -->
 
 The bar for admission is structural, not popularity: implementation-independent read-only-ness across GNU and BSD alike, no option that redirects output to a file, and effects that do not depend on argument content.
-`awk` and `sed` are excluded because their program text and `-i` flag can write; `uniq`, `tee`, `dd`, and `split` each have a positional or option that writes a file; `file` is excluded because `-C`/`--compile` writes a `magic.mgc` file; `less` and `more` can escape to a shell; `git`, `pnpm`, and `node` are subcommand-dependent.
+`uniq`, `tee`, `dd`, and `split` each have a positional or option that writes a file; `file` is excluded because `-C`/`--compile` writes a `magic.mgc` file; `less` and `more` can escape to a shell; `git`, `pnpm`, and `node` are subcommand-dependent; `gawk` and `nawk` are not admitted.
 
 Three members are read-only **until an argument says otherwise**, and naming one of these options withdraws the claim — the token falls back to consulting both surfaces:
 
@@ -902,6 +902,25 @@ A core word counts only as a **bare basename**.
 The core cannot be extended or removed from configuration.
 If you do not trust a member of it, deny or ask on the paths themselves — an effect proof only chooses which surface answers, and never overrides the answer.
 
+##### `sed` and `awk`
+
+`sed` and `awk` can write through their script or program as well as their options (`sed 'w out'`, `awk '{print > FILENAME}'`), so a withdrawing option is not enough to guard them.
+They are read-only only when the whole command line is **proven** read-only, and anything the proof does not recognize withdraws the claim:
+
+| Command | Proven read-only when                                                                                                                                                                                                                                                            |
+| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sed`   | every option is one of `-n`, `-E`, `-r`, `-s`, `-u`, `-z` (clustered or not), `-e`/`--expression`, `--quiet`, `--silent`, `--regexp-extended`, `--separate`, `--unbuffered`, `--null-data`, `--posix`, `--debug`, and `--sandbox`, and every script uses only read-only commands |
+| `awk`   | the only options are `-F` and `-v`, and the program text holds no `>`, `\|`, `system`, or `@`                                                                                                                                                                                    |
+
+So `sed -n '1,80p' file`, `sed 's/a/b/g' file`, and `awk '{print $1}' file` read, while `sed -i …`, `sed -f script.sed …`, a script with a `w`, `r`, `e`, `a`, `i`, or `c` command, `s///w` or `s///e`, `awk -f prog.awk …`, and `awk '{print > "out"}' …` consult both surfaces.
+A long option is matched only when spelled in full, so every abbreviation (`--in`, `--qui`) withdraws the claim.
+`awk`'s check is a character scan rather than a parse, so a comparison such as `NR>=100` withdraws it too.
+
+Two more shapes withdraw the claim:
+
+- An argument whose value only the shell decides (`"$range"`, `$f`, `$(cmd)`, `-*`, `-\i`, `{-i,-n}`), wherever it sits, because it could arrive as `-i` or as the script itself.
+- A `sed` script where GNU and BSD would read different commands: a delimiter inside a bracket expression (`s/[/]/x/`), or an `-e` after the first positional.
+
 #### Wrapper transparency
 
 The [indirection-wrapper floor](#fail-closed-behavior) exists because a wrapper hides the command that should be gated.
@@ -921,7 +940,7 @@ All four of these must hold, and each is a way the floor's reason could still ap
 4. The enclosing statement provably writes no file through a redirect.
    A destination the parse cannot resolve — `> $OUT`, `> $(mktemp)` — counts against the exemption rather than for it.
 
-So `xargs grep -l foo`, `xargs wc -l`, and `find . -name '*.ts' -exec cat {} +` stop prompting under a matching `bash` allow, while `xargs rm`, `xargs sed -i`, `time pnpm test`, and `find . -exec sh -c '…' \;` still prompt.
+So `xargs grep -l foo`, `xargs wc -l`, `xargs sed -n 1p`, and `find . -name '*.ts' -exec cat {} +` stop prompting under a matching `bash` allow, while `xargs rm`, `xargs sed -i`, `time pnpm test`, and `find . -exec sh -c '…' \;` still prompt.
 
 Three things this does **not** change:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "35.0.2",
+  "version": "35.0.3",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {

package/src/access-intent/bash/awk-invocation.ts

@@ -0,0 +1,86 @@
+import type { ArgWord } from "./node-text";
+
+// ── Public surface ─────────────────────────────────────────────────────────
+
+/**
+ * Whether an `awk` invocation's arguments withdraw its read claim.
+ *
+ * The claim stands only when the command line is **proven** read-only: the
+ * only options are `-F` and `-v`, the program arrives as literal text, and
+ * that text holds none of the constructs through which a POSIX or GNU awk
+ * program writes a file or runs a command.
+ *
+ * The program check is a character scan, not a parse, so it over-retracts:
+ * `NR>=100` withdraws the claim because `>` is also `print >`'s redirect.
+ * That costs relief and never safety — a withdrawn claim consults both
+ * surfaces, exactly as `awk` did before it joined the core.
+ *
+ * A computed word withdraws the claim wherever it sits, since it could spell
+ * `-f` or the program itself.
+ */
+export function awkWithdrawsReadClaim(argWords: readonly ArgWord[]): boolean {
+  if (argWords.some(({ computed }) => computed)) return true;
+  const program = selectProgram(argWords.map(({ value }) => value));
+  return program === null || !provesReadOnlyProgram(program);
+}
+
+// ── The option walk ────────────────────────────────────────────────────────
+
+/** `-F sep` and `-v name=value`: the options every awk shares that cannot write. */
+const VALUE_OPTIONS: ReadonlySet<string> = new Set(["-F", "-v"]);
+
+/**
+ * The program text an argument list hands `awk`, or `null` when the list
+ * cannot be proven to hand it only that.
+ *
+ * The program is the first positional. An option-looking word anywhere else
+ * withdraws the claim: whether an awk stops reading options at the program
+ * varies by implementation, so a trailing `-f` is not assumed to be a file.
+ */
+function selectProgram(values: readonly string[]): string | null {
+  let program: string | null = null;
+  let optionsEnded = false;
+  for (let i = 0; i < values.length; i++) {
+    const value = values[i];
+    if (optionsEnded || !isOptionWord(value)) {
+      program ??= value;
+      continue;
+    }
+    if (program !== null) return null;
+    if (value === "--") {
+      optionsEnded = true;
+      continue;
+    }
+    if (VALUE_OPTIONS.has(value)) {
+      if (i + 1 >= values.length) return null;
+      i++;
+      continue;
+    }
+    if (!isAttachedValueOption(value)) return null;
+  }
+  return program;
+}
+
+function isOptionWord(value: string): boolean {
+  return value.startsWith("-") && value !== "-";
+}
+
+/** `-F:` or `-vn=3`: an allowed option carrying its value in the same word. */
+function isAttachedValueOption(value: string): boolean {
+  return VALUE_OPTIONS.has(value.slice(0, 2)) && value.length > 2;
+}
+
+// ── The program scan ───────────────────────────────────────────────────────
+
+/**
+ * Text whose presence means the program may write a file or run a command.
+ *
+ * `>` covers `print >` and `>>`; `|` covers a pipe to or from a command and
+ * gawk's `|&` coprocess; `system` covers `system()`; `@` covers gawk's
+ * `@include`, `@load`, and indirect function calls.
+ */
+const WRITE_CAPABLE_TEXT: readonly string[] = [">", "|", "system", "@"];
+
+function provesReadOnlyProgram(program: string): boolean {
+  return !WRITE_CAPABLE_TEXT.some((text) => program.includes(text));
+}

package/src/access-intent/bash/command-effects.ts

@@ -1,4 +1,7 @@
 import { type TokenEffect, UNPROVEN_EFFECT } from "#src/access-intent/effect";
+import { awkWithdrawsReadClaim } from "./awk-invocation";
+import type { ArgWord } from "./node-text";
+import { sedWithdrawsReadClaim } from "./sed-invocation";
 
 // ── Public surface ─────────────────────────────────────────────────────────
 
@@ -22,18 +25,16 @@ import { type TokenEffect, UNPROVEN_EFFECT } from "#src/access-intent/effect";
  */
 export function proveCommandEffect(
   headWord: string,
-  argWords: readonly string[],
+  argWords: readonly ArgWord[],
 ): TokenEffect {
   if (!isBareCoreWord(headWord)) return UNPROVEN_EFFECT;
-  const guard = RETRACTION_GUARDS.get(headWord);
-  if (guard && argWords.some((word) => retractsClaim(word, guard))) {
-    return RETRACTED_EFFECT;
-  }
+  const withdrawsClaim = RETRACTION_GUARDS.get(headWord);
+  if (withdrawsClaim?.(argWords)) return RETRACTED_EFFECT;
   return CORE_READ_EFFECT;
 }
 
 /**
- * The frozen v1 pure-reader core: 21 command words that are read-only for any
+ * The pure-reader core: the command words that are read-only for any
  * arguments, in any implementation.
  *
  * Exported so `docs/configuration.md`'s published roster is held to it by a
@@ -118,8 +119,7 @@ interface CoreAdmission {
  *
  * | Word                                            | Why not                                                        |
  * | ----------------------------------------------- | -------------------------------------------------------------- |
- * | `awk`, `gawk`, `nawk`                           | The program text can `print > "file"` — not stable under args  |
- * | `sed`                                           | `-i` is in-place, and BSD needs a separate argument where GNU attaches one, so the guard is dialect-variant |
+ * | `gawk`, `nawk`                                  | Their own dialects' options are unaudited; `awk` is guarded instead |
  * | `uniq`                                          | `uniq IN OUT` writes its second positional                     |
  * | `tee`, `dd`, `split`, `csplit`, `xxd`, `tree`, `curl`, `wget` | Each has a positional or option that writes a file |
  * | `less`, `more`                                  | Interactive shell escape (`!cmd`) and `LESSOPEN` preprocessing |
@@ -160,6 +160,16 @@ function coreAdmissions(): readonly CoreAdmission[] {
       reason:
         "Read-only until an argument says otherwise — see RETRACTION_GUARDS",
     },
+    {
+      words: ["sed"],
+      reason:
+        "Read-only until the command line says otherwise: an allowlist proof over its options and script — see sed-invocation.ts",
+    },
+    {
+      words: ["awk"],
+      reason:
+        "Read-only until the command line says otherwise: an allowlist proof over its options and program text — see awk-invocation.ts",
+    },
   ];
 }
 
@@ -189,18 +199,35 @@ interface RetractionGuard {
 }
 
 /**
- * The three guarded words and what withdraws each one's claim.
+ * Whether a guarded word's arguments withdraw its read claim.
  *
- * All three were chosen because their write options spell identically in GNU
- * and BSD — which is exactly why `sed` is excluded outright rather than
- * guarded. `find`'s options are single-dash long words that never cluster, so
- * they match as exact words; `sort`'s only short option containing `o` is `-o`
- * itself, so the cluster rule cannot over-retract there.
+ * Each guarded word owns its own predicate, so a word whose proof needs more
+ * than option spellings can supply one without widening the option shape.
  */
-const RETRACTION_GUARDS: ReadonlyMap<string, RetractionGuard> = new Map([
+type ClaimWithdrawal = (argWords: readonly ArgWord[]) => boolean;
+
+/** A withdrawal decided by option spellings alone: any argument naming one. */
+function optionGuard(guard: RetractionGuard): ClaimWithdrawal {
+  return (argWords) =>
+    argWords.some(({ value }) => retractsClaim(value, guard));
+}
+
+/**
+ * The guarded words and what withdraws each one's claim.
+ *
+ * `find`, `fd`, and `sort` are guarded by option spellings alone, chosen
+ * because their write options spell identically in GNU and BSD. `sed` needs a
+ * proof over its script too, since a `w` command writes whatever its options
+ * say, and `awk` a proof over its program, since `print >` does the same — so
+ * each owns a predicate of its own. `find`'s options are single-dash long
+ * words that never cluster, so they match as exact words; `sort`'s only short
+ * option containing `o` is `-o` itself, so the cluster rule cannot
+ * over-retract there.
+ */
+const RETRACTION_GUARDS: ReadonlyMap<string, ClaimWithdrawal> = new Map([
   [
     "find",
-    {
+    optionGuard({
       exactWords: new Set([
         "-exec",
         "-execdir",
@@ -212,22 +239,24 @@ const RETRACTION_GUARDS: ReadonlyMap<string, RetractionGuard> = new Map([
         "-fprintf",
         "-fls",
       ]),
-    },
+    }),
   ],
   [
     "fd",
-    {
+    optionGuard({
       longStems: new Set(["--exec", "--exec-batch"]),
       shortLetters: new Set(["x", "X"]),
-    },
+    }),
   ],
   [
     "sort",
-    {
+    optionGuard({
       longStems: new Set(["--output"]),
       shortLetters: new Set(["o"]),
-    },
+    }),
   ],
+  ["sed", sedWithdrawsReadClaim],
+  ["awk", awkWithdrawsReadClaim],
 ]);
 
 // ── Private helpers ────────────────────────────────────────────────────────

package/src/access-intent/bash/command-enumeration.ts

@@ -1,5 +1,6 @@
 import type { BashCommandContext, FloorExemption } from "#src/types";
 import { EXECUTION_HOST_TYPES, forEachExecutionIn } from "./nested-execution";
+import { readArgWord } from "./node-text";
 import { parseUnresolvedWithin } from "./parse-health";
 import type { TSNode } from "./parser";
 import { REDIRECT_NODE_TYPES, redirectMayWriteFile } from "./redirect-analysis";
@@ -284,7 +285,11 @@ export function collectSalvagedCommands(node: TSNode): BashCommand[] {
 export function inlineShellPayloadNode(command: TSNode): TSNode | null {
   const nodes = commandWordNodes(command);
   const index = inlineShellPayloadIndex(
-    nodes.map((node) => ({ text: node.text, offset: node.startIndex })),
+    nodes.map((node) => ({
+      ...readArgWord(node),
+      text: node.text,
+      offset: node.startIndex,
+    })),
   );
   return index === -1 ? null : (nodes.at(index) ?? null);
 }
@@ -490,7 +495,7 @@ function readCommandUnit(node: TSNode): {
   let previous: TSNode | undefined;
   for (const word of nodes) {
     if (previous) text += gapBetween(node, previous, word, redirects);
-    words.push({ text: word.text, offset: text.length });
+    words.push({ ...readArgWord(word), text: word.text, offset: text.length });
     text += word.text;
     previous = word;
   }

package/src/access-intent/bash/node-text.ts

@@ -27,6 +27,82 @@ export const ARG_NODE_TYPES = new Set([
   "raw_string",
 ]);
 
+/**
+ * One argument as the program receives it, and whether that is knowable.
+ *
+ * A capability proof must read the value after quote removal, since `'-o'` and
+ * `-o` reach `sort` identically, and must know when the value is computed,
+ * since a word only the shell decides can spell any option at all.
+ */
+export interface ArgWord {
+  /** The string the shell passes after quote removal ({@link resolveNodeText}). */
+  readonly value: string;
+  /**
+   * Whether `value` may differ from what the program receives: a part only
+   * running the command decides ({@link hasComputedPart}), or a spelling the
+   * shell rewrites before the program sees it — an escape, a glob, a brace
+   * expansion, an ANSI-C string — which {@link resolveNodeText} passes through as written.
+   */
+  readonly computed: boolean;
+}
+
+/** Read an argument node into the word the program receives. */
+export function readArgWord(node: TSNode): ArgWord {
+  return {
+    value: resolveNodeText(node),
+    computed: hasComputedPart(node) || !isSpelledExactly(node),
+  };
+}
+
+/**
+ * Whether {@link resolveNodeText} returns exactly the string the shell passes.
+ *
+ * Answers `false` for any node type it does not know, which is the
+ * fail-closed direction for a caller proving what a word cannot be.
+ */
+function isSpelledExactly(node: TSNode): boolean {
+  switch (node.type) {
+    case "raw_string":
+      return true;
+    case "word":
+      return !SHELL_REWRITTEN_CHARACTERS.test(node.text);
+    case "string_content":
+      return !node.text.includes("\\");
+    case "simple_expansion":
+    case "expansion":
+      return resolvePlainVariableExpansion(node) !== null;
+    case "string":
+      return childrenSpelledExactly(node);
+    case "concatenation":
+      // The grammar splits `{-i,-n}` into plain words, so the expansion is
+      // visible only across the whole concatenation's text.
+      return !BRACE_EXPANSION.test(node.text) && childrenSpelledExactly(node);
+    default:
+      return false;
+  }
+}
+
+/** A `"` delimiter is spelled exactly; every named child must be too. */
+function childrenSpelledExactly(node: TSNode): boolean {
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child || child.type === '"') continue;
+    if (!isSpelledExactly(child)) return false;
+  }
+  return true;
+}
+
+/** An escape, or a glob the shell may expand into other words. */
+const SHELL_REWRITTEN_CHARACTERS = /[\\*?[]/;
+
+/**
+ * A brace the shell expands: one holding a `,` or a `..` range.
+ *
+ * An empty `{}` is left alone by bash, which is why `find -exec … {} +` keeps
+ * its placeholder as written.
+ */
+const BRACE_EXPANSION = /\{[^}]*(,|\.\.)[^}]*\}/;
+
 /**
  * Whether an argument node's value is decided at run time: it contains a
  * command or process substitution, an arithmetic expansion, or a variable

package/src/access-intent/bash/sed-invocation.ts

@@ -0,0 +1,471 @@
+import type { ArgWord } from "./node-text";
+
+// ── Public surface ─────────────────────────────────────────────────────────
+
+/**
+ * Whether a `sed` invocation's arguments withdraw its read claim.
+ *
+ * The claim stands only when the whole command line is **proven** read-only:
+ * every option is one the allowlist knows, and every script parses under a
+ * grammar that admits no command able to write a file or run one. Anything
+ * the walk does not recognize withdraws the claim, so an unknown option or
+ * command costs one ask rather than a missed write.
+ *
+ * A computed word withdraws the claim wherever it sits: GNU `sed` permutes
+ * options, so even a trailing `"$f"` can arrive as `-i`.
+ *
+ * The walk never needs to know which `sed` is installed. Where GNU and BSD
+ * would read the same argument list differently — an `-e` after the first
+ * positional, which GNU takes as a script and BSD as a file — it withdraws.
+ */
+export function sedWithdrawsReadClaim(argWords: readonly ArgWord[]): boolean {
+  if (argWords.some(({ computed }) => computed)) return true;
+  const scripts = selectScripts(argWords.map(({ value }) => value));
+  if (scripts === null) return true;
+  return !scripts.every(provesReadOnlyScript);
+}
+
+// ── The option walk ────────────────────────────────────────────────────────
+
+/** Short options that take no argument and cannot write: `-n -E -r -s -u -z`. */
+const FLAG_LETTERS: ReadonlySet<string> = new Set([
+  "n",
+  "E",
+  "r",
+  "s",
+  "u",
+  "z",
+]);
+
+/**
+ * Long options that take no argument and cannot write, matched exactly.
+ *
+ * Abbreviations are deliberately absent: GNU accepts `--qui` for `--quiet`
+ * and `--in` for `--in-place` alike, and matching whole words only is what
+ * lets every abbreviation withdraw without a prefix rule.
+ */
+const FLAG_WORDS: ReadonlySet<string> = new Set([
+  "--quiet",
+  "--silent",
+  "--regexp-extended",
+  "--separate",
+  "--unbuffered",
+  "--null-data",
+  "--posix",
+  "--debug",
+  "--sandbox",
+]);
+
+const EXPRESSION_OPTION = "--expression";
+
+/**
+ * The scripts an argument list hands `sed`, or `null` when the list cannot be
+ * proven to hand it only those.
+ *
+ * Every `-e` value is a script; with none, the first positional is. Options
+ * are recognized wherever they sit until a `--`, because GNU permutes them.
+ */
+function selectScripts(values: readonly string[]): string[] | null {
+  const scripts: string[] = [];
+  let firstPositional: string | undefined;
+  let optionsEnded = false;
+  for (let i = 0; i < values.length; i++) {
+    const value = values[i];
+    if (optionsEnded || !isOptionWord(value)) {
+      firstPositional ??= value;
+      continue;
+    }
+    if (value === "--") {
+      optionsEnded = true;
+      continue;
+    }
+    if (FLAG_WORDS.has(value)) continue;
+    const expression = expressionOf(value, values[i + 1]);
+    if (expression === null) return null;
+    // An -e after a positional is a script to GNU and a file to BSD.
+    if (expression.script !== undefined && firstPositional !== undefined) {
+      return null;
+    }
+    if (expression.script !== undefined) scripts.push(expression.script);
+    if (expression.consumesNext) i++;
+  }
+  if (scripts.length > 0) return scripts;
+  return firstPositional === undefined ? null : [firstPositional];
+}
+
+function isOptionWord(value: string): boolean {
+  return value.startsWith("-") && value !== "-";
+}
+
+/** What one option word contributes: a script, and whether it took the next word. */
+interface OptionReading {
+  readonly script?: string;
+  readonly consumesNext: boolean;
+}
+
+/**
+ * Read one option word, or `null` when it is not one the allowlist proves.
+ *
+ * A short cluster may hold only flag letters until an `e`, which ends it: the
+ * rest of the word is the script, or the next word is when nothing follows.
+ */
+function expressionOf(
+  value: string,
+  next: string | undefined,
+): OptionReading | null {
+  if (value.startsWith("--")) return longExpressionOf(value, next);
+  for (let j = 1; j < value.length; j++) {
+    const letter = value[j];
+    if (letter === "e") {
+      const attached = value.slice(j + 1);
+      if (attached !== "") return { script: attached, consumesNext: false };
+      return next === undefined ? null : { script: next, consumesNext: true };
+    }
+    if (!FLAG_LETTERS.has(letter)) return null;
+  }
+  return { consumesNext: false };
+}
+
+function longExpressionOf(
+  value: string,
+  next: string | undefined,
+): OptionReading | null {
+  if (value.startsWith(`${EXPRESSION_OPTION}=`)) {
+    return {
+      script: value.slice(EXPRESSION_OPTION.length + 1),
+      consumesNext: false,
+    };
+  }
+  if (value !== EXPRESSION_OPTION || next === undefined) return null;
+  return { script: next, consumesNext: true };
+}
+
+// ── The script grammar ─────────────────────────────────────────────────────
+
+/**
+ * Commands that take no argument and neither write a file nor run a command.
+ *
+ * `l`, `q`, and `Q` accept an optional number, read by the scanner.
+ */
+const READ_ONLY_COMMANDS: ReadonlySet<string> = new Set([
+  "p",
+  "P",
+  "d",
+  "D",
+  "n",
+  "N",
+  "g",
+  "G",
+  "h",
+  "H",
+  "x",
+  "=",
+  "z",
+  "F",
+  "l",
+  "q",
+  "Q",
+]);
+
+/** The commands among {@link READ_ONLY_COMMANDS} that take an optional number. */
+const NUMBERED_COMMANDS: ReadonlySet<string> = new Set(["l", "q", "Q"]);
+
+/**
+ * Whether a script is made only of commands that cannot write a file or run
+ * a command.
+ *
+ * An allowlist grammar: `w`, `W`, `r`, `R`, `e`, `v`, `a`, `i`, `c`, an `s`
+ * flag outside `g p i I m M` and digits (so `s///w` and `s///e`), and any
+ * character the scanner does not recognize end the proof.
+ */
+function provesReadOnlyScript(script: string): boolean {
+  return new ScriptScanner(script).provesReadOnly();
+}
+
+/** Flags an `s` command may carry without writing a file or running one. */
+const SUBSTITUTION_FLAGS = /[gpiImM0-9]/;
+
+/** Flags a regex address may carry: GNU's case-insensitive and multiline. */
+const ADDRESS_FLAGS: ReadonlySet<string> = new Set(["I", "M"]);
+
+/** Commands whose argument is a label running to the end of the command. */
+const LABEL_COMMANDS: ReadonlySet<string> = new Set(["b", "t", "T", ":"]);
+
+/** How an address position read: nothing there, an address, or a malformed one. */
+type AddressReading = "none" | "read" | "invalid";
+
+/** A single left-to-right pass over one script. */
+class ScriptScanner {
+  private position = 0;
+  private openBlocks = 0;
+
+  constructor(private readonly source: string) {}
+
+  provesReadOnly(): boolean {
+    this.skipSeparators();
+    while (!this.atEnd()) {
+      if (!this.readCommand()) return false;
+      this.skipSeparators();
+    }
+    return this.openBlocks === 0;
+  }
+
+  /** One `[address[,address]][!…]command`, and what may follow it. */
+  private readCommand(): boolean {
+    if (this.peek() === "#") return this.skipComment();
+    if (!this.readAddresses()) return false;
+    this.skipBlanks();
+    while (this.peek() === "!") {
+      this.position++;
+      this.skipBlanks();
+    }
+    const command = this.peek();
+    if (command === undefined) return false;
+    this.position++;
+    if (command === "{") {
+      this.openBlocks++;
+      return true;
+    }
+    if (!this.readCommandBody(command)) return false;
+    this.skipBlanks();
+    return this.atEnd() || this.atSeparator() || this.closesBlock();
+  }
+
+  /** What follows a command letter, up to where a separator must come. */
+  private readCommandBody(command: string): boolean {
+    if (command === "}") return this.closeBlock();
+    if (command === "s") return this.readSubstitution();
+    if (command === "y") return this.readTransliteration();
+    if (LABEL_COMMANDS.has(command)) return this.readLabel(command);
+    if (!READ_ONLY_COMMANDS.has(command)) return false;
+    if (NUMBERED_COMMANDS.has(command)) {
+      this.skipBlanks();
+      this.skipDigits();
+    }
+    return true;
+  }
+
+  /** An optional address, then an optional `,` and a second one. */
+  private readAddresses(): boolean {
+    const first = this.readAddress();
+    if (first === "invalid") return false;
+    if (first === "none") return true;
+    this.skipBlanks();
+    if (this.peek() !== ",") return true;
+    this.position++;
+    this.skipBlanks();
+    return this.readSecondAddress();
+  }
+
+  /** A line number, `first~step`, `$`, `/re/`, or `\cREc`. */
+  private readAddress(): AddressReading {
+    const next = this.peek();
+    if (next === "$") {
+      this.position++;
+      return "read";
+    }
+    if (next === "/" || next === "\\") return this.readRegexAddress();
+    if (!this.skipDigits()) return "none";
+    if (this.peek() === "~") {
+      this.position++;
+      this.skipDigits();
+    }
+    return "read";
+  }
+
+  private readRegexAddress(): AddressReading {
+    if (this.peek() === "\\") this.position++;
+    const delimiter = this.takeDelimiter();
+    if (delimiter === null || !this.readRegex(delimiter)) return "invalid";
+    while (ADDRESS_FLAGS.has(this.peek() ?? "")) this.position++;
+    return "read";
+  }
+
+  /** The end of a range: an address, or GNU's `+N` / `~N`. */
+  private readSecondAddress(): boolean {
+    const sign = this.peek();
+    if (sign === "+" || sign === "~") {
+      this.position++;
+      return this.skipDigits();
+    }
+    return this.readAddress() === "read";
+  }
+
+  /** `s/regex/replacement/flags`, whose flags must not write or execute. */
+  private readSubstitution(): boolean {
+    const delimiter = this.takeDelimiter();
+    if (delimiter === null) return false;
+    if (!this.readRegex(delimiter)) return false;
+    if (!this.readLiteral(delimiter)) return false;
+    while (SUBSTITUTION_FLAGS.test(this.peek() ?? "")) this.position++;
+    return true;
+  }
+
+  /** `y/source/target/`, whose operands are character lists, not regexes. */
+  private readTransliteration(): boolean {
+    const delimiter = this.takeDelimiter();
+    if (delimiter === null) return false;
+    return this.readLiteral(delimiter) && this.readLiteral(delimiter);
+  }
+
+  /**
+   * A label, running to `;` or a newline.
+   *
+   * GNU ends a label there; BSD runs it to the newline, so it sees fewer
+   * commands than this reading does, never more. A `}` stays in the label,
+   * which leaves its block open and the proof unfinished — the reading on
+   * which the two agree least.
+   */
+  private readLabel(command: string): boolean {
+    this.skipBlanks();
+    const start = this.position;
+    while (!this.atEnd() && !this.atSeparator()) this.position++;
+    return command !== ":" || this.position > start;
+  }
+
+  private closeBlock(): boolean {
+    this.openBlocks--;
+    return this.openBlocks >= 0;
+  }
+
+  /** A `}` directly after a command ends it, as a separator would. */
+  private closesBlock(): boolean {
+    return this.peek() === "}";
+  }
+
+  private skipComment(): boolean {
+    while (!this.atEnd() && this.peek() !== "\n") this.position++;
+    return true;
+  }
+
+  /**
+   * The delimiter a regex or `s`/`y` command opens with, or `null` when it is
+   * one this grammar does not accept.
+   *
+   * A letter, digit, backslash, blank, or newline delimiter is legal to GNU in
+   * places and a trap everywhere: `\n` and `\d` stop meaning what they say.
+   */
+  private takeDelimiter(): string | null {
+    const delimiter = this.peek();
+    if (delimiter === undefined || !/[!-/:-@[-`{-~]/.test(delimiter)) {
+      return null;
+    }
+    if (delimiter === "\\") return null;
+    this.position++;
+    return delimiter;
+  }
+
+  /**
+   * A regex up to its closing delimiter, bracket expressions included.
+   *
+   * A delimiter inside a bracket expression ends the proof: BSD reads `[/]`
+   * as a bracket and GNU ends the regex at its `/`, so the two disagree about
+   * where every later section starts.
+   */
+  private readRegex(delimiter: string): boolean {
+    while (!this.atEnd()) {
+      const next = this.peek();
+      if (next === "\n") return false;
+      if (next === delimiter) {
+        this.position++;
+        return true;
+      }
+      if (next === "\\") {
+        this.position += 2;
+        continue;
+      }
+      if (next === "[") {
+        if (!this.readBracket(delimiter)) return false;
+        continue;
+      }
+      this.position++;
+    }
+    return false;
+  }
+
+  /** `[…]`, with `]` literal first and `[:class:]` / `[.x.]` / `[=x=]` inside. */
+  private readBracket(delimiter: string): boolean {
+    this.position++;
+    if (this.peek() === "^") this.position++;
+    if (this.peek() === "]") this.position++;
+    while (!this.atEnd()) {
+      const next = this.peek();
+      if (next === "]") {
+        this.position++;
+        return true;
+      }
+      if (next === delimiter || next === "\n") return false;
+      if (next === "[" && this.opensBracketClass()) {
+        if (!this.skipBracketClass(delimiter)) return false;
+        continue;
+      }
+      this.position++;
+    }
+    return false;
+  }
+
+  private opensBracketClass(): boolean {
+    const marker = this.source[this.position + 1];
+    return marker === ":" || marker === "." || marker === "=";
+  }
+
+  private skipBracketClass(delimiter: string): boolean {
+    const marker = this.source[this.position + 1];
+    const close = this.source.indexOf(`${marker}]`, this.position + 2);
+    if (close === -1) return false;
+    const body = this.source.slice(this.position + 2, close);
+    if (body.includes(delimiter)) return false;
+    this.position = close + 2;
+    return true;
+  }
+
+  /**
+   * A replacement or `y` operand up to its closing delimiter.
+   *
+   * Brackets mean nothing here, so `s/x/[]/` is the literal `[]`.
+   */
+  private readLiteral(delimiter: string): boolean {
+    while (!this.atEnd()) {
+      const next = this.peek();
+      if (next === "\n") return false;
+      if (next === delimiter) {
+        this.position++;
+        return true;
+      }
+      this.position += next === "\\" ? 2 : 1;
+    }
+    return false;
+  }
+
+  private skipSeparators(): void {
+    while (this.atSeparator() || this.isBlank(this.peek())) this.position++;
+  }
+
+  private skipBlanks(): void {
+    while (this.isBlank(this.peek())) this.position++;
+  }
+
+  /** Advance over digits; true when there was at least one. */
+  private skipDigits(): boolean {
+    const start = this.position;
+    while (/[0-9]/.test(this.peek() ?? "")) this.position++;
+    return this.position > start;
+  }
+
+  private atSeparator(): boolean {
+    const next = this.peek();
+    return next === ";" || next === "\n";
+  }
+
+  private isBlank(character: string | undefined): boolean {
+    return character === " " || character === "\t";
+  }
+
+  private atEnd(): boolean {
+    return this.position >= this.source.length;
+  }
+
+  private peek(): string | undefined {
+    return this.source[this.position];
+  }
+}

package/src/access-intent/bash/token-collection.ts

@@ -4,12 +4,15 @@ import { proveCommandEffect } from "./command-effects";
 import { EXECUTION_HOST_TYPES, forEachExecutionIn } from "./nested-execution";
 import {
   ARG_NODE_TYPES,
+  type ArgWord,
   hasComputedPart,
+  readArgWord,
   resolveNodeText,
   SKIP_SUBTREE_TYPES,
 } from "./node-text";
 import type { TSNode } from "./parser";
 import {
+  REDIRECT_NODE_TYPES,
   redirectEffectForDestination,
   redirectTargetIndex,
 } from "./redirect-analysis";
@@ -310,15 +313,20 @@ export function extractCommandWord(node: TSNode): string | undefined {
  *
  * Reads the argument nodes directly rather than the collected tokens, because
  * a guard fires on an *option* (`find -delete`) and no collector emits one.
+ *
+ * Every named child but the prefix and a hosted redirect is a word, including
+ * a bare `$opt` or `$(cmd)` outside {@link ARG_NODE_TYPES}: such a word
+ * reaches the program as an argument too, and a proof that never saw it could
+ * not know it might spell `-i`.
  */
-function commandArgumentWords(node: TSNode): string[] {
-  const words: string[] = [];
+function commandArgumentWords(node: TSNode): ArgWord[] {
+  const words: ArgWord[] = [];
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
-    if (!child) continue;
+    if (!child?.isNamed) continue;
     if (COMMAND_PREFIX_TYPES.has(child.type)) continue;
-    if (!ARG_NODE_TYPES.has(child.type)) continue;
-    words.push(resolveNodeText(child));
+    if (REDIRECT_NODE_TYPES.has(child.type)) continue;
+    words.push(readArgWord(child));
   }
   return words;
 }

package/src/access-intent/bash/wrapper-analysis.ts

@@ -10,9 +10,16 @@
  */
 
 import { proveCommandEffect } from "./command-effects";
+import type { ArgWord } from "./node-text";
 
-/** One word of a command unit: its text, and its offset into the unit's text. */
-export interface CommandWord {
+/**
+ * One word of a command unit: its source text and its offset into the unit's
+ * text, beside the value the program receives once the shell removes quotes.
+ *
+ * The source text is what unwrapping and slicing read; the value is what a
+ * capability proof reads, since `'-o'` reaches `sort` as `-o`.
+ */
+export interface CommandWord extends ArgWord {
   readonly text: string;
   readonly offset: number;
 }
@@ -172,8 +179,7 @@ export function isTransparentWrapper(
   if (unwrapped.kind === "opaque" || unwrapped.layers === 0) return false;
 
   const head = unwrapped.words.at(0)?.text ?? "";
-  const args = unwrapped.words.slice(1).map((word) => word.text);
-  return proveCommandEffect(head, args).effect === "read";
+  return proveCommandEffect(head, unwrapped.words.slice(1)).effect === "read";
 }
 
 // ── Unwrapping ───────────────────────────────────────────────────────────────
@@ -354,7 +360,7 @@ function rebase(
   const origin = words[start].offset;
   return words
     .slice(start, end)
-    .map((word) => ({ text: word.text, offset: word.offset - origin }));
+    .map((word) => ({ ...word, offset: word.offset - origin }));
 }
 
 /** True for a `NAME=value` environment prefix. */

package/src/handlers/gates/bash-path-extractor.ts

@@ -1,23 +0,0 @@
-import { BashProgram } from "#src/access-intent/bash/program";
-import type { PathNormalizer } from "#src/path/path-normalizer";
-
-/**
- * Extract paths from a bash command that resolve outside CWD.
- *
- * Thin facade over {@link BashProgram.externalAccesses}; parses the command
- * through the injected {@link PathNormalizer} (platform + cwd baked in) and
- * returns the cd-aware external paths in their lexical (as-typed) string form.
- * See `BashProgram` for the parsing and resolution semantics.
- *
- * Returns `string[]` (not `AccessPath[]`) so the large projection-correctness
- * test suite in `bash-external-directory.test.ts` can assert path values
- * without migrating to the `AccessPath` accessors.
- */
-export async function extractExternalPathsFromBashCommand(
-  command: string,
-  normalizer: PathNormalizer,
-): Promise<string[]> {
-  return (await BashProgram.parse(command, normalizer))
-    .externalAccesses()
-    .map(({ path }) => path.value());
-}