@gotgenes/pi-permission-system 40.1.2 → 40.1.4

package/CHANGELOG.md

@@ -5,6 +5,36 @@ 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).
 
+## [40.1.4](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v40.1.3...pi-permission-system-v40.1.4) (2026-10-10)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** scope a wrapper's session approval to its inner command ([97f805f](https://github.com/gotgenes/pi-packages/commit/97f805fc7f07be93ef0fc054310755bddabada24)), closes [#1055](https://github.com/gotgenes/pi-packages/issues/1055), closes [#1054](https://github.com/gotgenes/pi-packages/issues/1054)
+* **pi-permission-system:** keep an xargs replacement template exact in session approvals ([b4a4d06](https://github.com/gotgenes/pi-packages/commit/b4a4d0648c9cf4e873a7679e8f701925232cd5aa)), closes [#1055](https://github.com/gotgenes/pi-packages/issues/1055), closes [#1054](https://github.com/gotgenes/pi-packages/issues/1054)
+* **pi-permission-system:** keep a wrapped command exact when a word holds a non-breaking space ([f16aa96](https://github.com/gotgenes/pi-packages/commit/f16aa968dbeed76b23967838b88fff0d18e93cde)), closes [#1055](https://github.com/gotgenes/pi-packages/issues/1055), closes [#1054](https://github.com/gotgenes/pi-packages/issues/1054)
+
+### Documentation
+
+* **pi-permission-system:** describe wrapper session-approval suggestions ([a999c58](https://github.com/gotgenes/pi-packages/commit/a999c585e60c8d4d8836de744788440712c9d099)), closes [#1055](https://github.com/gotgenes/pi-packages/issues/1055), closes [#1054](https://github.com/gotgenes/pi-packages/issues/1054)
+* **pi-permission-system:** note that a bare inline-shell payload keeps its exact session pattern ([3d53393](https://github.com/gotgenes/pi-packages/commit/3d53393c9da27c74c900902d2f0ec2453df1055d)), closes [#1055](https://github.com/gotgenes/pi-packages/issues/1055), closes [#1054](https://github.com/gotgenes/pi-packages/issues/1054)
+
+## [40.1.3](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v40.1.2...pi-permission-system-v40.1.3) (2026-10-10)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** xargs -J and GNU xargs -i/-l no longer earn the pure-reader exemption for the wrong command ([c28e296](https://github.com/gotgenes/pi-packages/commit/c28e29606842def673e7fc4f0b419ee70661736e)), closes [#1053](https://github.com/gotgenes/pi-packages/issues/1053)
+* **pi-permission-system:** xargs reads every option its BSD and GNU manuals list ([e8be7a8](https://github.com/gotgenes/pi-packages/commit/e8be7a8e5be43e729aebe076e75af6ce814d2102)), closes [#1053](https://github.com/gotgenes/pi-packages/issues/1053)
+* **pi-permission-system:** env's chdir, split-string, altpath, and argv0 modes keep the indirection floor ([40a1e1b](https://github.com/gotgenes/pi-packages/commit/40a1e1b6dc19cc90990288a4fce8cb10ea1468c9)), closes [#1053](https://github.com/gotgenes/pi-packages/issues/1053)
+* **pi-permission-system:** doas -a, -C, and -s keep the indirection floor ([0a1dada](https://github.com/gotgenes/pi-packages/commit/0a1dada433d6054b580dc46cbeadaf7531fb84b1)), closes [#1053](https://github.com/gotgenes/pi-packages/issues/1053)
+* **pi-permission-system:** watch and the parallelizers no longer earn the pure-reader exemption ([5e14c70](https://github.com/gotgenes/pi-packages/commit/5e14c70cb5851a43ebfa2b98f111f2dd3176893d)), closes [#1053](https://github.com/gotgenes/pi-packages/issues/1053)
+* **pi-permission-system:** GNU xargs --max-lines no longer earns the pure-reader exemption for the wrong command ([01e943a](https://github.com/gotgenes/pi-packages/commit/01e943ac1c6041491bc4086bc9213fb8a369b74b)), closes [#1053](https://github.com/gotgenes/pi-packages/issues/1053)
+
+### Documentation
+
+* **pi-permission-system:** document the env, xargs, doas, and command-line wrapper floors ([ef82c63](https://github.com/gotgenes/pi-packages/commit/ef82c6378d00ca6667135ec1e0f574ca952d2372))
+
 ## [40.1.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v40.1.1...pi-permission-system-v40.1.2) (2026-10-09)
 
 

package/docs/configuration.md

@@ -1074,6 +1074,7 @@ All four of these must hold, and each is a way the floor's reason could still ap
 1. The unit is an indirection wrapper.
    An `sh -c`/`eval` payload is not one — see below.
 2. The command it runs can be established without passing through an inline shell.
+   `watch` and `parallel` hand their whole command line to a shell, and `rush` and `rust-parallel` build theirs from a template, so a unit with any of the four as a layer never qualifies: `watch cat x \; rm y` runs `rm`.
 3. That command **proves** a read: a bare-basename core word with no option that withdraws the claim.
    So `xargs sort -o /tmp/x` and `xargs find . -delete` stay floored, and so does `xargs ./grep foo`.
 4. The enclosing statement provably writes no file through a redirect.
@@ -1142,6 +1143,17 @@ That rule matches the wrapper's own text, so it is decided before the exemption
 A `sudo` mode in which the command it names is not what runs as named keeps the floor whatever that command is: `-e`/`--edit` (sudoedit edits its operands as files, as root), `-s`/`--shell` and `-i`/`--login` (a shell runs the operand), and `-D`/`--chdir` and `-R`/`--chroot` (relative operands resolve somewhere the path surfaces do not look).
 So does `-h`, whose meaning depends on what follows it, and any option `sudo`'s manual does not list; a mode that keeps the floor is approved at the prompt or under `yoloMode`.
 
+`env`, `xargs`, and `doas` are read the same way, from the BSD and GNU manuals for the first two and `opendoas` for the third, and any option those do not list keeps the floor too.
+So `xargs -n 1 cat` and `env -u FOO cat x` still resolve by `cat`'s rule, while these keep the floor whatever command they name:
+
+- `env -C`/`--chdir`, because relative operands resolve somewhere the path surfaces do not look (`env -C /etc cat shadow` reads `/etc/shadow`).
+- `env -S`/`--split-string`, because the command is split out of one word at run time (`env -Srm cat` runs `rm cat`).
+- `env -P`, `-a`/`--argv0`, and `--env0-from`, because each chooses which binary the named command is: a search path, the argv0 a multi-call binary dispatches on, or an environment that may set `PATH`.
+- `xargs -J`, because it puts input in the command's place when the command equals its replacement string.
+- `doas -C` (it checks a config and runs nothing), `doas -s` (it runs a shell), and OpenBSD's `doas -a`, which `opendoas` does not list.
+
+GNU `xargs -i`, `-l`, `-e`, and `--max-lines` take a value only when it is attached (`-i{}`, `--max-lines=2`), so `xargs -i rm cat x` runs `rm`, and `xargs` and `doas` run a `NAME=value` word as the command rather than an assignment.
+
 #### Which key to actually write
 
 The useful *grants* are `*_read: allow` and the bare sugar key.

package/docs/session-approvals.md

@@ -87,6 +87,31 @@ The arity table covers common CLI tools including git, npm/pnpm/yarn/bun, docker
 To add an entry, open `src/access-intent/bash/bash-arity.ts` and add a key/arity pair to the `ARITY` object.
 Put the most specific multi-word prefix first (e.g. `"npm run": 3`) before the shorter fallback (`"npm": 2`).
 
+### Wrapped commands
+
+A command behind an indirection wrapper (`sudo`, `env`, `xargs`, `nohup`, `timeout`, `nice`, and the rest of the wrapper vocabulary) is approved by its inner command, not by the wrapper.
+A session approval skips the wrapper's floor, so the suggestion keeps every wrapper word literally (options, operands, nested wrappers) and lets only the inner command's arguments vary.
+
+| Example command                      | Suggested pattern             |
+| ------------------------------------ | ----------------------------- |
+| `nohup mytool argument`              | `nohup mytool *`              |
+| `sudo aws s3 rm s3://bucket`         | `sudo aws s3 rm *`            |
+| `env FOO=bar mytool argument`        | `env FOO=bar mytool *`        |
+| `timeout 5 mytool argument`          | `timeout 5 mytool *`          |
+| `sudo -u root nohup mytool argument` | `sudo -u root nohup mytool *` |
+
+A wrapped pattern always puts a space before its wildcard, so approving `nohup mytool` covers `nohup mytool` and `nohup mytool <args>` but not `nohup mytool-other`.
+
+When the inner command cannot be established from the words alone, the suggestion is the whole command with no wildcard:
+
+- Shell syntax in any word: quoting, `$` expansion, a glob, `~`, grouping, or an operator (`sudo mytool $HOME`).
+- An inline shell payload, bare or wrapped (`bash -c …`, `eval …`, `sudo bash -c …`), or a wrapper that hands its command line to a shell or template (`watch`, `parallel`, `rush`, `rust-parallel`).
+- A wrapper mode in which the peeled command is not what runs (`sudo -s`, `env -C`), an option the wrapper's table does not admit (`timeout --sig KILL 5 …`, `flock -w 5 …`), or a `find`/`fd` exec clause.
+- An `xargs` replacement option (`-I`, `-i`, `--replace`), since standard input then rewrites the inner command's arguments (`xargs -I X nohup X first`).
+- Wrappers nested deeper than the gate peels.
+
+This changes only the suggested pattern; the wrapper floors and their exemptions are unchanged.
+
 ## Review Log Entries
 
 The review log records session approval decisions:

package/package.json

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

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

@@ -3,10 +3,11 @@
  * what it actually runs, and whether its floor still has a reason to hold.
  *
  * Pure and word-based; the AST walk that produces the words lives in
- * `command-enumeration.ts`. The three questions live here together
- * deliberately: the shape that floors a unit to `ask`, the shape that names its
- * inner command, and the shape that exempts it must agree, and separate
- * classifiers over the same vocabulary would drift.
+ * `command-enumeration.ts`. The questions live here together deliberately:
+ * the shape that floors a unit to `ask`, the shape that names its inner
+ * command, the shape that exempts it, and how far a session approval may
+ * generalize past it must agree, and separate classifiers over the same
+ * vocabulary would drift.
  */
 
 import type { FloorExemption } from "#src/types";
@@ -163,7 +164,10 @@ export function executedUnitOf(
  * 2. Unwrapping reached the inner command without passing through an opaque
  *    payload. `sh -c '…'` carries an unparsed program whose first word says
  *    nothing about the rest of it, which is why this cannot consult
- *    {@link executedUnitOf}'s string.
+ *    {@link executedUnitOf}'s string. A wrapper that hands its whole command
+ *    line to a shell or builds it from a template
+ *    ({@link OPAQUE_COMMAND_LINE_WRAPPERS}) is that payload in another shape:
+ *    `watch cat x \; rm y` runs `rm`, so no layer may be one.
  * 3. The inner command *proves* a read — bare-basename core word, retraction
  *    guards applied, so `xargs sort -o /tmp/x` and `xargs find . -delete` are
  *    not transparent.
@@ -184,7 +188,11 @@ export function floorExemptionOf(
   // Only the peeled words matter here, so the walk is handed no source span to
   // cut from — the text slice is `executedUnitOf`'s product, not this one's.
   const unwrapped = unwrapIndirection(words, "");
-  if (unwrapped.kind === "opaque" || unwrapped.peeled.length === 0) {
+  if (
+    unwrapped.kind === "opaque" ||
+    unwrapped.peeled.length === 0 ||
+    unwrapped.peeled.some(runsOpaqueCommandLine)
+  ) {
     return undefined;
   }
 
@@ -197,6 +205,12 @@ export function floorExemptionOf(
     : undefined;
 }
 
+/** True when a peeled layer's wrapper does not run the words the peel sees. */
+function runsOpaqueCommandLine(layer: readonly CommandWord[]): boolean {
+  const name = wrapperName(layer);
+  return name !== undefined && OPAQUE_COMMAND_LINE_WRAPPERS.has(name);
+}
+
 /**
  * True when every peeled layer only changes *how* the inner command runs, and
  * that command is a literal name the gate can resolve by its own rule.
@@ -232,8 +246,16 @@ function onlyModifiesExecution(
   peeled: readonly (readonly CommandWord[])[],
   inner: readonly CommandWord[],
 ): boolean {
+  return peeled.every(isAdmittedModifierLayer) && reachedLiteralCommand(inner);
+}
+
+/**
+ * True when a peel ended at an ordinary command spelled as a literal name: not
+ * a wrapper it could not see past, and not shell syntax standing where the
+ * command name should be.
+ */
+function reachedLiteralCommand(inner: readonly CommandWord[]): boolean {
   return (
-    peeled.every(isAdmittedModifierLayer) &&
     classifyWrapperWords(inner) === undefined &&
     isLiteralCommandName(inner.at(0)?.text ?? "")
   );
@@ -296,6 +318,90 @@ function isLiteralCommandName(text: string): boolean {
   return LITERAL_COMMAND_NAME.test(text) && !RESERVED_WORDS.has(text);
 }
 
+// ── Session patterns ─────────────────────────────────────────────────────────
+
+/**
+ * Where the inner command starts for a session-approval pattern: `0` for an
+ * ordinary command, the count of peeled wrapper words when every layer may be
+ * generalized past, or `null` to keep the whole command.
+ *
+ * A session grant skips the wrapper floor, so the pattern built from this
+ * index is the grant's whole width: everything before the index stays literal,
+ * and only the inner command's arguments may vary. Each `null` is a shape where
+ * a pattern ending in a wildcard could name a command the human never saw —
+ * shell syntax the whitespace split cannot read, an opaque payload, a peel
+ * that stopped short, or a layer {@link generalizesLayer} refuses.
+ *
+ * The count is summed over the peeled layers rather than taken from the inner
+ * command's length, since the walk trims an exec terminator off the end.
+ */
+export function sessionCommandIndex(tokens: readonly string[]): number | null {
+  const words = literalWordsOf(tokens);
+  if (classifyWrapperWords(words) === undefined) return 0;
+  if (words.some((word) => word.computed)) return null;
+  const unwrapped = unwrapIndirection(words, "");
+  if (unwrapped.kind === "opaque") return null;
+  if (!unwrapped.peeled.every(generalizesLayer)) return null;
+  if (!reachedLiteralCommand(unwrapped.words)) return null;
+  return unwrapped.peeled.reduce((count, layer) => count + layer.length, 0);
+}
+
+/**
+ * True when a session pattern may keep a peeled layer literal and vary what
+ * follows its inner command.
+ *
+ * A getopt-read wrapper's peel already refuses an unlisted or mode-changing
+ * option. A table-read wrapper skips an unknown option as a flag, so it is
+ * admitted only by the floor exemption's own admission or with no option at
+ * all; that also refuses a `find`/`fd` exec flag, after which `find`'s own
+ * options may follow the inner command.
+ */
+function generalizesLayer(layer: readonly CommandWord[]): boolean {
+  const name = wrapperName(layer);
+  if (name === undefined || runsOpaqueCommandLine(layer)) return false;
+  if (name === "xargs") return !mayReplaceArguments(layer);
+  if (GETOPT_GRAMMARS.has(name)) return true;
+  return (
+    isAdmittedModifierLayer(layer) ||
+    layer.slice(1).every((word) => !word.text.startsWith("-"))
+  );
+}
+
+/**
+ * True when an `xargs` layer may carry a replacement option (`-I`, `-i`,
+ * `--replace`), which lets standard input rewrite the inner command's
+ * arguments, a nested wrapper's executable included.
+ *
+ * Deliberately wider than the grammar: any short cluster holding `I` or `i`
+ * and any long option opening `--r` counts, since a false positive only keeps
+ * the whole command.
+ */
+function mayReplaceArguments(layer: readonly CommandWord[]): boolean {
+  return layer
+    .slice(1)
+    .some(({ text }) => /^-[^-]*[Ii]/.test(text) || text.startsWith("--r"));
+}
+
+/**
+ * A command's whitespace tokens as command words, each marked `computed` when
+ * it carries shell syntax the split cannot read: quoting, expansion, a glob,
+ * grouping, an operator, or a comment.
+ */
+function literalWordsOf(tokens: readonly string[]): CommandWord[] {
+  let offset = 0;
+  return tokens.map((text) => {
+    const word: CommandWord = {
+      text,
+      value: text,
+      computed: SHELL_SYNTAX.test(text),
+      mayLeadWithDash: text.startsWith("-"),
+      offset,
+    };
+    offset += text.length + 1;
+    return word;
+  });
+}
+
 // ── Unwrapping ───────────────────────────────────────────────────────────────
 
 /**
@@ -423,11 +529,13 @@ function innerCommandIndex(words: readonly CommandWord[]): number {
 
 /**
  * {@link innerCommandIndex} for a wrapper read as getopt_long reads it, with
- * options permuted no further than the first non-option (sudo's `+` optstring).
+ * options permuted no further than the first non-option, as every grammar here
+ * does (a `+` optstring, or BSD getopt, which never permutes).
  *
- * Options come first, then the `NAME=value` assignments the wrapper passes to
- * the command, then the command. `-1` when an option is refused, unlisted, or
- * an ambiguous abbreviation, or when the words run out first.
+ * Options come first, then — for a wrapper that takes them — the `NAME=value`
+ * assignments it passes to the command, then the command. `-1` when an option
+ * is refused, unlisted, or an ambiguous abbreviation, or when the words run out
+ * first.
  */
 function getoptInnerIndex(
   words: readonly CommandWord[],
@@ -436,7 +544,7 @@ function getoptInnerIndex(
   let index = 1;
   while (index < words.length) {
     const word = words[index].text;
-    if (word === "--") {
+    if (word === "--" || (word === "-" && grammar.loneDashEndsOptions)) {
       index++;
       break;
     }
@@ -447,7 +555,11 @@ function getoptInnerIndex(
     if (consumed === undefined) return -1;
     index += consumed;
   }
-  while (index < words.length && isEnvironmentAssignment(words[index].text)) {
+  while (
+    grammar.assignments &&
+    index < words.length &&
+    isEnvironmentAssignment(words[index].text)
+  ) {
     index++;
   }
   return index < words.length ? index : -1;
@@ -458,7 +570,9 @@ function getoptInnerIndex(
  * `undefined` when a letter in it is refused or unlisted.
  *
  * A value-taking letter ends the cluster: the rest of the cluster is its value
- * (`-uedward`), or the following word when nothing is left (`-nu root`).
+ * (`-uedward`), or the following word when nothing is left (`-nu root`). An
+ * optional-argument letter ends it too, but its value is only ever the rest of
+ * the cluster (`-i{}`), never the following word (`-i rm cat x` runs `rm`).
  */
 function shortClusterWords(
   letters: string,
@@ -467,6 +581,7 @@ function shortClusterWords(
   for (let position = 0; position < letters.length; position++) {
     const arity = table.get(letters[position]);
     if (arity === undefined || arity === "refuse") return undefined;
+    if (arity === "optional") return 1;
     if (arity === "value") return position + 1 < letters.length ? 1 : 2;
   }
   return 1;
@@ -474,7 +589,8 @@ function shortClusterWords(
 
 /**
  * How many words a long option spans (`--user root` is two, `--user=root`
- * one), or `undefined` when it is refused, unlisted, or ambiguous.
+ * one), or `undefined` when it is refused, unlisted, or ambiguous. A flag or an
+ * optional argument (`--replace[=R]`) never takes the following word.
  */
 function longOptionWords(
   body: string,
@@ -634,17 +750,11 @@ const EXEC_CONDITIONAL_WRAPPERS = new Map<string, ReadonlySet<string>>([
  *
  * This table decides the gate, not only the display: {@link floorExemptionOf}
  * judges the command it locates, so a missing entry can name a pure reader that
- * is really an option's value (`xargs -J cat rm x`), and the execution-modifier
- * clause admits value-taking options from it. A wrapper read by a
- * {@link GETOPT_GRAMMARS} entry has no row here.
+ * is really an option's value (GNU `time --out cat rm x`, #1057), and the
+ * execution-modifier clause admits value-taking options from it. A wrapper
+ * read by a {@link GETOPT_GRAMMARS} entry has no row here.
  */
 const VALUE_TAKING_FLAGS = new Map<string, ReadonlySet<string>>([
-  ["doas", new Set(["-u", "-C"])],
-  ["env", new Set(["-u", "-C", "--unset", "--chdir"])],
-  [
-    "xargs",
-    new Set(["-n", "-P", "-I", "-i", "-d", "-E", "-L", "-l", "-s", "-a"]),
-  ],
   ["timeout", new Set(["-s", "-k", "--signal", "--kill-after"])],
   ["nice", new Set(["-n", "--adjustment"])],
   ["time", new Set(["-o", "-f", "--output", "--format"])],
@@ -657,10 +767,11 @@ const EMPTY_FLAGS: ReadonlySet<string> = new Set<string>();
 
 /**
  * How a getopt-parsed wrapper treats one of its options: a flag, an option
- * taking a value, or a mode in which the command the peel would name is not
+ * taking a value, an option whose value is optional and so only ever attached
+ * (getopt's `::`), or a mode in which the command the peel would name is not
  * the one that runs, which refuses the peel.
  */
-type OptionArity = "flag" | "value" | "refuse";
+type OptionArity = "flag" | "value" | "optional" | "refuse";
 
 /**
  * A wrapper's options as getopt_long reads them, keyed by short letter and by
@@ -670,6 +781,17 @@ type OptionArity = "flag" | "value" | "refuse";
 interface GetoptGrammar {
   readonly short: ReadonlyMap<string, OptionArity>;
   readonly long: ReadonlyMap<string, OptionArity>;
+  /**
+   * Whether `NAME=value` words after the options are assignments the wrapper
+   * passes to the command. `xargs` and `doas` run such a word as the command.
+   */
+  readonly assignments: boolean;
+  /**
+   * Whether a lone `-` is an option that ends the option walk, as `env -`
+   * (clear the environment) is; otherwise it is the command, which names
+   * nothing.
+   */
+  readonly loneDashEndsOptions: boolean;
 }
 
 /**
@@ -743,11 +865,145 @@ const SUDO_GRAMMAR: GetoptGrammar = {
     ["login", "refuse"],
     ["shell", "refuse"],
   ]),
+  assignments: true,
+  loneDashEndsOptions: false,
+};
+
+/**
+ * `env`'s options: the union of BSD `env` (optstring `-0C:iP:S:u:v`, no long
+ * options) and GNU coreutils 9.12 (`env --help`). No letter has different
+ * arities on the two.
+ *
+ * Each refusing option is one where the command the peel would name is not
+ * what runs as named: `-C`/`--chdir` move where its relative operands
+ * resolve, so the path surfaces would judge the wrong file; `-S`/
+ * `--split-string` split one word into several, so the command is built at
+ * run time; and `-P` (a search path), `-a`/`--argv0` (the argv0 a multi-call
+ * binary dispatches on), and `--env0-from` (an environment that may set
+ * `PATH`) choose which binary the named command is.
+ *
+ * A lone `-` clears the environment and, as GNU reads it, ends the options;
+ * BSD keeps parsing after it, so ending there only ever names less.
+ */
+const ENV_GRAMMAR: GetoptGrammar = {
+  short: new Map<string, OptionArity>([
+    ["0", "flag"],
+    ["i", "flag"],
+    ["v", "flag"],
+    ["u", "value"],
+    ["a", "refuse"],
+    ["C", "refuse"],
+    ["P", "refuse"],
+    ["S", "refuse"],
+  ]),
+  long: new Map<string, OptionArity>([
+    ["debug", "flag"],
+    ["help", "flag"],
+    ["ignore-environment", "flag"],
+    ["list-signal-handling", "flag"],
+    ["null", "flag"],
+    ["version", "flag"],
+    ["unset", "value"],
+    ["block-signal", "optional"],
+    ["default-signal", "optional"],
+    ["ignore-signal", "optional"],
+    ["argv0", "refuse"],
+    ["chdir", "refuse"],
+    ["env0-from", "refuse"],
+    ["split-string", "refuse"],
+  ]),
+  assignments: true,
+  loneDashEndsOptions: true,
+};
+
+/**
+ * `xargs`'s options: the union of BSD `xargs` (optstring
+ * `+0E:I:J:L:n:oP:pR:S:s:rtx`) and GNU findutils 4.9 (`xargs --help`). No
+ * letter has different arities on the two, and BSD's long names are a subset
+ * of GNU's, so an option one platform rejects only makes it run nothing.
+ *
+ * GNU's `-i`, `-l`, and `-e` take an optional value, attached only, so
+ * `xargs -i rm cat x` runs `rm`. So does `--max-lines`, though its `--help`
+ * line reads as required and its short form `-L` does take the next word:
+ * `xargs --max-lines echo A B` runs `echo`. BSD's `-J` refuses: it puts input
+ * in the utility position when the utility equals its replstr
+ * (`xargs -J % % x`).
+ */
+const XARGS_GRAMMAR: GetoptGrammar = {
+  short: new Map<string, OptionArity>([
+    ["0", "flag"],
+    ["o", "flag"],
+    ["p", "flag"],
+    ["r", "flag"],
+    ["t", "flag"],
+    ["x", "flag"],
+    ["a", "value"],
+    ["d", "value"],
+    ["E", "value"],
+    ["I", "value"],
+    ["L", "value"],
+    ["n", "value"],
+    ["P", "value"],
+    ["R", "value"],
+    ["S", "value"],
+    ["s", "value"],
+    ["e", "optional"],
+    ["i", "optional"],
+    ["l", "optional"],
+    ["J", "refuse"],
+  ]),
+  long: new Map<string, OptionArity>([
+    ["exit", "flag"],
+    ["help", "flag"],
+    ["interactive", "flag"],
+    ["no-run-if-empty", "flag"],
+    ["null", "flag"],
+    ["open-tty", "flag"],
+    ["show-limits", "flag"],
+    ["verbose", "flag"],
+    ["version", "flag"],
+    ["arg-file", "value"],
+    ["delimiter", "value"],
+    ["max-args", "value"],
+    ["max-chars", "value"],
+    ["max-procs", "value"],
+    ["process-slot-var", "value"],
+    ["eof", "optional"],
+    ["max-lines", "optional"],
+    ["replace", "optional"],
+  ]),
+  assignments: false,
+  loneDashEndsOptions: false,
+};
+
+/**
+ * `doas`'s options, verified against `opendoas`
+ * (`usage: doas [-Lns] [-C config] [-u user] command [args]`); it takes no
+ * long options and never permutes. OpenBSD's `-a style` is absent there, so
+ * it is left unlisted and refuses rather than admitted unverified.
+ *
+ * `-C` checks a config and runs nothing, so the command it would name never
+ * runs as named; `-s` runs a shell.
+ */
+const DOAS_GRAMMAR: GetoptGrammar = {
+  short: new Map<string, OptionArity>([
+    ["L", "flag"],
+    ["n", "flag"],
+    ["u", "value"],
+    ["C", "refuse"],
+    ["s", "refuse"],
+  ]),
+  long: new Map<string, OptionArity>(),
+  assignments: false,
+  loneDashEndsOptions: false,
 };
 
 /** Wrappers whose inner command is located by a getopt grammar. */
 const GETOPT_GRAMMARS = new Map<string, GetoptGrammar>([
   ["sudo", SUDO_GRAMMAR],
+  ["env", ENV_GRAMMAR],
+  ["xargs", XARGS_GRAMMAR],
+  ["doas", DOAS_GRAMMAR],
 ]);
 
 /**
@@ -796,6 +1052,12 @@ const WRITING_OPTIONS = new Map<string, ReadonlySet<string>>([
  */
 const LITERAL_COMMAND_NAME = /^[A-Za-z0-9_./+@%,:][A-Za-z0-9_./+@%,:-]*$/;
 
+/**
+ * A character that makes a whitespace token something other than the literal
+ * word a program receives.
+ */
+const SHELL_SYNTAX = /['"\\$`|&;<>(){}[\]*?!~#]/;
+
 /** Bash reserved words, which open syntax rather than name a command. */
 const RESERVED_WORDS: ReadonlySet<string> = new Set([
   "!",
@@ -828,6 +1090,21 @@ const RESERVED_WORDS: ReadonlySet<string> = new Set([
  */
 const LEADING_OPERAND_WRAPPERS = new Set(["timeout", "flock"]);
 
+/**
+ * Wrappers whose executed command line is not the words the peel sees, so a
+ * core-looking first word says nothing about what runs. `watch` (without
+ * `-x`) passes its words to `sh -c`, and GNU `parallel` runs its command
+ * through a shell; both verified, where `watch cat x \; rm y` runs `rm`.
+ * `rush` and `rust-parallel` build command lines from templates and have no
+ * local binary to verify how, so they are refused rather than admitted.
+ */
+const OPAQUE_COMMAND_LINE_WRAPPERS: ReadonlySet<string> = new Set([
+  "watch",
+  "parallel",
+  "rush",
+  "rust-parallel",
+]);
+
 /** Words ending a `find -exec` clause; they belong to `find`, not its command. */
 const EXEC_TERMINATORS = new Set([";", "+"]);
 

package/src/presentation/pattern-suggest.ts

@@ -2,6 +2,7 @@ import {
   prefix,
   stripBashCommentLines,
 } from "#src/access-intent/bash/bash-arity";
+import { sessionCommandIndex } from "#src/access-intent/bash/wrapper-analysis";
 import {
   type CapabilityDirection,
   PATH_BEARING_TOOLS,
@@ -30,6 +31,10 @@ export interface SessionApprovalSuggestion {
  * - Arity prefix covers all tokens: trailing wildcard (`npm run build*`).
  * - Arity prefix shorter than token list: space + wildcard (`git checkout *`).
  * - Unknown command: first token + space wildcard (`mytool *`).
+ * - Recognized wrapper: its words, then the inner command's arity prefix,
+ *   then a space wildcard (`sudo -u root nohup mytool *`).
+ * - Wrapper whose inner command cannot be proven: the exact command, with no
+ *   wildcard (`watch mytool x`).
  */
 export function suggestBashPattern(command: string): string {
   const trimmed = command.trim();
@@ -40,6 +45,12 @@ export function suggestBashPattern(command: string): string {
   if (!stripped) return "";
   const tokens = stripped.split(/\s+/);
   if (tokens.length === 1) return stripped;
+  // A wrapper's words are split only where bash splits them: `\s` also splits
+  // on a non-breaking space or `\r`, which would read `rm<NBSP>-rf` as `rm`.
+  const words = stripped.split(BASH_BLANKS);
+  const commandIndex = sessionCommandIndex(words);
+  if (commandIndex === null) return stripped;
+  if (commandIndex > 0) return wrappedPattern(words, commandIndex);
   const meaningful = prefix(tokens);
   if (meaningful.length >= tokens.length) {
     return `${stripped}*`;
@@ -47,6 +58,28 @@ export function suggestBashPattern(command: string): string {
   return `${meaningful.join(" ")} *`;
 }
 
+/** The blanks bash splits a command's words on. */
+const BASH_BLANKS = /[ \t\n]+/;
+
+/**
+ * The wrapper words kept literally, then the inner command's arity prefix.
+ *
+ * The wildcard always follows a space, even when the arity prefix covers every
+ * token, so approving `nohup mytool` never approves `nohup mytool-other`; the
+ * matcher treats a trailing space and wildcard as optional, so the bare
+ * command is still covered.
+ */
+function wrappedPattern(
+  tokens: readonly string[],
+  commandIndex: number,
+): string {
+  const meaningful = [
+    ...tokens.slice(0, commandIndex),
+    ...prefix(tokens.slice(commandIndex)),
+  ];
+  return `${meaningful.join(" ")} *`;
+}
+
 /**
  * Suggest an MCP session-approval pattern from a resolved target string.
  *