@gotgenes/pi-permission-system 9.0.0 → 9.1.0

package/CHANGELOG.md

@@ -5,6 +5,33 @@ 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).
 
+## [9.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v9.0.1...pi-permission-system-v9.1.0) (2026-06-02)
+
+
+### Features
+
+* evaluate nested bash command substitutions and subshells ([#306](https://github.com/gotgenes/pi-packages/issues/306)) ([0e52d64](https://github.com/gotgenes/pi-packages/commit/0e52d645bc2f604b1317781edf48578936e0ae34))
+* surface nested execution context in bash deny and ask messages ([#306](https://github.com/gotgenes/pi-packages/issues/306)) ([9d88543](https://github.com/gotgenes/pi-packages/commit/9d88543c855d16910d71c7e783c451160753c52d))
+
+
+### Documentation
+
+* document nested bash command evaluation ([#306](https://github.com/gotgenes/pi-packages/issues/306)) ([352e206](https://github.com/gotgenes/pi-packages/commit/352e206ce673ba73d57b1a4dbf24a409adf32e70))
+
+## [9.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v9.0.0...pi-permission-system-v9.0.1) (2026-06-01)
+
+
+### Bug Fixes
+
+* enumerate top-level bash commands in BashProgram ([cdb41e1](https://github.com/gotgenes/pi-packages/commit/cdb41e1ed03ad2219f5ba0a3ec79130bd39f3686))
+* evaluate each bash sub-command with most-restrictive precedence ([85e48b2](https://github.com/gotgenes/pi-packages/commit/85e48b258dad84756a05fe11615d6d5de68a8659))
+* gate bash command chains per sub-command ([#301](https://github.com/gotgenes/pi-packages/issues/301)) ([3f80097](https://github.com/gotgenes/pi-packages/commit/3f800977a909b2efc2a21ffefe933804b1c0eafd))
+
+
+### Documentation
+
+* document per-sub-command bash chain evaluation ([#301](https://github.com/gotgenes/pi-packages/issues/301)) ([e195a70](https://github.com/gotgenes/pi-packages/commit/e195a706d192f3acaeb232c6ed580890ac3c0652))
+
 ## [9.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v8.3.2...pi-permission-system-v9.0.0) (2026-06-01)
 
 

package/package.json

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

package/src/denial-messages.ts

@@ -1,5 +1,5 @@
 import { EXTENSION_ID } from "./extension-config";
-import type { PermissionCheckResult } from "./types";
+import type { BashCommandContext, PermissionCheckResult } from "./types";
 
 // ── Extension attribution tag ──────────────────────────────────────────────
 
@@ -114,13 +114,54 @@ function buildToolDenyBody(
     parts.push(`command '${check.command}'`);
   }
 
-  if (check.matchedPattern) {
-    parts.push(`(matched '${check.matchedPattern}')`);
+  const qualifier = matchQualifier(check.matchedPattern, check.commandContext);
+  if (qualifier) {
+    parts.push(qualifier);
   }
 
   return `${parts.join(" ")}.`;
 }
 
+/**
+ * Human-readable label for a nested bash execution context, or `undefined` for
+ * a current-shell (top-level) command.
+ */
+export function describeBashCommandContext(
+  context?: BashCommandContext,
+): string | undefined {
+  switch (context) {
+    case "command_substitution":
+      return "command substitution";
+    case "process_substitution":
+      return "process substitution";
+    case "subshell":
+      return "subshell";
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Build the parenthetical qualifier for a bash decision, folding the matched
+ * rule and (for a nested command) its execution context into one clause, e.g.
+ * `(matched 'rm *', inside command substitution)`. Returns `""` when neither
+ * applies.
+ */
+export function matchQualifier(
+  matchedPattern?: string,
+  context?: BashCommandContext,
+): string {
+  const parts: string[] = [];
+  if (matchedPattern) {
+    parts.push(`matched '${matchedPattern}'`);
+  }
+  const label = describeBashCommandContext(context);
+  if (label) {
+    parts.push(`inside ${label}`);
+  }
+  return parts.length > 0 ? `(${parts.join(", ")})` : "";
+}
+
 function buildUnavailableBody(ctx: DenialContext): string {
   switch (ctx.kind) {
     case "tool": {

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

@@ -0,0 +1,57 @@
+import type { BashCommand } from "#src/handlers/gates/bash-program";
+import { pickMostRestrictive } from "#src/handlers/gates/candidate-check";
+import type { Rule } from "#src/rule";
+import type { PermissionCheckResult } from "#src/types";
+
+/** Function type for checkPermission used by the resolver. */
+type CheckPermissionFn = (
+  surface: string,
+  input: unknown,
+  agentName?: string,
+  sessionRules?: Rule[],
+) => PermissionCheckResult;
+
+/**
+ * Resolve the bash command-pattern decision for a (possibly chained) command.
+ *
+ * A bash invocation may be a shell program with several commands joined by
+ * `&&`, `||`, `;`, `|`, `&`, or newlines. Matching the whole string against the
+ * bash patterns lets a denied command ride through on an allowed leading one
+ * (issue #301). Instead, the caller supplies the program's command units (from
+ * the shared `BashProgram.commands()` parse) — including those nested inside
+ * substitutions and subshells (#306); each is evaluated on the `bash` surface
+ * and the most restrictive result wins (`deny > ask > allow`).
+ *
+ * The selected result carries the offending sub-command in `command`, its rule
+ * in `matchedPattern`, and the offending command's execution context in
+ * `commandContext` (set only for a nested command), so the prompt,
+ * session-approval suggestion, and decision event scope to that command.
+ *
+ * When `commands` is empty (an empty command, a comment, or a bare compound
+ * statement), the whole `command` is evaluated as before, so the surface is
+ * never weaker than the previous behavior.
+ *
+ * Pure and synchronous: the (async, tree-sitter) parse happens once in the
+ * handler, which passes the decomposed `commands` here.
+ */
+export function resolveBashCommandCheck(
+  command: string,
+  commands: BashCommand[],
+  agentName: string | undefined,
+  sessionRules: Rule[],
+  checkPermission: CheckPermissionFn,
+): PermissionCheckResult {
+  const results = commands.map((cmd) => {
+    const result = checkPermission(
+      "bash",
+      { command: cmd.text },
+      agentName,
+      sessionRules,
+    );
+    return cmd.context ? { ...result, commandContext: cmd.context } : result;
+  });
+  return (
+    pickMostRestrictive(results) ??
+    checkPermission("bash", { command }, agentName, sessionRules)
+  );
+}

package/src/handlers/gates/bash-external-directory.ts

@@ -3,7 +3,8 @@ import type { Rule } from "#src/rule";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { PermissionCheckResult } from "#src/types";
-import { extractExternalPathsFromBashCommand } from "./bash-path-extractor";
+import type { BashProgram } from "./bash-program";
+import { pickMostRestrictive } from "./candidate-check";
 import type { GateResult } from "./descriptor";
 import { formatBashExternalDirectoryAskPrompt } from "./external-directory-messages";
 import type { ToolCallContext } from "./types";
@@ -19,26 +20,26 @@ type CheckPermissionFn = (
 /**
  * Build a pure descriptor for the bash external-directory permission gate.
  *
- * Extracts paths from a bash command and checks whether any reference
- * directories outside the working directory. Returns `null` when the gate
+ * Reads the external paths from the injected `BashProgram` and checks whether
+ * any reference directories outside the working directory. Returns `null` when the gate
  * does not apply (tool is not bash, no CWD, or no external paths found).
  * Returns a `GateBypass` when all paths are allowed (by config or session rule).
  * Returns a `GateDescriptor` with multi-pattern sessionApproval for uncovered paths.
  */
-export async function describeBashExternalDirectoryGate(
+export function describeBashExternalDirectoryGate(
   tcc: ToolCallContext,
+  bashProgram: BashProgram | null,
   checkPermission: CheckPermissionFn,
   getSessionRuleset: () => Rule[],
-): Promise<GateResult> {
+): GateResult {
   if (tcc.toolName !== "bash" || !tcc.cwd) return null;
 
   const command = getNonEmptyString(toRecord(tcc.input).command);
   if (!command) return null;
 
-  const externalPaths = await extractExternalPathsFromBashCommand(
-    command,
-    tcc.cwd,
-  );
+  if (!bashProgram) return null;
+
+  const externalPaths = bashProgram.externalPaths(tcc.cwd);
   if (externalPaths.length === 0) return null;
 
   const bashSessionRules = getSessionRuleset();
@@ -85,7 +86,7 @@ export async function describeBashExternalDirectoryGate(
   // This ensures a config-level "deny" rule is not downgraded to "ask" by the
   // generic "*" catch-all that the old path-less checkPermission call returned.
   const worstCheck =
-    uncoveredEntries.find(({ check }) => check.state === "deny")?.check ??
+    pickMostRestrictive(uncoveredEntries.map(({ check }) => check)) ??
     uncoveredEntries[0].check;
 
   const bashExtMessage = formatBashExternalDirectoryAskPrompt(