@gotgenes/pi-permission-system 40.1.3 → 40.1.4

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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)
 
 

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.3",
+  "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";
@@ -245,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 ?? "")
   );
@@ -309,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 ───────────────────────────────────────────────────────────────
 
 /**
@@ -959,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([
   "!",

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.
  *