@gotgenes/pi-permission-system 9.0.1 → 9.2.0

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

@@ -1,5 +1,5 @@
 import { createRequire } from "node:module";
-import { basename, resolve } from "node:path";
+import { basename, isAbsolute, join, resolve } from "node:path";
 
 import {
   classifyTokenAsPathCandidate,
@@ -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,46 @@ 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;
+}
+
+/**
+ * The working directory in force where a path candidate appears.
+ *
+ * A `known` base carries an `offset` to be joined with `cwd` at resolution time
+ * (the parse-time walk never sees `cwd`): a relative-or-absolute path string
+ * built by folding the literal targets of current-shell `cd` commands (`""` =
+ * `cwd`); an absolute offset (from `cd /abs`) ignores `cwd` at resolution time.
+ * An `unknown` base marks a non-literal `cd` target (`cd "$DIR"`, `cd $(…)`,
+ * `cd -`, bare `cd`, `cd ~…`) that made the effective directory unresolvable.
+ */
+type EffectiveBase =
+  | { readonly kind: "known"; readonly offset: string }
+  | { readonly kind: "unknown" };
+
+/**
+ * A path-candidate token paired with the effective working directory projected
+ * onto the point in the command stream where it appears.
+ */
+interface PathCandidate {
+  readonly token: string;
+  readonly base: EffectiveBase;
+}
+
 /**
  * A bash command parsed once into a reusable representation.
  *
@@ -67,29 +110,29 @@ function getParser(): Promise<TSParser> {
  */
 export class BashProgram {
   private constructor(
-    private readonly rawTokens: readonly string[],
-    private readonly leadingCdTarget: string | undefined,
-    private readonly topLevelCommandTexts: readonly string[],
+    private readonly rawCandidates: readonly PathCandidate[],
+    private readonly commandUnits: readonly BashCommand[],
   ) {}
 
   /**
    * Parse a bash command into a `BashProgram`.
    *
-   * Uses tree-sitter-bash to build the full AST, walks command-argument and
-   * redirect-destination nodes once into raw candidate tokens, and records the
-   * leading `cd` target. Heredoc bodies, comments, and other non-argument
-   * content are skipped. An unparseable command yields an empty program.
+   * Uses tree-sitter-bash to build the full AST and walks command-argument and
+   * redirect-destination nodes once into raw candidate tokens, each tagged with
+   * the effective working directory projected onto its position by folding
+   * current-shell `cd` commands. Heredoc bodies, comments, and other
+   * non-argument content are skipped. An unparseable command yields an empty
+   * program.
    */
   static async parse(command: string): Promise<BashProgram> {
     const parser = await getParser();
     const tree = parser.parse(command);
-    if (!tree) return new BashProgram([], undefined, []);
+    if (!tree) return new BashProgram([], []);
 
     try {
-      const leadingCdTarget = extractLeadingCdTarget(tree.rootNode);
-      const rawTokens = collectPathCandidateTokens(tree.rootNode);
-      const topLevelCommandTexts = collectTopLevelCommandTexts(tree.rootNode);
-      return new BashProgram(rawTokens, leadingCdTarget, topLevelCommandTexts);
+      const rawCandidates = collectPathCandidates(tree.rootNode);
+      const commandUnits = collectCommands(tree.rootNode);
+      return new BashProgram(rawCandidates, commandUnits);
     } finally {
       tree.delete();
     }
@@ -102,14 +145,10 @@ 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[] = [];
-    for (const token of this.rawTokens) {
+    for (const { token } of this.rawCandidates) {
       const candidate = classifyTokenAsRuleCandidate(token);
       if (!candidate) continue;
       if (!seen.has(candidate)) {
@@ -121,17 +160,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,22 +172,49 @@ 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`.
+   *
+   * Each candidate is resolved against the effective working directory in force
+   * where it appears, projected by folding a sequence of current-shell `cd`
+   * commands (joined by `&&`, `||`, `;`, or a newline). A `cd` inside a
+   * pipeline or a backgrounded command runs in a subshell and does not update
+   * the running directory.
+   */
   externalPaths(cwd: string): string[] {
-    const resolveBase = computeEffectiveResolveBase(this.leadingCdTarget, cwd);
     const normalizedCwd = normalizePathForComparison(cwd, cwd);
 
     const seen = new Set<string>();
     const externalPaths: string[] = [];
 
-    for (const token of this.rawTokens) {
+    for (const { token, base } of this.rawCandidates) {
       const candidate = classifyTokenAsPathCandidate(token);
       if (!candidate) continue;
 
+      // Unknown effective directory: a relative candidate could resolve
+      // anywhere, so flag it conservatively (resolving against `cwd` only for a
+      // display path). Absolute / `~` candidates are base-independent and
+      // resolve normally below.
+      if (base.kind === "unknown" && isRelativeCandidate(candidate)) {
+        const normalized = normalizePathForComparison(candidate, cwd);
+        if (
+          normalized &&
+          normalizedCwd !== "" &&
+          !isSafeSystemPath(normalized) &&
+          !seen.has(normalized)
+        ) {
+          seen.add(normalized);
+          externalPaths.push(normalized);
+        }
+        continue;
+      }
+
+      const resolveBase =
+        base.kind === "known" ? resolve(cwd, base.offset) : cwd;
       const normalized = normalizePathForComparison(candidate, resolveBase);
       if (!normalized) continue;
 
@@ -592,14 +648,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 +661,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,100 +676,300 @@ 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 ───────────────────────────────────────────────────
+// ── Effective working directory projection ─────────────────────────────────
+
+/** The working directory in force at the start of a program (`cwd`). */
+const CWD_BASE: EffectiveBase = { kind: "known", offset: "" };
+
+/** The effective directory after a non-literal or unresolvable `cd`. */
+const UNKNOWN_BASE: EffectiveBase = { kind: "unknown" };
 
 /**
- * Walk down from the root to find the first `command` node in the program.
+ * Walk the AST once, collecting every path-candidate token tagged with the
+ * effective working directory projected onto its position.
  *
- * Only descends into `program` and `list` nodes — subshells, pipelines, and
- * other compound statements are ignored because a `cd` inside them does not
- * affect the outer shell's working directory.
+ * The effective directory is stateful: it starts at `cwd` and each current-shell
+ * `cd <literal>` (joined by `&&`, `||`, `;`, or a newline) folds into it for
+ * subsequent commands. A `cd` inside a pipeline or a backgrounded command runs
+ * in a subshell and does not update the running directory; subshell and
+ * brace-group interiors inherit the enclosing base without folding their own
+ * `cd`s (a conservative first tier).
+ */
+function collectPathCandidates(rootNode: TSNode): PathCandidate[] {
+  const out: PathCandidate[] = [];
+  walkForCandidates(rootNode, CWD_BASE, out);
+  return out;
+}
+
+/**
+ * Collect a single node's candidates tagged with `base`, returning the
+ * effective base in force *after* the node (the input base unless the node is a
+ * current-shell `cd <literal>` that folds the running directory).
  */
-function findFirstCommand(node: TSNode): TSNode | null {
-  if (node.type === "command") return node;
-  if (node.type === "program" || node.type === "list") {
-    const firstChild = node.child(0);
-    if (firstChild) return findFirstCommand(firstChild);
+function walkForCandidates(
+  node: TSNode,
+  base: EffectiveBase,
+  out: PathCandidate[],
+): EffectiveBase {
+  switch (node.type) {
+    case "program":
+    case "list":
+    case "redirected_statement":
+      return walkCurrentShellSequence(node, base, out);
+    case "command":
+      tagTokens(collectCommandTokens(node), base, out);
+      return foldCd(node, base);
+    case "subshell":
+      // A subshell runs in a child shell: its interior `cd`s fold within the
+      // subshell but reset on exit, so the folded base is discarded.
+      walkCurrentShellSequence(node, base, out);
+      return base;
+    case "compound_statement":
+      // A `{ … }` brace group runs in the current shell, so its `cd`s persist
+      // to following commands — thread and return the folded base.
+      return walkCurrentShellSequence(node, base, out);
+    default:
+      // Pipelines, control-flow bodies, redirect targets, and command/process
+      // substitution interiors: collect every candidate in the subtree tagged
+      // with the enclosing base and do not fold their internal `cd`s. (Folding
+      // inside substitutions is deferred — conservative, never under-flags.)
+      tagTokens(collectPathCandidateTokens(node), base, out);
+      return base;
   }
-  return null;
 }
 
 /**
- * Extract the target directory of a leading `cd` command from the parsed AST.
- *
- * When a bash command begins with `cd <dir> && …`, the shell resolves
- * subsequent relative paths against `<dir>`, not the original working
- * directory.  The external-directory guard must do the same, otherwise a
- * path that the shell keeps inside the working directory can appear to
- * escape it and trigger a spurious permission prompt.
- *
- * Returns `undefined` when the first command is not `cd`, or when the
- * target cannot be meaningfully resolved (`cd -`, bare `cd`, or `cd ~…`).
+ * Fold a current-shell sequence (`program` / `list` / `redirected_statement`):
+ * thread the effective base left-to-right through the children so a `cd` updates
+ * the base for following siblings. A statement immediately followed by the
+ * background operator (`&`) runs in a subshell, so its folded base is discarded.
  */
-function extractLeadingCdTarget(rootNode: TSNode): string | undefined {
-  const firstCmd = findFirstCommand(rootNode);
-  if (!firstCmd) return undefined;
+function walkCurrentShellSequence(
+  seqNode: TSNode,
+  base: EffectiveBase,
+  out: PathCandidate[],
+): EffectiveBase {
+  let current = base;
+  for (let i = 0; i < seqNode.childCount; i++) {
+    const child = seqNode.child(i);
+    if (!child?.isNamed) continue;
+    if (SKIP_SUBTREE_TYPES.has(child.type)) continue;
+    const after = walkForCandidates(child, current, out);
+    current = isBackgrounded(seqNode, i) ? current : after;
+  }
+  return current;
+}
 
-  const cmdName = extractCommandName(firstCmd);
-  if (cmdName !== "cd") return undefined;
+/**
+ * True when the statement at `index` is immediately followed by the background
+ * operator (`&`) — distinct from the `&&` / `||` / `;` current-shell separators.
+ */
+function isBackgrounded(seqNode: TSNode, index: number): boolean {
+  const next = seqNode.child(index + 1);
+  if (!next || next.isNamed) return false;
+  return next.type === "&";
+}
+
+function tagTokens(
+  tokens: readonly string[],
+  base: EffectiveBase,
+  out: PathCandidate[],
+): void {
+  for (const token of tokens) out.push({ token, base });
+}
+
+/**
+ * True when a path candidate is relative (resolved against the effective
+ * directory) rather than absolute (`/…`) or home-relative (`~…`), which are
+ * base-independent. Used to decide which candidates an unknown base affects.
+ */
+function isRelativeCandidate(candidate: string): boolean {
+  return !candidate.startsWith("/") && !candidate.startsWith("~");
+}
 
-  for (let i = 0; i < firstCmd.childCount; i++) {
-    const child = firstCmd.child(i);
+/**
+ * Compute the effective base after a command runs. Returns `base` unchanged
+ * unless the command is `cd`:
+ *
+ * - `cd /abs` (absolute literal) → a fresh known base, recovering from an
+ *   earlier unknown base.
+ * - `cd rel` (relative literal) → fold into a known base, or stay unknown if the
+ *   base was already unknown.
+ * - `cd "$DIR"` / `cd $(…)` / `cd -` / bare `cd` / `cd ~…` (non-literal) →
+ *   unknown.
+ */
+function foldCd(commandNode: TSNode, base: EffectiveBase): EffectiveBase {
+  if (extractCommandName(commandNode) !== "cd") return base;
+  const target = cdLiteralTarget(commandNode);
+  if (target === null) return UNKNOWN_BASE;
+  if (isAbsolute(target)) return { kind: "known", offset: target };
+  if (base.kind === "unknown") return UNKNOWN_BASE;
+  return { kind: "known", offset: join(base.offset, target) };
+}
+
+/**
+ * Resolve the literal target of a `cd` command, or `null` when the first
+ * argument is not a static literal (contains an expansion or command
+ * substitution) or cannot be resolved against the working directory (`cd -`,
+ * `cd ~…`, bare `cd`).
+ */
+function cdLiteralTarget(commandNode: TSNode): string | null {
+  for (let i = 0; i < commandNode.childCount; i++) {
+    const child = commandNode.child(i);
     if (!child) continue;
     if (child.type === "command_name" || child.type === "variable_assignment")
       continue;
-    if (!ARG_NODE_TYPES.has(child.type)) continue;
-
-    const text = resolveNodeText(child);
-    // Skip `--` (end-of-flags marker)
-    if (text === "--") continue;
-    // `cd -` jumps to $OLDPWD; `cd ~…` is home-relative — neither can be
-    // resolved against the working directory.
-    if (text === "-" || text.startsWith("~")) return undefined;
-    return text;
+    if (!child.isNamed) continue;
+    // Skip the `--` end-of-flags marker; the next argument is the target.
+    if (child.type === "word" && child.text === "--") continue;
+    if (!ARG_NODE_TYPES.has(child.type)) return null;
+    return literalTextOf(child);
   }
-  return undefined;
+  return null;
 }
 
 /**
- * Compute the effective base directory for resolving relative path candidates.
- *
- * When the leading `cd` target stays within the working directory, subsequent
- * relative paths should be resolved against it.  An escaping target is itself
- * an external access (reported via its own candidate token) and must never
- * silence checks on subsequent paths, so the function falls back to `cwd`.
+ * The literal string value of an argument node, or `null` when it contains a
+ * variable expansion / command substitution or is a non-resolvable `cd`
+ * destination (`-`, `~…`).
  */
-function computeEffectiveResolveBase(
-  cdTarget: string | undefined,
-  cwd: string,
-): string {
-  if (cdTarget === undefined) return cwd;
-  const resolved = resolve(cwd, cdTarget);
-  const normalizedCwd = resolve(cwd);
-  return isPathWithinDirectory(resolved, normalizedCwd) ? resolved : cwd;
+function literalTextOf(node: TSNode): string | null {
+  switch (node.type) {
+    case "word": {
+      const text = node.text;
+      if (text === "-" || text.startsWith("~")) return null;
+      return text;
+    }
+    case "raw_string": {
+      const text = node.text;
+      return text.length >= 2 && text.startsWith("'") && text.endsWith("'")
+        ? text.slice(1, -1)
+        : text;
+    }
+    case "concatenation": {
+      let result = "";
+      for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        if (!child) continue;
+        const part = literalTextOf(child);
+        if (part === null) return null;
+        result += part;
+      }
+      return result;
+    }
+    case "string": {
+      let result = "";
+      for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        if (!child) continue;
+        if (child.type === '"') continue;
+        if (child.type !== "string_content") return null;
+        result += child.text;
+      }
+      return result;
+    }
+    default:
+      return null;
+  }
 }

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,