@gotgenes/pi-permission-system 9.0.0 → 9.1.0

package/src/handlers/gates/candidate-check.ts

@@ -0,0 +1,32 @@
+import type { PermissionCheckResult, PermissionState } from "#src/types";
+
+/** Restrictiveness ordering: deny is the most restrictive, allow the least. */
+const RESTRICTIVENESS: Record<PermissionState, number> = {
+  allow: 0,
+  ask: 1,
+  deny: 2,
+};
+
+/**
+ * Select the most restrictive permission result from a list (deny > ask > allow).
+ *
+ * The first occurrence wins on ties, so a caller passing results in candidate
+ * order receives the earliest worst case. Returns `undefined` for an empty list.
+ *
+ * Shared by the bash gates (path, external-directory) to combine the per-candidate
+ * `checkPermission` results their tree-sitter token extraction produces.
+ */
+export function pickMostRestrictive(
+  results: readonly PermissionCheckResult[],
+): PermissionCheckResult | undefined {
+  let worst: PermissionCheckResult | undefined;
+  for (const result of results) {
+    if (
+      worst === undefined ||
+      RESTRICTIVENESS[result.state] > RESTRICTIVENESS[worst.state]
+    ) {
+      worst = result;
+    }
+  }
+  return worst;
+}

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

@@ -3,7 +3,7 @@ import type {
   InputEventResult,
 } from "@earendil-works/pi-coding-agent";
 
-import { toRecord } from "#src/common";
+import { getNonEmptyString, toRecord } from "#src/common";
 import {
   emitDecisionEvent,
   type PermissionEventBus,
@@ -26,8 +26,10 @@ import {
   getToolNameFromValue,
   type ToolRegistry,
 } from "#src/tool-registry";
+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";
@@ -86,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) =>
@@ -165,17 +175,37 @@ export class PermissionGateHandler {
       () =>
         describeBashExternalDirectoryGate(
           tcc,
+          bashProgram,
+          checkPermission,
+          getSessionRuleset,
+        ),
+      () =>
+        describeBashPathGate(
+          tcc,
+          bashProgram,
           checkPermission,
           getSessionRuleset,
         ),
-      () => describeBashPathGate(tcc, checkPermission, getSessionRuleset),
       () => {
-        const toolCheck = checkPermission(
-          tcc.toolName,
-          tcc.input,
-          tcc.agentName ?? undefined,
-          getSessionRuleset(),
-        );
+        // Bash commands may chain several sub-commands (`a && b`, `a | b`, …);
+        // 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" && bashProgram
+            ? resolveBashCommandCheck(
+                command ?? "",
+                bashProgram.commands(),
+                tcc.agentName ?? undefined,
+                getSessionRuleset(),
+                checkPermission,
+              )
+            : checkPermission(
+                tcc.toolName,
+                tcc.input,
+                tcc.agentName ?? undefined,
+                getSessionRuleset(),
+              );
         const toolDescriptor = describeToolGate(tcc, toolCheck, formatter);
         toolDescriptor.preCheck = toolCheck;
         return toolDescriptor;

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;
 }

package/test/denial-messages.test.ts

@@ -98,6 +98,22 @@ describe("formatDenyReason", () => {
       );
     });
 
