@gotgenes/pi-permission-system 9.0.1 → 9.2.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v9.1.0...pi-permission-system-v9.2.0) (2026-06-02)
+
+
+### Features
+
+* flag relative paths conservatively after a non-literal cd ([6e631a0](https://github.com/gotgenes/pi-packages/commit/6e631a0c62633e0be3a498752a3bf3614d357d65)), closes [#307](https://github.com/gotgenes/pi-packages/issues/307)
+* fold sequential current-shell cd into the bash effective directory ([7fd8e95](https://github.com/gotgenes/pi-packages/commit/7fd8e9525196ffa558a2b59ea9f4cf66943f9010)), closes [#307](https://github.com/gotgenes/pi-packages/issues/307)
+* scope cd inside subshells and persist it across brace groups ([37b948c](https://github.com/gotgenes/pi-packages/commit/37b948c7e9fd5d9ddac3aa8c6b456039132f7c4e)), closes [#307](https://github.com/gotgenes/pi-packages/issues/307)
+
+## [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)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "9.0.1",
+  "version": "9.2.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

@@ -1,4 +1,4 @@
-import { BashProgram } from "#src/handlers/gates/bash-program";
+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";
@@ -11,43 +11,45 @@ type CheckPermissionFn = (
   sessionRules?: Rule[],
 ) => PermissionCheckResult;
 
-/** Decompose a bash command into its top-level simple-commands. */
-async function decomposeTopLevelCommands(command: string): Promise<string[]> {
-  return (await BashProgram.parse(command)).topLevelCommands();
-}
-
 /**
  * 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, decompose the command into its top-level simple-commands
- * and evaluate each on the `bash` surface, then select the most restrictive
- * result (`deny > ask > allow`).
+ * (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` and its
- * rule in `matchedPattern`, so the prompt, session-approval suggestion, and
- * decision event scope to that command.
+ * 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 decomposition yields no top-level commands (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.
+ * 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.
  *
- * `checkPermission` stays synchronous and single-command; only the decomposition
- * is async (tree-sitter). `decompose` is injectable for testing.
+ * Pure and synchronous: the (async, tree-sitter) parse happens once in the
+ * handler, which passes the decomposed `commands` here.
  */
-export async function resolveBashCommandCheck(
+export function resolveBashCommandCheck(
   command: string,
+  commands: BashCommand[],
   agentName: string | undefined,
   sessionRules: Rule[],
   checkPermission: CheckPermissionFn,
-  decompose: (command: string) => Promise<string[]> = decomposeTopLevelCommands,
-): Promise<PermissionCheckResult> {
-  const units = await decompose(command);
-  const results = units.map((unit) =>
-    checkPermission("bash", { command: unit }, agentName, sessionRules),
-  );
+): 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,7 @@ 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";
@@ -20,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();

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

@@ -3,7 +3,7 @@ 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 { extractTokensForPathRules } from "./bash-path-extractor";
+import type { BashProgram } from "./bash-program";
 import { pickMostRestrictive } from "./candidate-check";
 import type { GateResult } from "./descriptor";
 import { formatPathAskPrompt } from "./path";
@@ -20,8 +20,8 @@ type CheckPermissionFn = (
 /**
  * Build a pure descriptor for the cross-cutting path permission gate (bash).
  *
- * Extracts path-candidate tokens from a bash command using tree-sitter with
- * the broader filter (accepts dot-files, relative paths). Evaluates each
+ * Reads path-candidate tokens from the injected `BashProgram` (the broader
+ * `path`-rule filter, accepting dot-files and relative paths). Evaluates each
  * token against the `path` permission surface and returns the most
  * restrictive result.
  *
@@ -30,17 +30,20 @@ type CheckPermissionFn = (
  * Returns a `GateBypass` when all tokens are session-covered.
  * Returns a `GateDescriptor` for the most restrictive token needing a check.
  */
-export async function describeBashPathGate(
+export function describeBashPathGate(
   tcc: ToolCallContext,
+  bashProgram: BashProgram | null,
   checkPermission: CheckPermissionFn,
   getSessionRuleset: () => Rule[],
-): Promise<GateResult> {
+): GateResult {
   if (tcc.toolName !== "bash") return null;
 
   const command = getNonEmptyString(toRecord(tcc.input).command);
   if (!command) return null;
 
-  const tokens = await extractTokensForPathRules(command);
+  if (!bashProgram) return null;
+
+  const tokens = bashProgram.pathTokens();
   if (tokens.length === 0) return null;
 
   // Check each token against path rules with session rules appended.