@gotgenes/pi-permission-system 9.0.1 → 9.1.0

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).
 
+## [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.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

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

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

@@ -10,6 +10,7 @@ import {
   isSafeSystemPath,
   normalizePathForComparison,
 } from "#src/path-utils";
+import type { BashCommandContext } from "#src/types";
 
 // ── tree-sitter-bash lazy parser ───────────────────────────────────────────
 
@@ -21,6 +22,8 @@ interface TSNode {
   readonly type: string;
   readonly text: string;
   readonly childCount: number;
+  /** False for anonymous tokens (operators, delimiters); true for named nodes. */
+  readonly isNamed: boolean;
   child(index: number): TSNode | null;
 }
 
@@ -55,6 +58,23 @@ function getParser(): Promise<TSParser> {
 
 // ── Parsed bash command representation ───────────────────────────────────────
 
+/**
+ * One command-pattern unit of a parsed bash program.
+ *
+ * Minimal by design — `text` is the simple-command (or whole compound
+ * statement) string matched against the bash rules. The type is the stable
+ * extension point: #306 adds an execution `context`, #307 adds per-command
+ * path candidates and an effective working directory.
+ */
+export interface BashCommand {
+  readonly text: string;
+  /**
+   * Execution context for a nested command (substitution or subshell); absent
+   * for a current-shell (top-level) command.
+   */
+  readonly context?: BashCommandContext;
+}
+
 /**
  * A bash command parsed once into a reusable representation.
  *
@@ -69,7 +89,7 @@ export class BashProgram {
   private constructor(
     private readonly rawTokens: readonly string[],
     private readonly leadingCdTarget: string | undefined,
-    private readonly topLevelCommandTexts: readonly string[],
+    private readonly commandUnits: readonly BashCommand[],
   ) {}
 
   /**
@@ -88,8 +108,8 @@ export class BashProgram {
     try {
       const leadingCdTarget = extractLeadingCdTarget(tree.rootNode);
       const rawTokens = collectPathCandidateTokens(tree.rootNode);
-      const topLevelCommandTexts = collectTopLevelCommandTexts(tree.rootNode);
-      return new BashProgram(rawTokens, leadingCdTarget, topLevelCommandTexts);
+      const commandUnits = collectCommands(tree.rootNode);
+      return new BashProgram(rawTokens, leadingCdTarget, commandUnits);
     } finally {
       tree.delete();
     }
@@ -102,10 +122,6 @@ export class BashProgram {
    * paths; does NOT filter by CWD. Returns deduplicated tokens for rule
    * evaluation.
    */
-  // Used by the facades (bash-path-extractor.ts) and tests. Fallow's syntactic
-  // analysis cannot resolve the static-factory return type (private ctor), so
-  // it reports a false positive here.
-  // fallow-ignore-next-line unused-class-member
   pathTokens(): string[] {
     const seen = new Set<string>();
     const result: string[] = [];
@@ -121,17 +137,7 @@ export class BashProgram {
   }
 
   /**
-   * Deduplicated paths that resolve outside `cwd`.
-   *
-   * When the command begins with `cd <dir> && …`, relative candidate paths are
-   * resolved against `<dir>` (if it stays within CWD) rather than CWD itself,
-   * mirroring how the shell would resolve them.
-   */
-  // Used by the facades (bash-path-extractor.ts) and tests. Fallow's syntactic
-  // analysis cannot resolve the static-factory return type (private ctor), so
-  // it reports a false positive here.
-  /**
-   * The top-level simple-commands of the chain, in source order.
+   * The top-level command-pattern units of the chain, in source order.
    *
    * Splits on the shell chain operators (`&&`, `||`, `;`, `|`, `&`, newlines);
    * quotes, command substitution, and subshells are respected by the parser and
@@ -143,11 +149,17 @@ export class BashProgram {
   // syntactic analysis cannot resolve the static-factory return type (private
   // ctor), so it reports a false positive here.
   // fallow-ignore-next-line unused-class-member
-  topLevelCommands(): string[] {
-    return [...this.topLevelCommandTexts];
+  commands(): BashCommand[] {
+    return [...this.commandUnits];
   }
 
-  // fallow-ignore-next-line unused-class-member
+  /**
+   * Deduplicated paths that resolve outside `cwd`.
+   *
+   * When the command begins with `cd <dir> && …`, relative candidate paths are
+   * resolved against `<dir>` (if it stays within CWD) rather than CWD itself,
+   * mirroring how the shell would resolve them.
+   */
   externalPaths(cwd: string): string[] {
     const resolveBase = computeEffectiveResolveBase(this.leadingCdTarget, cwd);
     const normalizedCwd = normalizePathForComparison(cwd, cwd);
@@ -592,14 +604,12 @@ function collectPathCandidateTokens(node: TSNode): string[] {
 // which exports classifyTokenAsPathCandidate and classifyTokenAsRuleCandidate
 // with a shared rejectNonPathToken predicate eliminating the prior clone.
 
-// ── Top-level command enumeration ───────────────────────────────────────────
+// ── Command enumeration ──────────────────────────────────────────────────────
 
 /**
- * Container node types descended into when enumerating top-level commands.
- * A `cd` or `rm` inside a subshell or compound statement is NOT a top-level
- * command, so those node types are deliberately absent.
+ * Container node types descended into when enumerating command units.
  */
-const TOP_LEVEL_COMMAND_DESCEND = new Set([
+const COMMAND_ENUM_DESCEND = new Set([
   "program",
   "list",
   "pipeline",
@@ -607,18 +617,12 @@ const TOP_LEVEL_COMMAND_DESCEND = new Set([
 ]);
 
 /**
- * Node types skipped during top-level command enumeration: chain-operator and
- * separator tokens, redirect targets, comments, and heredoc bodies. None of
- * these is a command to evaluate.
+ * Named node types skipped during command enumeration: redirect targets,
+ * comments, and heredoc bodies — none is a command to evaluate. Anonymous
+ * tokens (chain operators `&&`/`;`/`|`, substitution and subshell delimiters
+ * `$(`/`)`/`` ` ``/`(`) are filtered by the `isNamed` guard, not listed here.
  */
-const TOP_LEVEL_COMMAND_SKIP = new Set([
-  "&&",
-  "||",
-  ";",
-  "&",
-  "|",
-  "|&",
-  "\n",
+const COMMAND_ENUM_SKIP = new Set([
   "file_redirect",
   "heredoc_redirect",
   "herestring_redirect",
@@ -628,29 +632,105 @@ const TOP_LEVEL_COMMAND_SKIP = new Set([
 ]);
 
 /**
- * Collect the text of each top-level simple-command in the program.
+ * Nested execution contexts whose interior commands really execute and must be
+ * evaluated too: command substitution (`$(…)`, backticks) and process
+ * substitution (`<(…)`/`>(…)`). Subshells (`( … )`) are handled separately
+ * because they are also emitted whole.
+ */
+const NESTED_EXECUTION_CONTEXTS = new Map<string, BashCommandContext>([
+  ["command_substitution", "command_substitution"],
+  ["process_substitution", "process_substitution"],
+]);
+
+/**
+ * Enumerate the command units of a bash program, in source order.
  *
  * Descends container nodes (`program`, `list`, `pipeline`, `redirected_statement`)
- * and emits each `command` node's text. Chain-operator tokens and redirect
- * targets are skipped. Any other top-level statement node (subshell, compound
- * statement, control-flow) is emitted whole without descending, so its inner
- * commands are matched as part of the enclosing statement's text rather than
- * independently (the top-level scope).
+ * and emits each `command` node whole. Additionally descends into the three
+ * nested execution contexts — command substitution (`$(…)`, backticks), process
+ * substitution (`<(…)`/`>(…)`), and subshells (`( … )`) — emitting each inner
+ * command as its own unit *in addition to* the enclosing command, since those
+ * inner commands really execute (#306). Control-flow bodies and `{ … }` brace
+ * groups are emitted whole without descending (deferred).
+ *
+ * The enclosing command/subshell is always still emitted whole, so adding the
+ * nested units can only ever produce a more-restrictive decision, never weaker.
  */
-function collectTopLevelCommandTexts(node: TSNode): string[] {
-  if (node.type === "command") return [node.text];
-  if (TOP_LEVEL_COMMAND_SKIP.has(node.type)) return [];
-  if (TOP_LEVEL_COMMAND_DESCEND.has(node.type)) {
-    const texts: string[] = [];
-    for (let i = 0; i < node.childCount; i++) {
-      const child = node.child(i);
-      if (child) texts.push(...collectTopLevelCommandTexts(child));
+function collectCommands(node: TSNode): BashCommand[] {
+  const out: BashCommand[] = [];
+  collectCommandsInto(node, undefined, out);
+  return out;
+}
+
+function collectCommandsInto(
+  node: TSNode,
+  context: BashCommandContext | undefined,
+  out: BashCommand[],
+): void {
+  // Anonymous tokens (operators `&&`/`;`/`|`, delimiters `$(`/`)`/`` ` ``/`(`)
+  // carry no command.
+  if (!node.isNamed) return;
+  if (COMMAND_ENUM_SKIP.has(node.type)) return;
+
+  if (node.type === "command") {
+    out.push(makeUnit(node.text, context));
+    // A command's text already contains any substitution; descend its subtree
+    // to ALSO emit the inner commands of command/process substitutions.
+    collectSubstitutionCommands(node, out);
+    return;
+  }
+
+  if (node.type === "subshell") {
+    out.push(makeUnit(node.text, context)); // never-weaker whole emit
+    descendCommandChildren(node, "subshell", out);
+    return;
+  }
+
+  if (COMMAND_ENUM_DESCEND.has(node.type)) {
+    descendCommandChildren(node, context, out);
+    return;
+  }
+
+  // Any other named statement (compound_statement `{ … }`, if/while/for/case,
+  // function_definition): emit whole, do not descend — deferred (#306).
+  out.push(makeUnit(node.text, context));
+}
+
+function makeUnit(
+  text: string,
+  context: BashCommandContext | undefined,
+): BashCommand {
+  return context ? { text, context } : { text };
+}
+
+function descendCommandChildren(
+  node: TSNode,
+  context: BashCommandContext | undefined,
+  out: BashCommand[],
+): void {
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child) collectCommandsInto(child, context, out);
+  }
+}
+
+/**
+ * Search a command's subtree for command/process substitutions and enumerate
+ * the commands inside them, tagged with the substitution's execution context.
+ * A substitution can nest under `command_name` (when the whole command is
+ * `$(…)`) or under an argument, so the entire subtree is searched.
+ */
+function collectSubstitutionCommands(node: TSNode, out: BashCommand[]): void {
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    const nestedContext = NESTED_EXECUTION_CONTEXTS.get(child.type);
+    if (nestedContext) {
+      descendCommandChildren(child, nestedContext, out);
+    } else {
+      collectSubstitutionCommands(child, out);
     }
-    return texts;
   }
-  // Any other named statement node (subshell, compound_statement, if/while/for,
-  // function_definition, …): emit whole, do not descend.
-  return [node.text];
 }
 
 // ── Leading cd detection ───────────────────────────────────────────────────

package/src/handlers/permission-gate-handler.ts

@@ -29,6 +29,7 @@ import {
 import { resolveBashCommandCheck } from "./gates/bash-command";
 import { describeBashExternalDirectoryGate } from "./gates/bash-external-directory";
 import { describeBashPathGate } from "./gates/bash-path";
+import { BashProgram } from "./gates/bash-program";
 import type { GateResult, GateRunnerDeps } from "./gates/descriptor";
 import { isGateBypass } from "./gates/descriptor";
 import { describeExternalDirectoryGate } from "./gates/external-directory";
@@ -87,6 +88,14 @@ export class PermissionGateHandler {
       cwd: ctx.cwd,
     };
 
+    // Parse the bash command exactly once per tool_call; the three bash gates
+    // share this single BashProgram instead of each re-parsing (#308).
+    const command = getNonEmptyString(toRecord(tcc.input).command);
+    const bashProgram =
+      tcc.toolName === "bash" && command
+        ? await BashProgram.parse(command)
+        : null;
+
     // ── Shared gate adapter closures ─────────────────────────────────────
     const canConfirm = () => this.session.canPrompt(ctx);
     const promptPermission = (details: PromptPermissionDetails) =>
@@ -166,19 +175,27 @@ export class PermissionGateHandler {
       () =>
         describeBashExternalDirectoryGate(
           tcc,
+          bashProgram,
+          checkPermission,
+          getSessionRuleset,
+        ),
+      () =>
+        describeBashPathGate(
+          tcc,
+          bashProgram,
           checkPermission,
           getSessionRuleset,
         ),
-      () => describeBashPathGate(tcc, checkPermission, getSessionRuleset),
-      async () => {
+      () => {
         // Bash commands may chain several sub-commands (`a && b`, `a | b`, …);
-        // evaluate each on the bash surface and select the most restrictive,
-        // rather than matching the whole program string (#301). Other tools
-        // evaluate their single input directly.
+        // evaluate each unit from the shared parse on the bash surface and
+        // select the most restrictive, rather than matching the whole program
+        // string (#301). Other tools evaluate their single input directly.
         const toolCheck =
-          tcc.toolName === "bash"
-            ? await resolveBashCommandCheck(
-                getNonEmptyString(toRecord(tcc.input).command) ?? "",
+          tcc.toolName === "bash" && bashProgram
+            ? resolveBashCommandCheck(
+                command ?? "",
+                bashProgram.commands(),
                 tcc.agentName ?? undefined,
                 getSessionRuleset(),
                 checkPermission,

package/src/permission-prompts.ts

@@ -1,3 +1,4 @@
+import { matchQualifier } from "./denial-messages";
 import type { SkillPromptEntry } from "./skill-prompt-sanitizer";
 import type { ToolPreviewFormatter } from "./tool-preview-formatter";
 import type { PermissionCheckResult } from "./types";
@@ -36,10 +37,12 @@ export function formatAskPrompt(
   const subject = agentName ? `Agent '${agentName}'` : "Current agent";
 
   if (result.toolName === "bash") {
-    const patternInfo = result.matchedPattern
-      ? ` (matched '${result.matchedPattern}')`
-      : "";
-    return `${subject} requested bash command '${result.command ?? ""}'${patternInfo}. Allow this command?`;
+    const qualifier = matchQualifier(
+      result.matchedPattern,
+      result.commandContext,
+    );
+    const qualifierInfo = qualifier ? ` ${qualifier}` : "";
+    return `${subject} requested bash command '${result.command ?? ""}'${qualifierInfo}. Allow this command?`;
   }
 
   if ((result.source === "mcp" || result.toolName === "mcp") && result.target) {

package/src/types.ts

@@ -22,6 +22,15 @@ export interface ScopeConfig {
   permission?: FlatPermissionConfig;
 }
 
+/**
+ * Execution context of a bash command nested inside a substitution or subshell.
+ * Absent for current-shell (top-level) commands.
+ */
+export type BashCommandContext =
+  | "command_substitution"
+  | "process_substitution"
+  | "subshell";
+
 export interface PermissionCheckResult {
   toolName: string;
   state: PermissionState;
@@ -31,4 +40,10 @@ export interface PermissionCheckResult {
   source: "tool" | "bash" | "mcp" | "skill" | "special" | "default" | "session";
   /** Which source contributed the winning rule. */
   origin: RuleOrigin;
+  /**
+   * Execution context of the offending nested command, when the winning bash
+   * unit came from a substitution or subshell. Absent for current-shell
+   * (top-level) commands.
+   */
+  commandContext?: BashCommandContext;
 }