+    test("bash with nested execution context", () => {
+      expect(
+        formatDenyReason(
+          toolCtx(
+            toolCheck("bash", {
+              command: "rm -rf foo",
+              matchedPattern: "rm *",
+              commandContext: "command_substitution",
+            }),
+          ),
+        ),
+      ).toBe(
+        "[pi-permission-system] is not permitted to run 'bash' command 'rm -rf foo' (matched 'rm *', inside command substitution).",
+      );
+    });
+
     test("MCP source with target on non-mcp toolName", () => {
       expect(
         formatDenyReason(

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

@@ -0,0 +1,205 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { resolveBashCommandCheck } from "#src/handlers/gates/bash-command";
+import type { Rule } from "#src/rule";
+import type { PermissionCheckResult } from "#src/types";
+
+import { makeCheckResult } from "#test/helpers/handler-fixtures";
+
+type CheckPermissionFn = (
+  surface: string,
+  input: unknown,
+  agentName?: string,
+  sessionRules?: Rule[],
+) => PermissionCheckResult;
+
+/** Build a bash-surface check result for a single command unit. */
+function bashResult(
+  state: PermissionCheckResult["state"],
+  command: string,
+  matchedPattern?: string,
+): PermissionCheckResult {
+  return makeCheckResult({ state, source: "bash", command, matchedPattern });
+}
+
+describe("resolveBashCommandCheck", () => {
+  it("passes a single command straight through", () => {
+    const checkPermission = vi
+      .fn<CheckPermissionFn>()
+      .mockReturnValue(bashResult("allow", "npm install pkg", "npm *"));
+
+    const result = resolveBashCommandCheck(
+      "npm install pkg",
+      [{ text: "npm install pkg" }],
+      undefined,
+      [],
+      checkPermission,
+    );
+
+    expect(result.state).toBe("allow");
+    expect(checkPermission).toHaveBeenCalledTimes(1);
+    expect(checkPermission).toHaveBeenCalledWith(
+      "bash",
+      { command: "npm install pkg" },
+      undefined,
+      [],
+    );
+  });
+
+  it("denies the chain when any sub-command is denied, reporting that command's pattern", () => {
+    const checkPermission = vi
+      .fn<CheckPermissionFn>()
+      .mockImplementation((_surface, input) => {
+        const command = (input as { command: string }).command;
+        return command.startsWith("npm")
+          ? bashResult("deny", command, "npm *")
+          : bashResult("allow", command, "cd *");
+      });
+
+    const result = resolveBashCommandCheck(
+      "cd /p && npm install pkg",
+      [{ text: "cd /p" }, { text: "npm install pkg" }],
+      undefined,
+      [],
+      checkPermission,
+    );
+
+    expect(result.state).toBe("deny");
+    expect(result.matchedPattern).toBe("npm *");
+    expect(result.command).toBe("npm install pkg");
+  });
+
+  it("asks when a sub-command asks and none denies", () => {
+    const checkPermission = vi
+      .fn<CheckPermissionFn>()
+      .mockImplementation((_surface, input) => {
+        const command = (input as { command: string }).command;
+        return command.startsWith("git")
+          ? bashResult("ask", command, "git *")
+          : bashResult("allow", command, "cd *");
+      });
+
+    const result = resolveBashCommandCheck(
+      "cd /p && git push",
+      [{ text: "cd /p" }, { text: "git push" }],
+      undefined,
+      [],
+      checkPermission,
+    );
+
+    expect(result.state).toBe("ask");
+    expect(result.matchedPattern).toBe("git *");
+    expect(result.command).toBe("git push");
+  });
+
+  it("returns the first allow result when every sub-command is allowed", () => {
+    const checkPermission = vi
+      .fn<CheckPermissionFn>()
+      .mockImplementation((_surface, input) => {
+        const command = (input as { command: string }).command;
+        return bashResult("allow", command, `${command} *`);
+      });
+
+    const result = resolveBashCommandCheck(
+      "a && b",
+      [{ text: "a" }, { text: "b" }],
+      undefined,
+      [],
+      checkPermission,
+    );
+
+    expect(result.state).toBe("allow");
+    expect(result.matchedPattern).toBe("a *");
+  });
+
+  it("falls back to the whole command when no top-level commands are found", () => {
+    const checkPermission = vi
+      .fn<CheckPermissionFn>()
+      .mockReturnValue(bashResult("ask", "( rm x )", "*"));
+
+    const result = resolveBashCommandCheck(
+      "( rm x )",
+      [],
+      undefined,
+      [],
+      checkPermission,
+    );
+
+    expect(result.state).toBe("ask");
+    expect(result.commandContext).toBeUndefined();
+    expect(checkPermission).toHaveBeenCalledTimes(1);
+    expect(checkPermission).toHaveBeenCalledWith(
+      "bash",
+      { command: "( rm x )" },
+      undefined,
+      [],
+    );
+  });
+
+  it("forwards the agent name and session rules to each sub-command check", () => {
+    const sessionRules: Rule[] = [
+      { surface: "bash", pattern: "npm *", action: "allow", origin: "session" },
+    ];
+    const checkPermission = vi
+      .fn<CheckPermissionFn>()
+      .mockReturnValue(bashResult("allow", "npm i"));
+
+    resolveBashCommandCheck(
+      "npm i",
+      [{ text: "npm i" }],
+      "agent-x",
+      sessionRules,
+      checkPermission,
+    );
+
+    expect(checkPermission).toHaveBeenCalledWith(
+      "bash",
+      { command: "npm i" },
+      "agent-x",
+      sessionRules,
+    );
+  });
+
+  it("tags the winning result with the offending command's execution context", () => {
+    const checkPermission = vi
+      .fn<CheckPermissionFn>()
+      .mockImplementation((_surface, input) => {
+        const command = (input as { command: string }).command;
+        return command.startsWith("rm")
+          ? bashResult("deny", command, "rm *")
+          : bashResult("allow", command, "echo *");
+      });
+
+    const result = resolveBashCommandCheck(
+      "echo $(rm -rf foo)",
+      [
+        { text: "echo $(rm -rf foo)" },
+        { text: "rm -rf foo", context: "command_substitution" },
+      ],
+      undefined,
+      [],
+      checkPermission,
+    );
+
+    expect(result.state).toBe("deny");
+    expect(result.command).toBe("rm -rf foo");
+    expect(result.commandContext).toBe("command_substitution");
+  });
+
+  it("leaves commandContext unset when the winning command is top-level", () => {
+    const checkPermission = vi
+      .fn<CheckPermissionFn>()
+      .mockReturnValue(bashResult("deny", "rm -rf foo", "rm *"));
+
+    const result = resolveBashCommandCheck(
+      "rm -rf foo",
+      [{ text: "rm -rf foo" }],
+      undefined,
+      [],
+      checkPermission,
+    );
+
+    expect(result.state).toBe("deny");
+    expect(result.commandContext).toBeUndefined();
+  });
+});

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

@@ -1,8 +1,11 @@
 import { describe, expect, it, vi } from "vitest";
+import { getNonEmptyString, toRecord } from "#src/common";
 import { describeBashExternalDirectoryGate } from "#src/handlers/gates/bash-external-directory";
+import { BashProgram } from "#src/handlers/gates/bash-program";
 import type {
   GateBypass,
   GateDescriptor,
+  GateResult,
 } from "#src/handlers/gates/descriptor";
 import { isGateBypass, isGateDescriptor } from "#src/handlers/gates/descriptor";
 import type { ToolCallContext } from "#src/handlers/gates/types";
@@ -34,11 +37,34 @@ function makeCheckResult(
   };
 }
 
+/**
+ * Mirror the handler's parse-once derivation: parse the bash command into a
+ * shared `BashProgram` and inject it, exactly as `permission-gate-handler.ts`
+ * does, so the gate is exercised through the production wiring.
+ */
+async function describeGate(
+  tcc: ToolCallContext,
+  checkPermission: Parameters<typeof describeBashExternalDirectoryGate>[2],
+  getSessionRuleset: Parameters<typeof describeBashExternalDirectoryGate>[3],
+): Promise<GateResult> {
+  const command = getNonEmptyString(toRecord(tcc.input).command);
+  const bashProgram =
+    tcc.toolName === "bash" && command
+      ? await BashProgram.parse(command)
+      : null;
+  return describeBashExternalDirectoryGate(
+    tcc,
+    bashProgram,
+    checkPermission,
+    getSessionRuleset,
+  );
+}
+
 // ── tests ──────────────────────────────────────────────────────────────────
 
 describe("describeBashExternalDirectoryGate", () => {
   it("returns null when tool is not bash", async () => {
-    const result = await describeBashExternalDirectoryGate(
+    const result = await describeGate(
       makeTcc({ toolName: "read" }),
       vi.fn().mockReturnValue(makeCheckResult("ask")),
       vi.fn().mockReturnValue([]),
@@ -47,7 +73,7 @@ describe("describeBashExternalDirectoryGate", () => {
   });
 
   it("returns null when no CWD", async () => {
-    const result = await describeBashExternalDirectoryGate(
+    const result = await describeGate(
       makeTcc({ cwd: undefined }),
       vi.fn().mockReturnValue(makeCheckResult("ask")),
       vi.fn().mockReturnValue([]),
@@ -56,7 +82,7 @@ describe("describeBashExternalDirectoryGate", () => {
   });
 
   it("returns null when command has no external paths", async () => {
-    const result = await describeBashExternalDirectoryGate(
+    const result = await describeGate(
       makeTcc({ input: { command: "ls -la" } }),
       vi.fn().mockReturnValue(makeCheckResult("ask")),
       vi.fn().mockReturnValue([]),
@@ -68,7 +94,7 @@ describe("describeBashExternalDirectoryGate", () => {
     const checkPermission = vi
       .fn()
       .mockReturnValue(makeCheckResult("allow", { source: "session" }));
-    const result = await describeBashExternalDirectoryGate(
+    const result = await describeGate(
       makeTcc(),
       checkPermission,
       vi.fn().mockReturnValue([]),
@@ -85,7 +111,7 @@ describe("describeBashExternalDirectoryGate", () => {
 
   it("returns GateDescriptor with multi-pattern sessionApproval for uncovered paths", async () => {
     const checkPermission = vi.fn().mockReturnValue(makeCheckResult("ask"));
-    const result = await describeBashExternalDirectoryGate(
+    const result = await describeGate(
       makeTcc({ input: { command: "diff /outside/a.ts /outside/b.ts" } }),
       checkPermission,
       vi.fn().mockReturnValue([]),
@@ -110,7 +136,7 @@ describe("describeBashExternalDirectoryGate", () => {
           return makeCheckResult("ask");
         },
       );
-    const result = await describeBashExternalDirectoryGate(
+    const result = await describeGate(
       makeTcc(),
       checkPermission,
       vi.fn().mockReturnValue([]),
@@ -132,7 +158,7 @@ describe("describeBashExternalDirectoryGate", () => {
           return makeCheckResult("ask");
         },
       );
-    const result = await describeBashExternalDirectoryGate(
+    const result = await describeGate(
       makeTcc(),
       checkPermission,
       vi.fn().mockReturnValue([]),
@@ -143,7 +169,7 @@ describe("describeBashExternalDirectoryGate", () => {
   });
 
   it("descriptor surface is 'external_directory'", async () => {
-    const result = await describeBashExternalDirectoryGate(
+    const result = await describeGate(
       makeTcc(),
       vi.fn().mockReturnValue(makeCheckResult("ask")),
       vi.fn().mockReturnValue([]),
@@ -153,7 +179,7 @@ describe("describeBashExternalDirectoryGate", () => {
   });
 
   it("descriptor decision surface is 'external_directory'", async () => {
-    const result = await describeBashExternalDirectoryGate(
+    const result = await describeGate(
       makeTcc(),
       vi.fn().mockReturnValue(makeCheckResult("ask")),
       vi.fn().mockReturnValue([]),
@@ -163,7 +189,7 @@ describe("describeBashExternalDirectoryGate", () => {
   });
 
   it("denialContext contains the command and external paths", async () => {
-    const result = await describeBashExternalDirectoryGate(
+    const result = await describeGate(
       makeTcc({ input: { command: "cat /outside/file.ts" } }),
       vi.fn().mockReturnValue(makeCheckResult("ask")),
       vi.fn().mockReturnValue([]),
@@ -177,7 +203,7 @@ describe("describeBashExternalDirectoryGate", () => {
   });
 
   it("promptDetails includes command and tool_call source", async () => {
-    const result = await describeBashExternalDirectoryGate(
+    const result = await describeGate(
       makeTcc({ agentName: "agent-1", toolCallId: "tc-5" }),
       vi.fn().mockReturnValue(makeCheckResult("ask")),
       vi.fn().mockReturnValue([]),
@@ -203,7 +229,7 @@ describe("describeBashExternalDirectoryGate", () => {
           return makeCheckResult("ask");
         },
       );
-    const result = await describeBashExternalDirectoryGate(
+    const result = await describeGate(
       makeTcc({ input: { command: "diff /outside/a.ts /outside/b.ts" } }),
       checkPermission,
       vi.fn().mockReturnValue([]),
@@ -227,7 +253,7 @@ describe("describeBashExternalDirectoryGate", () => {
           return makeCheckResult("ask");
         },
       );
-    const result = await describeBashExternalDirectoryGate(
+    const result = await describeGate(
       makeTcc({ input: { command: "diff /outside/a.ts /outside/b.ts" } }),
       checkPermission,
       vi.fn().mockReturnValue([]),
@@ -252,7 +278,7 @@ describe("describeBashExternalDirectoryGate", () => {
           return makeCheckResult("ask");
         },
       );
-    const result = await describeBashExternalDirectoryGate(
+    const result = await describeGate(
       makeTcc({ input: { command: "diff /outside/a.ts /outside/b.ts" } }),
       checkPermission,
       vi.fn().mockReturnValue([]),