@gotgenes/pi-permission-system 40.1.2 → 40.1.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).
 
+## [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/package.json

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

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

@@ -163,7 +163,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 +187,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 +204,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.
@@ -423,11 +436,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 +451,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 +462,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 +477,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 +488,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 +496,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 +657,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 +674,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 +688,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 +772,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],
 ]);
 
 /**
@@ -828,6 +991,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([";", "+"]);