@gotgenes/pi-permission-system 40.2.0 → 40.2.1

package/CHANGELOG.md

@@ -5,6 +5,17 @@ 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.2.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v40.2.0...pi-permission-system-v40.2.1) (2026-10-14)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** a computed word in a wrapper's options keeps the indirection floor ([754a5fa](https://github.com/gotgenes/pi-packages/commit/754a5fadcab0aeac765ecb8cf423b1fb55e8d4d5))
+
+### Documentation
+
+* **pi-permission-system:** one literal-word rule for both wrapper floor exemptions ([334318a](https://github.com/gotgenes/pi-packages/commit/334318a0a918557e92741d442cba7728b66cc92e))
+
 ## [40.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v40.1.4...pi-permission-system-v40.2.0) (2026-10-12)
 
 

package/docs/configuration.md

@@ -1094,15 +1094,18 @@ The floor guards unknowability of *scope*, and scope stays the path surfaces' jo
 Such a unit is therefore **not** floored.
 It resolves by the inner command's own `bash` rules instead, and the review log records `floorExemption: "core-reader"` beside the rule that decided, so an allow the floor would once have prompted for is auditable to the reason that let it through.
 
-All four of these must hold, and each is a way the floor's reason could still apply:
+All five of these must hold, and each is a way the floor's reason could still apply:
 
 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.
+3. Every word the wrapper itself takes (an option, its value, an operand, a `NAME=value` word) is written literally.
+   The shell splits or expands a computed word before the wrapper runs, so `sudo -u $U cat x` with `U="root rm y"` runs `rm y cat x`; quoting does not exempt it, since `"$@"` can vanish and a quoted variable can name an array.
+   A computed word of the command it runs is fine: `sudo -u root cat $X` still qualifies.
+4. 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.
+5. 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`, `xargs sed -n 1p`, `find . -name '*.ts' -exec cat {} +`, and the no-op probe `sudo -n true` stop prompting under a matching `bash` allow, while `xargs rm`, `xargs sed -i`, and `find . -exec sh -c '…' \;` still prompt.
@@ -1115,7 +1118,7 @@ Three things this does **not** change:
   Under `bash: {"*": "allow", "grep *": "deny"}`, `xargs grep foo` is denied rather than merely prompted.
 - Path gating is untouched.
   The exemption decides the `bash` surface only, and every path token the command projects still goes through `path` and `external_directory` with the direction its command proved.
-  Clause 4 is what keeps that from being a weaker promise than it sounds: a redirect destination the parse cannot resolve (`> $OUT`, `> $(mktemp)`) is not projected onto those surfaces either, so the wrapper keeps its floor rather than relying on a gate that would not see the write.
+  Clause 5 is what keeps that from being a weaker promise than it sounds: a redirect destination the parse cannot resolve (`> $OUT`, `> $(mktemp)`) is not projected onto those surfaces either, so the wrapper keeps its floor rather than relying on a gate that would not see the write.
 
 ##### A wrapper that only modifies execution
 
@@ -1127,7 +1130,7 @@ All four of these must hold, and each keeps the decision about the command that
 
 1. **Every** wrapper layer is one of the five.
    `time sudo rm -rf x` and `sudo time pnpm test` stay floored, as do `nohup` (it may write `nohup.out`) and `flock` (it creates its lock file).
-2. Every option on each layer is one that wrapper is known to take, spelled in full, and every option, value, and operand is written literally (an environment assignment, which the shell does not split, may be computed).
+2. Every option on each layer is one that wrapper is known to take, spelled in full, and every option, value, operand, and `NAME=value` word is written literally.
    A word the shell rewrites (`timeout $D …`, `timeout {5,sudo} …`) may become several, one of them a wrapper, so it keeps the floor.
    So `timeout --sig KILL 5 …` (an abbreviation) and `nice -5 …` stay floored, and so do `time`'s file-writing `-o`, `--output`, and `-a`.
    The admitted options are `time -p`/`-l`/`-h`/`-f`; `timeout -s`/`-k`/`-f`/`-p`/`-v` and their long forms; `nice -n`/`--adjustment`; and `stdbuf -i`/`-o`/`-e` and their long forms.

package/package.json

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

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

@@ -158,7 +158,7 @@ export function executedUnitOf(
  * alike. Argument-independence is the core's admission bar, so there are no
  * arguments that make `grep` write a file.
  *
- * Four things must hold for it, and each is a way the reason could still hold:
+ * Five things must hold for it, and each is a way the reason could still hold:
  *
  * 1. The unit is an indirection wrapper — an ordinary command has no floor.
  * 2. Unwrapping reached the inner command without passing through an opaque
@@ -168,16 +168,21 @@ export function executedUnitOf(
  *    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
+ * 3. Every word a peeled layer passes its wrapper is literal: each option,
+ *    value, operand, and `NAME=value` word. The shell splits or expands a
+ *    computed one before the wrapper runs, so one of the words it becomes may
+ *    be the command that really runs — `sudo -u $U cat x` with
+ *    `U="root rm y"` runs `rm y cat x` as root.
+ * 4. 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.
- * 4. The unit writes no file through a redirect, which the caller reads off
+ * 5. The unit writes no file through a redirect, which the caller reads off
  *    the parse tree and this module never sees.
  *
  * `"execution-modifier"`: every wrapper layer only changes *how* the visible
  * inner command runs, so the unit resolves by that command's own rule whatever
- * it does (see {@link onlyModifiesExecution}). The first two conditions above
- * hold for it too; the core-reader reason is preferred when both apply.
+ * it does (see {@link onlyModifiesExecution}). The first three conditions
+ * above hold for it too; the core-reader reason is preferred when both apply.
  */
 export function floorExemptionOf(
   words: readonly CommandWord[],
@@ -191,7 +196,8 @@ export function floorExemptionOf(
   if (
     unwrapped.kind === "opaque" ||
     unwrapped.peeled.length === 0 ||
-    unwrapped.peeled.some(runsOpaqueCommandLine)
+    unwrapped.peeled.some(runsOpaqueCommandLine) ||
+    unwrapped.peeled.some(carriesComputedWord)
   ) {
     return undefined;
   }
@@ -211,6 +217,17 @@ function runsOpaqueCommandLine(layer: readonly CommandWord[]): boolean {
   return name !== undefined && OPAQUE_COMMAND_LINE_WRAPPERS.has(name);
 }
 
+/**
+ * True when the shell may rewrite a word a peeled layer passes its wrapper.
+ *
+ * The wrapper name is skipped: it is matched by its text against a fixed
+ * vocabulary, so a computed spelling never classifies as a wrapper, and the
+ * word adapter reads a `command_name` node as computed whatever it spells.
+ */
+function carriesComputedWord(layer: readonly CommandWord[]): boolean {
+  return layer.slice(1).some((word) => word.computed);
+}
+
 /**
  * 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.
@@ -230,9 +247,9 @@ function runsOpaqueCommandLine(layer: readonly CommandWord[]): boolean {
  * 2. Every option in every layer is on that modifier's allowlist. The real
  *    tools accept abbreviations (`timeout --sig KILL 5 rm`) the inner-command
  *    search does not know, and one of them misplaces where the command starts.
- *    Each option, value, and operand must also be literal: the shell splits
- *    `timeout $D pnpm` or expands `timeout {5,sudo} rm` into extra words before
- *    the modifier runs, and one of those may be a wrapper or the real command.
+ *    That every word is also literal is {@link floorExemptionOf}'s condition,
+ *    shared with the core-reader reason: the shell splits `timeout $D pnpm` or
+ *    expands `timeout {5,sudo} rm` into extra words before the modifier runs.
  * 3. The peel ended at an ordinary command, not a wrapper it could not see
  *    past.
  * 4. The inner head is a literal command name. The grammar has no `time`
@@ -267,6 +284,9 @@ function reachedLiteralCommand(inner: readonly CommandWord[]): boolean {
  *
  * Walks the words with the same value-taking table {@link innerCommandIndex}
  * skips by, so an admitted option's value can never be taken for the command.
+ * It reads option shapes only: each caller refuses a computed word before it
+ * gets here ({@link floorExemptionOf}'s literal-layer condition, and
+ * {@link sessionCommandIndex}'s refusal of any token with shell syntax).
  */
 function isAdmittedModifierLayer(layer: readonly CommandWord[]): boolean {
   const name = wrapperName(layer);
@@ -278,15 +298,11 @@ function isAdmittedModifierLayer(layer: readonly CommandWord[]): boolean {
   for (let index = 1; index < layer.length; index++) {
     const word = layer[index].text;
     if (isEnvironmentAssignment(word)) continue;
-    // A word the shell rewrites (`$D`, `{5,sudo}`, `*`) may become several, one
-    // of them a wrapper or the real command, so only a literal word is admitted.
-    if (layer[index].computed) return false;
     if (word === "--") continue;
     if (!word.startsWith("-")) continue;
     if (flags.has(word)) continue;
     if (valueTaking.has(word)) {
       index++;
-      if (layer[index]?.computed) return false;
       continue;
     }
     if (!hasAttachedValue(word, valueTaking)) return false;