@gotgenes/pi-permission-system 27.1.1 → 27.1.3

package/CHANGELOG.md

@@ -5,6 +5,39 @@ 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).
 
+## [27.1.3](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v27.1.2...pi-permission-system-v27.1.3) (2026-08-29)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** gate commands hosted by declarations, test commands, and assignments ([dfde822](https://github.com/gotgenes/pi-packages/commit/dfde8227d3bf11de5258dcbe376dd0b8b75045e0)), closes [#742](https://github.com/gotgenes/pi-packages/issues/742)
+* **pi-permission-system:** gate commands inside a for loop's body and word list ([6e96464](https://github.com/gotgenes/pi-packages/commit/6e9646486db849afdf80819150a203d293b3847c)), closes [#742](https://github.com/gotgenes/pi-packages/issues/742)
+* **pi-permission-system:** gate commands inside control-flow bodies and function definitions ([3a2f232](https://github.com/gotgenes/pi-packages/commit/3a2f232d9c12588ea1feacf41cade0e56e66a44b)), closes [#742](https://github.com/gotgenes/pi-packages/issues/742)
+* **pi-permission-system:** project a command-name substitution's path operands ([9807d44](https://github.com/gotgenes/pi-packages/commit/9807d444b6d81526b01bc542cd4a829a1b2640c3)), closes [#742](https://github.com/gotgenes/pi-packages/issues/742)
+
+
+### Documentation
+
+* **pi-permission-system:** bound the path-slice claim on behavior, not diff footprint ([91ef5c9](https://github.com/gotgenes/pi-packages/commit/91ef5c9f2d0578fb64fe317bcddd3ec7d9418d4c)), closes [#742](https://github.com/gotgenes/pi-packages/issues/742)
+* **pi-permission-system:** commit the instrument behind Step 4's measurement ([e634c2c](https://github.com/gotgenes/pi-packages/commit/e634c2cf068340cc0deae86648330e44c2741f06)), closes [#742](https://github.com/gotgenes/pi-packages/issues/742)
+
+## [27.1.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v27.1.1...pi-permission-system-v27.1.2) (2026-08-29)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** claim no arity for awk's long forms, whose parser the bare name does not fix ([#823](https://github.com/gotgenes/pi-packages/issues/823)) ([6c8e4a0](https://github.com/gotgenes/pi-packages/commit/6c8e4a0b813d17750296cbd065aec20377c82d2a))
+* **pi-permission-system:** discharge a flag argument on whatever node type follows ([#823](https://github.com/gotgenes/pi-packages/issues/823)) ([228f6fb](https://github.com/gotgenes/pi-packages/commit/228f6fb235310b304557ec501567373e33d4cfab))
+* **pi-permission-system:** read --context per tool, whose arity differs between grep and rg ([#823](https://github.com/gotgenes/pi-packages/issues/823)) ([bba8317](https://github.com/gotgenes/pi-packages/commit/bba83175d1f9f8079cd9613412c65868e4a2fa09))
+* **pi-permission-system:** read awk's long forms only for gawk ([#823](https://github.com/gotgenes/pi-packages/issues/823)) ([52488f0](https://github.com/gotgenes/pi-packages/commit/52488f02cc902b8669f893cc1cfee090482f2e72))
+* **pi-permission-system:** recognize the long, embedded, and glued spellings of a pattern-first flag ([#823](https://github.com/gotgenes/pi-packages/issues/823)) ([ce7b65e](https://github.com/gotgenes/pi-packages/commit/ce7b65eb607cc2e6f61a6eceda1d1a9bb22aea85))
+* **pi-permission-system:** spend a pattern positional on a computed or numeric pattern ([#823](https://github.com/gotgenes/pi-packages/issues/823)) ([dce4d3f](https://github.com/gotgenes/pi-packages/commit/dce4d3f06b164f6f45df3c5550ec624f3acba896))
+
+
+### Documentation
+
+* **pi-permission-system:** record the optional-argument flag residuals ([#823](https://github.com/gotgenes/pi-packages/issues/823)) ([94e51fc](https://github.com/gotgenes/pi-packages/commit/94e51fc5a05acf3b2c4bc49479b45b0b7797b9ac))
+
 ## [27.1.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v27.1.0...pi-permission-system-v27.1.1) (2026-08-28)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "27.1.1",
+  "version": "27.1.3",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {
@@ -90,6 +90,7 @@
     "test:watch": "vitest",
     "verify:public-types": "bash scripts/verify-public-types.sh",
     "measure:core-coverage": "node scripts/measure-core-coverage.mjs",
+    "measure:statement-descent": "node scripts/measure-statement-descent.mjs",
     "measure:wrapper-transparency": "node scripts/measure-wrapper-transparency.mjs",
     "lint:md": "rumdl check *.md docs/**/*.md",
     "lint": "biome check . && eslint . && pnpm run lint:md"

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

@@ -1,6 +1,6 @@
 import {
   EXECUTION_HOST_TYPES,
-  forEachNestedExecution,
+  forEachExecutionIn,
 } from "#src/access-intent/bash/nested-execution";
 import type { TSNode } from "#src/access-intent/bash/parser";
 import { redirectMayWriteFile } from "#src/access-intent/bash/redirect-analysis";
@@ -79,7 +79,7 @@ interface UnitScope {
 /** A top-level command in the current shell, writing no file. */
 const TOP_LEVEL_SCOPE: UnitScope = { writesViaRedirect: false };
 
-// ── Command enumeration ──────────────────────────────────────────────────────
+// ── Node-type vocabulary ─────────────────────────────────────────────────────
 
 /**
  * Container node types descended into with the enclosing scope unchanged.
@@ -89,6 +89,39 @@ const TOP_LEVEL_SCOPE: UnitScope = { writesViaRedirect: false };
  */
 const COMMAND_ENUM_DESCEND = new Set(["program", "list", "pipeline"]);
 
+/**
+ * Compound statements: emitted whole, then descended for their statements.
+ *
+ * The whole emit is what keeps the #306 never-weaker invariant — the commands
+ * found inside are additional units, never a replacement.
+ *
+ * `select` parses as `for_statement` and `until` as `while_statement`, so each
+ * pair is one entry.
+ */
+const COMPOUND_STATEMENT_TYPES = new Set([
+  "if_statement",
+  "while_statement",
+  "for_statement",
+  "c_style_for_statement",
+  "case_statement",
+  "function_definition",
+  "compound_statement",
+  "negated_command",
+]);
+
+/**
+ * Syntactic groupings inside a compound statement: descended, never emitted.
+ *
+ * None of these is something anybody runs — a `do_group` is the loop body's
+ * punctuation — so emitting one would produce a `do rm $f; done` unit.
+ */
+const STATEMENT_GROUP_TYPES = new Set([
+  "do_group",
+  "case_item",
+  "elif_clause",
+  "else_clause",
+]);
+
 /**
  * Named node types abandoned during command enumeration: they are neither
  * commands nor able to host one, so nothing in their subtree ever runs.
@@ -104,6 +137,33 @@ const COMMAND_ENUM_DESCEND = new Set(["program", "list", "pipeline"]);
  */
 const COMMAND_ENUM_SKIP = new Set(["comment", "heredoc_end"]);
 
+/**
+ * Every node type the enumerator recognizes as a statement.
+ *
+ * This is the enumerator's third question, beside "is this a command?" and
+ * "can this host one?": "is this a *statement*, so that descending an enclosing
+ * compound reaches it?" A compound statement's named children are a mix —
+ * `for_statement` carries its loop variable and word list, `case_statement` its
+ * subject, `function_definition` its name — and descending all of them emits
+ * operand words as bash command units, naming `a` as the offending *command* in
+ * a prompt. Membership is what {@link descendStatementChildren} filters on.
+ */
+const STATEMENT_TYPES = new Set([
+  "command",
+  "redirected_statement",
+  "subshell",
+  "declaration_command",
+  "variable_assignment",
+  "test_command",
+  "unset_command",
+  "ERROR",
+  ...COMMAND_ENUM_DESCEND,
+  ...COMPOUND_STATEMENT_TYPES,
+  ...STATEMENT_GROUP_TYPES,
+]);
+
+// ── Command enumeration ──────────────────────────────────────────────
+
 /**
  * Enumerate the command units of a bash program, in source order.
  *
@@ -114,10 +174,14 @@ const COMMAND_ENUM_SKIP = new Set(["comment", "heredoc_end"]);
  * subshells (`( … )`) — emitting each inner command as its own unit *in
  * addition to* the enclosing command, since those inner commands really execute
  * (#306).
- * Control-flow bodies and `{ … }` brace groups are emitted whole without
- * descending (deferred).
+ * A compound statement (control flow, a function definition, a `{ … }` brace
+ * group) is emitted whole and then descended for the statements it contains,
+ * while its operand words — a loop variable, a word list, a `case` subject, a
+ * function's own name — are not commands and are left unemitted. An `ERROR`
+ * node is the one exception: its recovered structure is invented rather than
+ * observed, so the unparsed blob is emitted whole and never descended (#742).
  *
- * The enclosing command/subshell is always still emitted whole, so adding the
+ * The enclosing command/statement is always still emitted whole, so adding the
  * nested units can only ever produce a more-restrictive decision, never weaker.
  *
  * Each emitted command unit has any leading `variable_assignment` prefix
@@ -172,9 +236,33 @@ function collectCommandsInto(
     return;
   }
 
+  if (COMPOUND_STATEMENT_TYPES.has(node.type)) {
+    out.push(makeUnit(node.text, scope)); // never-weaker whole emit
+    descendStatementChildren(node, scope, out);
+    return;
+  }
+
+  if (STATEMENT_GROUP_TYPES.has(node.type)) {
+    descendStatementChildren(node, scope, out);
+    return;
+  }
+
+  if (node.type === "ERROR") {
+    // Tree-sitter's error recovery *invents* structure, so the node types
+    // inside an ERROR subtree are not evidence that anything runs: descending
+    // one turns backtick-quoted prose in an unterminated heredoc into command
+    // units. Emit the unparsed blob whole and stop (#742).
+    out.push(makeUnit(node.text, scope));
+    return;
+  }
+
   // Any other named statement (compound_statement `{ … }`, if/while/for/case,
   // function_definition): emit whole, do not descend — deferred (#306).
+  // A declaration, assignment, test, or `unset` still hosts executions that
+  // really run (`local x=$(rm y)`, `[[ $(rm x) ]]`), so those are enumerated
+  // in addition to the statement (#742).
   out.push(makeUnit(node.text, scope));
+  collectHostedCommands(node, out);
 }
 
 /** The wrapper facts a `command` node's words establish about its unit. */
@@ -291,6 +379,35 @@ function descendCommandChildren(
   }
 }
 
+/**
+ * Descend a compound statement's children, enumerating only the ones that are
+ * themselves statements.
+ *
+ * The filter is the whole difference from {@link descendCommandChildren}, whose
+ * container types (`program` / `list` / `pipeline` / `redirected_statement` /
+ * `subshell`) have nothing but statement children. Here the children are a mix,
+ * and a non-statement one is an operand word rather than something that runs.
+ *
+ * A non-statement child is not abandoned, though: `for f in $(rm x)` hosts a
+ * real execution in its word list, which is what the second branch reaches.
+ *
+ * The scope is relayed unchanged — a compound statement's body runs in the
+ * current shell, so a write established by an enclosing `redirected_statement`
+ * covers every unit beneath it (#803).
+ */
+function descendStatementChildren(
+  node: TSNode,
+  scope: UnitScope,
+  out: BashCommand[],
+): void {
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child?.isNamed) continue;
+    if (STATEMENT_TYPES.has(child.type)) collectCommandsInto(child, scope, out);
+    else collectHostedCommands(child, out);
+  }
+}
+
 /**
  * Enumerate the commands of every nested execution context in a subtree, each
  * tagged with the context it was found in.
@@ -298,9 +415,12 @@ function descendCommandChildren(
  * The traversal itself lives in `nested-execution.ts` so the bash path surface
  * shares one definition of what counts as a nested execution (#741); this
  * function supplies the command-surface interpretation of each one found.
+ *
+ * `node` may be a context outright or merely host one, so the traversal is the
+ * root-inclusive `forEachExecutionIn`.
  */
 function collectHostedCommands(node: TSNode, out: BashCommand[]): void {
-  forEachNestedExecution(node, (contextNode, context) => {
+  forEachExecutionIn(node, (contextNode, context) => {
     // A nested execution starts fresh: an enclosing statement's redirect is
     // that statement's, not the substitution's, exactly as #807 attributes a
     // nested command's path tokens to its own command.

package/src/access-intent/bash/nested-execution.ts

@@ -47,6 +47,24 @@ export const EXECUTION_HOST_TYPES: ReadonlySet<string> = new Set([
   "heredoc_body",
 ]);
 
+/**
+ * Visit every execution context `node` *is or contains*, in source order.
+ *
+ * The root-inclusive question, and the one nearly every consumer asks: a node
+ * handed in can be a substitution outright (`> $(cmd)`) or merely host one
+ * (`> ${DIR}/$(cmd)`), and both really execute. {@link forEachNestedExecution}
+ * answers the strictly-within question instead, which is what a visitor needs
+ * once it has already decided to treat a context's interior itself.
+ */
+export function forEachExecutionIn(
+  node: TSNode,
+  visit: (contextNode: TSNode, context: BashCommandContext) => void,
+): void {
+  const context = NESTED_EXECUTION_CONTEXTS.get(node.type);
+  if (context) visit(node, context);
+  else forEachNestedExecution(node, visit);
+}
+
 /**
  * Visit every nested execution context in `node`'s subtree, in source order.
  *
@@ -58,6 +76,10 @@ export const EXECUTION_HOST_TYPES: ReadonlySet<string> = new Set([
  * A substitution can nest under `command_name` (when the whole command is
  * `$(…)`), under an argument, inside a redirect destination, or inside an
  * interpolating heredoc body, so the entire subtree is searched.
+ *
+ * `node` itself is never visited, however it is typed — use
+ * {@link forEachExecutionIn} when it may *be* a context rather than merely
+ * contain one.
  */
 export function forEachNestedExecution(
   node: TSNode,

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

@@ -2,8 +2,7 @@ import { basename } from "node:path";
 import { proveCommandEffect } from "#src/access-intent/bash/command-effects";
 import {
   EXECUTION_HOST_TYPES,
-  forEachNestedExecution,
-  NESTED_EXECUTION_CONTEXTS,
+  forEachExecutionIn,
 } from "#src/access-intent/bash/nested-execution";
 import {
   ARG_NODE_TYPES,
@@ -79,10 +78,11 @@ export function collectCommandTokens(node: TSNode): PathToken[] {
   const config = commandName
     ? PATTERN_FIRST_COMMANDS.get(commandName)
     : undefined;
-  const tokens = config
-    ? collectPatternCommandTokens(node, config, effect)
-    : collectGenericCommandTokens(node, effect);
-  return [...tokens, ...collectEmbeddedOptionValues(node, effect)];
+  if (config) return collectPatternCommandTokens(node, config, effect);
+  return [
+    ...collectGenericCommandTokens(node, effect),
+    ...collectEmbeddedOptionValues(node, effect),
+  ];
 }
 
 /**
@@ -128,15 +128,12 @@ export function collectRedirectTokens(node: TSNode): PathToken[] {
  * its prose stays out of the path surface entirely.
  *
  * `node` may be a context outright (`> $(cmd)`) or merely contain one
- * (`> ${DIR}/$(cmd)`); `forEachNestedExecution` searches strictly within a
- * subtree, so the first case is checked here.
+ * (`> ${DIR}/$(cmd)`), so the traversal is the root-inclusive
+ * `forEachExecutionIn`.
  */
 function collectHostedExecutionTokens(node: TSNode): PathToken[] {
-  if (NESTED_EXECUTION_CONTEXTS.has(node.type)) {
-    return collectPathCandidateTokens(node);
-  }
   const tokens: PathToken[] = [];
-  forEachNestedExecution(node, (contextNode) => {
+  forEachExecutionIn(node, (contextNode) => {
     tokens.push(...collectPathCandidateTokens(contextNode));
   });
   return tokens;
@@ -200,6 +197,23 @@ function commandArgumentWords(node: TSNode): string[] {
   return words;
 }
 
+/**
+ * The children of a `command` node that supply no operand text of their own:
+ * its head word, and any env-var prefix assignment.
+ *
+ * Both are skipped as operands — the head word is not an argument, and a prefix
+ * assignment's value is assigned rather than accessed — but either can *host* a
+ * substitution that really runs (`$(cat /etc/shadow)`,
+ * `FOO=$(cat /etc/shadow) echo hi`), whose own operands are candidates like any
+ * other position (ADR 0009's positional invariance). The two walkers below are
+ * different state machines and so each carry their own skip, which is why the
+ * question is named here once rather than spelled twice (#742).
+ */
+const COMMAND_PREFIX_TYPES: ReadonlySet<string> = new Set([
+  "command_name",
+  "variable_assignment",
+]);
+
 /**
  * A long or short option carrying its value inline: one or two leading dashes,
  * a name containing no `=` or whitespace, then `=` and a non-empty value.
@@ -208,11 +222,11 @@ function commandArgumentWords(node: TSNode): string[] {
 const OPTION_VALUE_PATTERN = /^-{1,2}[^=\s]+=(.+)$/;
 
 /**
- * The values embedded in this command's `--opt=value` argument tokens.
+ * The values embedded in a **generic** command's `--opt=value` argument tokens.
  *
  * Read straight from the argument nodes rather than from the collected token
- * list, because a pattern-first command's collector classifies a flag and never
- * emits it — so `grep --file=/tmp/patterns` would otherwise lose the path.
+ * list, because a collector classifies a flag and never emits it — so
+ * `tar --directory=/etc` would otherwise lose the path.
  *
  * This is token *preprocessing*, not classification: the extracted value is
  * handed to the ordinary shape classifiers and existence probe, so
@@ -220,6 +234,10 @@ const OPTION_VALUE_PATTERN = /^-{1,2}[^=\s]+=(.+)$/;
  * yields a bare `json` that names nothing and is dropped. Keeping the split
  * here is what lets the projection see option-embedded paths without per-command
  * option tables (ADR 0009, #645).
+ *
+ * A pattern-first command runs the same split from inside its own walker
+ * instead, because there the flag's *role* is known: splitting blindly emits a
+ * pattern flag's value as a path candidate (#823).
  */
 function collectEmbeddedOptionValues(
   node: TSNode,
@@ -239,11 +257,64 @@ function collectEmbeddedOptionValues(
   return values;
 }
 
+/** The value embedded in a single `--opt=value` token, if it carries one. */
+function embeddedOptionValueToken(
+  text: string,
+  effect: TokenEffect,
+): PathToken[] {
+  const value = OPTION_VALUE_PATTERN.exec(text)?.[1];
+  return value === undefined ? [] : [{ token: value, effect }];
+}
+
+/**
+ * What a recognized flag's argument is, for the pattern-first walker.
+ *
+ * `script` and `script-file` mark the inline pattern positional as already
+ * supplied; `value` and `suffix` do not. Only `script-file` contributes a path
+ * candidate — the others name a pattern, a count, or a backup suffix.
+ */
+type PatternFlagRole =
+  /** Supplies the pattern/script inline (`grep -e`, `sed --expression`). */
+  | "script"
+  /** Supplies the pattern/script from a file (`grep -f`, `sed --file`). */
+  | "script-file"
+  /** Consumes a value that is neither pattern nor path (`grep -A`, `rg -g`). */
+  | "value"
+  /**
+   * Consumes the following argument only when it is empty.
+   *
+   * BSD `sed` requires a separate suffix argument (`sed -i '' 's/a/b/' f`)
+   * while GNU `sed` requires it glued (`-i`, `-i.bak`). Consuming
+   * unconditionally is right for one and eats the *script* on the other,
+   * leaving the file operand to be skipped as the inline pattern — a write
+   * target that reaches no path surface. The argument's own emptiness decides
+   * it, so the walk needs no knowledge of which sed is installed (#823).
+   *
+   * BSD also accepts a separate *non-empty* suffix (`sed -i bak 's/a/b/' f`),
+   * which this rule declines: the suffix then spends the pattern positional
+   * and the script surfaces as a candidate. The file operand still survives,
+   * so the residual is on ADR 0009's recoverable side.
+   */
+  | "suffix"
+  /**
+   * Recognized, but whose arity depends on which implementation the command's
+   * *name* resolves to — so it takes neither the following argument nor the
+   * pattern positional.
+   *
+   * `awk` is GNU awk on Fedora/RHEL, where `--file prog.awk` reads `prog.awk`,
+   * and one-true-awk or mawk elsewhere, where the long option is ignored
+   * outright and `prog.awk` is the program *text*. Asserting either arity
+   * drops a real operand on the other family, and the projection cannot see
+   * which binary the name will reach. Claiming neither over-surfaces on both
+   * — the recoverable direction — and the extra token names nothing, so the
+   * existence probe discards it. Prefer a precise role wherever the name does
+   * fix the parser: `gawk` gets the real ones (#823).
+   */
+  | "unknown-arity";
+
 interface PatternCommandConfig {
-  /** Flags that consume the next argument as a non-path value (pattern, separator, etc.) */
-  readonly argConsumingFlags: ReadonlySet<string>;
-  /** Flags that consume the next argument as a file path */
-  readonly fileConsumingFlags: ReadonlySet<string>;
+  /** Recognized flag spellings, short and long, mapped to their roles. */
+  readonly flags: ReadonlyMap<string, PatternFlagRole>;
   /**
    * Number of leading positional arguments that are patterns/scripts, not paths.
    * Default: 1 (covers sed, awk, grep, rg).
@@ -252,130 +323,186 @@ interface PatternCommandConfig {
   readonly patternPositionals?: number;
 }
 
+const GREP_FLAGS = new Map<string, PatternFlagRole>([
+  ["-e", "script"],
+  ["--regexp", "script"],
+  ["-f", "script-file"],
+  ["--file", "script-file"],
+  ["-A", "value"],
+  ["--after-context", "value"],
+  ["-B", "value"],
+  ["--before-context", "value"],
+  ["-C", "value"],
+  // `--context` is deliberately absent, though `-C` is present and `rg` lists
+  // the long form below. grep parses with getopt, which declares `context`
+  // with an *optional* argument (`-C[NUM]`'s history), and a long option
+  // declared that way never takes a separate `argv`: `grep --context 2 pat f`
+  // searches for `2` in the files `pat` and `f`. Listing it would consume the
+  // `2`, leaving `pat` — a real file operand — to be skipped as the inline
+  // pattern. Its absence costs only a bare `2` token from `--context=2`, which
+  // names nothing and the existence probe drops (#823).
+  ["-m", "value"],
+  ["--max-count", "value"],
+]);
+
+const SED_CONFIG: PatternCommandConfig = {
+  flags: new Map<string, PatternFlagRole>([
+    ["-e", "script"],
+    ["--expression", "script"],
+    ["-f", "script-file"],
+    ["--file", "script-file"],
+    ["-i", "suffix"],
+  ]),
+};
+
+/**
+ * The short flags are POSIX and consume on every awk; the GNU long forms are
+ * `unknown-arity` because the bare name does not fix the parser.
+ *
+ * `awk` is GNU awk on Fedora/RHEL, where `--file prog.awk` reads `prog.awk`,
+ * and one-true-awk or mawk on macOS and Debian/Ubuntu, where the long option
+ * is ignored outright (`awk: unknown option --field-separator ignored`) and
+ * the following words are the program text and its input files. Asserting
+ * either arity drops a real operand on the other family, so the table asserts
+ * neither. `nawk` shares this for the same reason (#823).
+ */
+const AWK_CONFIG: PatternCommandConfig = {
+  flags: new Map<string, PatternFlagRole>([
+    ["-e", "script"],
+    ["-f", "script-file"],
+    ["-F", "value"],
+    ["-v", "value"],
+    ["--source", "unknown-arity"],
+    ["--file", "unknown-arity"],
+    ["--field-separator", "unknown-arity"],
+    ["--assign", "unknown-arity"],
+  ]),
+};
+
+/** `gawk` names GNU awk outright, so its long forms carry their real roles. */
+const GAWK_CONFIG: PatternCommandConfig = {
+  flags: new Map<string, PatternFlagRole>([
+    ...AWK_CONFIG.flags,
+    ["--source", "script"],
+    ["--file", "script-file"],
+    ["--field-separator", "value"],
+    ["--assign", "value"],
+  ]),
+};
+
+const GREP_CONFIG: PatternCommandConfig = { flags: GREP_FLAGS };
+
+const RG_CONFIG: PatternCommandConfig = {
+  flags: new Map<string, PatternFlagRole>([
+    ...GREP_FLAGS,
+    // rg parses with clap rather than getopt, where `--context` takes a
+    // required argument, so its separated spelling really does consume:
+    // `rg --context 2 pat f` searches for `pat` in `f`. Same spelling as
+    // grep's, opposite arity — which is why it is listed per tool rather than
+    // shared above (#823).
+    ["--context", "value"],
+    ["-g", "value"],
+    ["--glob", "value"],
+    ["-t", "value"],
+    ["--type", "value"],
+    ["-T", "value"],
+    ["--type-not", "value"],
+    ["-j", "value"],
+    ["--threads", "value"],
+    ["-M", "value"],
+    ["--max-columns", "value"],
+    ["-r", "value"],
+    ["--replace", "value"],
+    ["-E", "value"],
+    ["--encoding", "value"],
+  ]),
+};
+
+const SD_CONFIG: PatternCommandConfig = {
+  flags: new Map<string, PatternFlagRole>([
+    ["-f", "value"],
+    ["--flags", "value"],
+    ["-n", "value"],
+    ["--max-replacements", "value"],
+  ]),
+  patternPositionals: 2,
+};
+
 /**
  * Commands whose first N positional arguments are inline patterns/scripts,
  * not filesystem paths. The map stores per-command flag configuration so
  * the walker can correctly identify which arguments are consumed by flags
  * vs. which are positional.
+ *
+ * Names share a configuration object only when they share a *parser*, which is
+ * narrower than being aliases: `egrep`/`fgrep` are the same binary as `grep`
+ * here, and `nawk` is one-true-awk like `awk` — but `gawk` has its own config,
+ * because it is the only one of the three that certainly means GNU awk and so
+ * the only one whose long options certainly consume (#823).
  */
 const PATTERN_FIRST_COMMANDS: ReadonlyMap<string, PatternCommandConfig> =
   new Map([
-    [
-      "sed",
-      {
-        argConsumingFlags: new Set(["-e", "-i"]),
-        fileConsumingFlags: new Set(["-f"]),
-      },
-    ],
-    [
-      "awk",
-      {
-        argConsumingFlags: new Set(["-e", "-F", "-v"]),
-        fileConsumingFlags: new Set(["-f"]),
-      },
-    ],
-    [
-      "gawk",
-      {
-        argConsumingFlags: new Set(["-e", "-F", "-v"]),
-        fileConsumingFlags: new Set(["-f"]),
-      },
-    ],
-    [
-      "nawk",
-      {
-        argConsumingFlags: new Set(["-e", "-F", "-v"]),
-        fileConsumingFlags: new Set(["-f"]),
-      },
-    ],
-    [
-      "grep",
-      {
-        argConsumingFlags: new Set(["-e", "-A", "-B", "-C", "-m"]),
-        fileConsumingFlags: new Set(["-f"]),
-      },
-    ],
-    [
-      "egrep",
-      {
-        argConsumingFlags: new Set(["-e", "-A", "-B", "-C", "-m"]),
-        fileConsumingFlags: new Set(["-f"]),
-      },
-    ],
-    [
-      "fgrep",
-      {
-        argConsumingFlags: new Set(["-e", "-A", "-B", "-C", "-m"]),
-        fileConsumingFlags: new Set(["-f"]),
-      },
-    ],
-    [
-      "rg",
-      {
-        argConsumingFlags: new Set([
-          "-e",
-          "-A",
-          "-B",
-          "-C",
-          "-m",
-          "-g",
-          "-t",
-          "-T",
-          "-j",
-          "-M",
-          "-r",
-          "-E",
-        ]),
-        fileConsumingFlags: new Set(["-f"]),
-      },
-    ],
-    [
-      "sd",
-      {
-        argConsumingFlags: new Set(["-n", "-f"]),
-        fileConsumingFlags: new Set([]),
-        patternPositionals: 2,
-      },
-    ],
+    ["sed", SED_CONFIG],
+    ["awk", AWK_CONFIG],
+    ["gawk", GAWK_CONFIG],
+    ["nawk", AWK_CONFIG],
+    ["grep", GREP_CONFIG],
+    ["egrep", GREP_CONFIG],
+    ["fgrep", GREP_CONFIG],
+    ["rg", RG_CONFIG],
+    ["sd", SD_CONFIG],
   ]);
 
 /**
  * Describes what the walker should do when it encounters a flag word inside
  * a pattern-first command.  Using a discriminated union lets the `switch` in
- * `collectPatternCommandTokens` narrow `nextArgAction` without a non-null
+ * `collectPatternCommandTokens` narrow the flag's role without a non-null
  * assertion (which would trigger the Biome/ESLint assertion conflict).
  */
 type PatternCommandFlagDirective =
   | { kind: "end-of-flags" }
   | { kind: "regular-flag" }
-  | {
-      kind: "consume-arg";
-      nextArgAction: "skip" | "extract";
-      setsExplicitScript: boolean;
-    };
+  /** A recognized flag whose value is the argument that follows it. */
+  | { kind: "consume-next"; role: PatternFlagRole }
+  /** A recognized flag carrying its value in the same token. */
+  | { kind: "inline-value"; role: PatternFlagRole; value: string };
+
+/** A long option carrying its value inline: `--name=value`. */
+const LONG_OPTION_VALUE_PATTERN = /^(--[^=\s]+)=(.+)$/;
 
 /**
  * Classify a flag word from a pattern-first command into a directive that
- * tells the walker how to handle the flag and its following argument.
+ * tells the walker how to handle the flag and its value.
+ *
+ * Matched in the order the tools accept: the exact spelling (short or long),
+ * then a long option's `=`-embedded value, then a glued short value. The glued
+ * form matches only the **first** short flag, which is getopt's own rule —
+ * `grep -ei pattern` really is `-e` with the value `i`. A cluster whose
+ * argument-taking flag is not first (`grep -ie pattern`) therefore stays a
+ * plain flag, which over-surfaces the pattern rather than dropping the
+ * command's operand (ADR 0009's recoverable direction).
  */
 function classifyPatternCommandFlag(
   text: string,
   config: PatternCommandConfig,
 ): PatternCommandFlagDirective {
   if (text === "--") return { kind: "end-of-flags" };
-  if (config.argConsumingFlags.has(text)) {
-    return {
-      kind: "consume-arg",
-      nextArgAction: "skip",
-      setsExplicitScript: text === "-e" || text === "-f",
-    };
+
+  const exact = config.flags.get(text);
+  if (exact) return { kind: "consume-next", role: exact };
+
+  const longOption = LONG_OPTION_VALUE_PATTERN.exec(text);
+  if (longOption) {
+    const [, name, value] = longOption;
+    const role = config.flags.get(name);
+    return role === undefined
+      ? { kind: "regular-flag" }
+      : { kind: "inline-value", role, value };
   }
-  if (config.fileConsumingFlags.has(text)) {
-    return {
-      kind: "consume-arg",
-      nextArgAction: "extract",
-      setsExplicitScript: true,
-    };
+
+  if (!text.startsWith("--") && text.length > 2) {
+    const role = config.flags.get(text.slice(0, 2));
+    if (role) return { kind: "inline-value", role, value: text.slice(2) };
   }
   return { kind: "regular-flag" };
 }
@@ -389,11 +516,13 @@ function classifyPatternCommandFlag(
  * inline patterns/scripts and are skipped. Remaining positional
  * arguments are collected as path candidates.
  *
- * Flags listed in `argConsumingFlags` consume the next argument
- * (skipped). Flags in `fileConsumingFlags` consume the next
- * argument as a file path (collected). The flags `-e` and `-f`
- * additionally signal that an explicit script was provided via
- * flag, so no inline positional script is expected.
+ * A recognized flag's role (see {@link PatternFlagRole}) decides three things
+ * at once: whether the pattern positional is still expected, whether the
+ * flag's value is a path candidate, and — for `suffix` — whether the
+ * following argument belongs to the flag at all. The `=`-embedded and glued
+ * spellings carry the value in the flag's own token, so the walker splits it
+ * here rather than letting {@link collectEmbeddedOptionValues} emit a
+ * pattern's text as a path (#823).
  */
 function collectPatternCommandTokens(
   node: TSNode,
@@ -403,7 +532,7 @@ function collectPatternCommandTokens(
   const patternPositionals = config.patternPositionals ?? 1;
   let hasExplicitScript = false;
   let positionalsSeen = 0;
-  let nextArgAction: "skip" | "extract" | null = null;
+  let pendingConsumption: PatternFlagRole | null = null;
   let pastEndOfFlags = false;
   const tokens: PathToken[] = [];
 
@@ -411,27 +540,56 @@ function collectPatternCommandTokens(
     const child = node.child(i);
     if (!child) continue;
 
-    // Skip command_name and variable_assignment nodes.
-    if (child.type === "command_name" || child.type === "variable_assignment")
-      continue;
-
-    // Only process argument-like nodes; recurse into others
-    // (e.g. command_substitution) for nested commands.
-    if (!ARG_NODE_TYPES.has(child.type)) {
-      tokens.push(...collectPathCandidateTokens(child));
+    if (COMMAND_PREFIX_TYPES.has(child.type)) {
+      // Supplies no operand of its own, but may host one that really runs.
+      tokens.push(...collectHostedExecutionTokens(child));
       continue;
     }
 
+    const isArgNode = ARG_NODE_TYPES.has(child.type);
     const text = resolveNodeText(child);
 
-    // Handle consumed argument from previous flag.
-    if (nextArgAction === "skip") {
-      nextArgAction = null;
-      continue;
+    // Handle the argument a previous flag consumed. The consumption discharges
+    // on whatever node type follows, not only on an ARG_NODE_TYPES one: a bare
+    // number (`-A 3`), an expansion (`-A $N`), and a substitution
+    // (`-A $(echo 3)`) are all this flag's argument, and carrying the pending
+    // skip past them lands it on the *pattern* — shifting the positional count
+    // by one and eating the command's real file operand (#823).
+    if (pendingConsumption !== null) {
+      const consumption = pendingConsumption;
+      pendingConsumption = null;
+      if (!isArgNode) {
+        // Contributes no operand text of its own, but may host a nested
+        // execution whose operands are candidates (#741).
+        tokens.push(...collectPathCandidateTokens(child));
+        continue;
+      }
+      const discharge = dischargePendingConsumption(consumption, text, effect);
+      if (discharge.token) tokens.push(discharge.token);
+      if (discharge.consumed) continue;
     }
-    if (nextArgAction === "extract") {
-      tokens.push({ token: text, effect });
-      nextArgAction = null;
+
+    // A node outside ARG_NODE_TYPES is still one word the shell passes as an
+    // argument (`grep 42 f`, `grep $PATTERN f`, `grep $(cmd) f`), so it spends
+    // a pattern positional even though no reliable operand text can be read
+    // from it. Counting only argument nodes left a numeric or computed pattern
+    // unseen, so the slot was spent on the command's real operand instead and
+    // the operand reached no path surface (#823).
+    //
+    // A redirect hosted on the command node is not an argument and is excluded;
+    // counting it would push the real pattern out as an operand token. The
+    // exclusion is the narrow side on purpose: miscounting an argument as a
+    // redirect drops an operand, while the reverse only over-surfaces.
+    if (!isArgNode) {
+      if (
+        !EXECUTION_HOST_TYPES.has(child.type) &&
+        !hasExplicitScript &&
+        positionalsSeen < patternPositionals
+      ) {
+        positionalsSeen++;
+      }
+      // Recurse for nested commands (e.g. command_substitution).
+      tokens.push(...collectPathCandidateTokens(child));
       continue;
     }
 
@@ -447,11 +605,19 @@ function collectPatternCommandTokens(
         case "end-of-flags":
           pastEndOfFlags = true;
           break;
-        case "consume-arg":
-          nextArgAction = directive.nextArgAction;
-          if (directive.setsExplicitScript) hasExplicitScript = true;
+        case "consume-next":
+          pendingConsumption = directive.role;
+          if (suppliesScript(directive.role)) hasExplicitScript = true;
+          break;
+        case "inline-value":
+          if (directive.role === "script-file")
+            tokens.push({ token: directive.value, effect });
+          if (suppliesScript(directive.role)) hasExplicitScript = true;
           break;
         case "regular-flag":
+          // Unrecognized: fall back to the blind `--opt=value` split, which is
+          // safe precisely because the flag's role is unknown (#645).
+          tokens.push(...embeddedOptionValueToken(text, effect));
           break;
       }
       continue;
@@ -459,17 +625,63 @@ function collectPatternCommandTokens(
 
     // Positional argument.
     if (!hasExplicitScript && positionalsSeen < patternPositionals) {
-      positionalsSeen++;
-      continue; // Skip: this is an inline pattern/script.
+      positionalsSeen++; // Skip: this is an inline pattern/script.
+    } else {
+      tokens.push({ token: text, effect });
     }
-
-    // File argument — collect as path candidate.
-    tokens.push({ token: text, effect });
+    // A quoted flag never reaches the flag branch above, so its embedded value
+    // is split here instead.
+    tokens.push(...embeddedOptionValueToken(text, effect));
   }
 
   return tokens;
 }
 
+/**
+ * Whether a flag in this role means the inline pattern positional is spent.
+ *
+ * `unknown-arity` says so for the opposite reason to the others: not because
+ * the script was supplied, but because the walker cannot tell which word the
+ * script is, and skipping the wrong one drops a real operand.
+ */
+function suppliesScript(role: PatternFlagRole): boolean {
+  return (
+    role === "script" || role === "script-file" || role === "unknown-arity"
+  );
+}
+
+/**
+ * What a pending flag consumption made of the argument node that followed it.
+ *
+ * `consumed` is the flag's own verdict, not the walker's: a `suffix` flag
+ * declines a non-empty argument, which the walker then reads as an ordinary
+ * argument.
+ */
+interface ConsumptionDischarge {
+  readonly consumed: boolean;
+  /** The path candidate the consumed argument contributes, if any. */
+  readonly token?: PathToken;
+}
+
+/** Apply a pending consumption to the argument text that follows its flag. */
+function dischargePendingConsumption(
+  role: PatternFlagRole,
+  text: string,
+  effect: TokenEffect,
+): ConsumptionDischarge {
+  switch (role) {
+    case "script-file":
+      return { consumed: true, token: { token: text, effect } };
+    case "script":
+    case "value":
+      return { consumed: true };
+    case "suffix":
+      return { consumed: text === "" };
+    case "unknown-arity":
+      return { consumed: false };
+  }
+}
+
 /**
  * Collect all argument tokens from a generic (non-pattern-first) command node,
  * skipping the command name and variable assignments.
@@ -485,12 +697,12 @@ function collectGenericCommandTokens(
     const child = node.child(i);
     if (!child) continue;
 
-    if (child.type === "command_name") {
-      seenCommandName = true;
+    if (COMMAND_PREFIX_TYPES.has(child.type)) {
+      // Supplies no operand of its own, but may host one that really runs.
+      if (child.type === "command_name") seenCommandName = true;
+      tokens.push(...collectHostedExecutionTokens(child));
       continue;
     }
-    // Skip variable_assignment nodes (FOO=/bar)
-    if (child.type === "variable_assignment") continue;
 
     // If there was no explicit command_name node, the first word-like
     // child is the command name itself — skip it.