@gotgenes/pi-permission-system 9.0.1 → 9.1.0

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

@@ -23,18 +23,17 @@ function bashResult(
 }
 
 describe("resolveBashCommandCheck", () => {
-  it("passes a single command straight through", async () => {
-    const decompose = vi.fn(async () => ["npm install pkg"]);
+  it("passes a single command straight through", () => {
     const checkPermission = vi
       .fn<CheckPermissionFn>()
       .mockReturnValue(bashResult("allow", "npm install pkg", "npm *"));
 
-    const result = await resolveBashCommandCheck(
+    const result = resolveBashCommandCheck(
       "npm install pkg",
+      [{ text: "npm install pkg" }],
       undefined,
       [],
       checkPermission,
-      decompose,
     );
 
     expect(result.state).toBe("allow");
@@ -47,8 +46,7 @@ describe("resolveBashCommandCheck", () => {
     );
   });
 
-  it("denies the chain when any sub-command is denied, reporting that command's pattern", async () => {
-    const decompose = vi.fn(async () => ["cd /p", "npm install pkg"]);
+  it("denies the chain when any sub-command is denied, reporting that command's pattern", () => {
     const checkPermission = vi
       .fn<CheckPermissionFn>()
       .mockImplementation((_surface, input) => {
@@ -58,12 +56,12 @@ describe("resolveBashCommandCheck", () => {
           : bashResult("allow", command, "cd *");
       });
 
-    const result = await resolveBashCommandCheck(
+    const result = resolveBashCommandCheck(
       "cd /p && npm install pkg",
+      [{ text: "cd /p" }, { text: "npm install pkg" }],
       undefined,
       [],
       checkPermission,
-      decompose,
     );
 
     expect(result.state).toBe("deny");
@@ -71,8 +69,7 @@ describe("resolveBashCommandCheck", () => {
     expect(result.command).toBe("npm install pkg");
   });
 
-  it("asks when a sub-command asks and none denies", async () => {
-    const decompose = vi.fn(async () => ["cd /p", "git push"]);
+  it("asks when a sub-command asks and none denies", () => {
     const checkPermission = vi
       .fn<CheckPermissionFn>()
       .mockImplementation((_surface, input) => {
@@ -82,12 +79,12 @@ describe("resolveBashCommandCheck", () => {
           : bashResult("allow", command, "cd *");
       });
 
-    const result = await resolveBashCommandCheck(
+    const result = resolveBashCommandCheck(
       "cd /p && git push",
+      [{ text: "cd /p" }, { text: "git push" }],
       undefined,
       [],
       checkPermission,
-      decompose,
     );
 
     expect(result.state).toBe("ask");
@@ -95,8 +92,7 @@ describe("resolveBashCommandCheck", () => {
     expect(result.command).toBe("git push");
   });
 
-  it("returns the first allow result when every sub-command is allowed", async () => {
-    const decompose = vi.fn(async () => ["a", "b"]);
+  it("returns the first allow result when every sub-command is allowed", () => {
     const checkPermission = vi
       .fn<CheckPermissionFn>()
       .mockImplementation((_surface, input) => {
@@ -104,33 +100,33 @@ describe("resolveBashCommandCheck", () => {
         return bashResult("allow", command, `${command} *`);
       });
 
-    const result = await resolveBashCommandCheck(
+    const result = resolveBashCommandCheck(
       "a && b",
+      [{ text: "a" }, { text: "b" }],
       undefined,
       [],
       checkPermission,
-      decompose,
     );
 
     expect(result.state).toBe("allow");
     expect(result.matchedPattern).toBe("a *");
   });
 
-  it("falls back to the whole command when no top-level commands are found", async () => {
-    const decompose = vi.fn(async () => []);
+  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 = await resolveBashCommandCheck(
+    const result = resolveBashCommandCheck(
       "( rm x )",
+      [],
       undefined,
       [],
       checkPermission,
-      decompose,
     );
 
     expect(result.state).toBe("ask");
+    expect(result.commandContext).toBeUndefined();
     expect(checkPermission).toHaveBeenCalledTimes(1);
     expect(checkPermission).toHaveBeenCalledWith(
       "bash",
@@ -140,21 +136,20 @@ describe("resolveBashCommandCheck", () => {
     );
   });
 
-  it("forwards the agent name and session rules to each sub-command check", async () => {
+  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 decompose = vi.fn(async () => ["npm i"]);
     const checkPermission = vi
       .fn<CheckPermissionFn>()
       .mockReturnValue(bashResult("allow", "npm i"));
 
-    await resolveBashCommandCheck(
+    resolveBashCommandCheck(
       "npm i",
+      [{ text: "npm i" }],
       "agent-x",
       sessionRules,
       checkPermission,
-      decompose,
     );
 
     expect(checkPermission).toHaveBeenCalledWith(
@@ -164,4 +159,47 @@ describe("resolveBashCommandCheck", () => {
       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([]),

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

@@ -9,12 +9,16 @@ vi.mock("node:os", () => {
   };
 });
 
+import { getNonEmptyString, toRecord } from "#src/common";
 import { describeBashPathGate } from "#src/handlers/gates/bash-path";
+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";
 import type { Rule } from "#src/rule";
 import type { PermissionCheckResult } from "#src/types";
 
@@ -34,13 +38,36 @@ type CheckPermissionFn = (
   sessionRules?: Rule[],
 ) => PermissionCheckResult;
 
+/**
+ * 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: CheckPermissionFn,
+  getSessionRuleset: () => Rule[],
+): Promise<GateResult> {
+  const command = getNonEmptyString(toRecord(tcc.input).command);
+  const bashProgram =
+    tcc.toolName === "bash" && command
+      ? await BashProgram.parse(command)
+      : null;
+  return describeBashPathGate(
+    tcc,
+    bashProgram,
+    checkPermission,
+    getSessionRuleset,
+  );
+}
+
 // ── tests ──────────────────────────────────────────────────────────────────
 
 describe("describeBashPathGate", () => {
   it("returns null for non-bash tools", async () => {
     const checkPermission = vi.fn<CheckPermissionFn>();
     const getSessionRuleset = vi.fn<() => Rule[]>().mockReturnValue([]);
-    const result = await describeBashPathGate(
+    const result = await describeGate(
       makeTcc({ toolName: "read", input: { path: ".env" } }),
       checkPermission,
       getSessionRuleset,
@@ -51,7 +78,7 @@ describe("describeBashPathGate", () => {
   it("returns null when no tokens are extracted", async () => {
     const checkPermission = vi.fn<CheckPermissionFn>();
     const getSessionRuleset = vi.fn<() => Rule[]>().mockReturnValue([]);
-    const result = await describeBashPathGate(
+    const result = await describeGate(
       makeTcc({ input: { command: "echo hello" } }),
       checkPermission,
       getSessionRuleset,
@@ -64,7 +91,7 @@ describe("describeBashPathGate", () => {
       .fn<CheckPermissionFn>()
       .mockReturnValue(makeCheckResult({ state: "allow" }));
     const getSessionRuleset = vi.fn<() => Rule[]>().mockReturnValue([]);
-    const result = await describeBashPathGate(
+    const result = await describeGate(
       makeTcc({ input: { command: "cat .env" } }),
       checkPermission,
       getSessionRuleset,
@@ -80,7 +107,7 @@ describe("describeBashPathGate", () => {
       }),
     );
     const getSessionRuleset = vi.fn<() => Rule[]>().mockReturnValue([]);
-    const result = await describeBashPathGate(
+    const result = await describeGate(
       makeTcc({ input: { command: "cat .env" } }),
       checkPermission,
       getSessionRuleset,
@@ -97,7 +124,7 @@ describe("describeBashPathGate", () => {
       .fn<CheckPermissionFn>()
       .mockReturnValue(makeCheckResult({ state: "ask", matchedPattern: "*" }));
     const getSessionRuleset = vi.fn<() => Rule[]>().mockReturnValue([]);
-    const result = await describeBashPathGate(
+    const result = await describeGate(
       makeTcc({ input: { command: "cat .env" } }),
       checkPermission,
       getSessionRuleset,
@@ -115,7 +142,7 @@ describe("describeBashPathGate", () => {
         makeCheckResult({ state: "deny", matchedPattern: "*.env" }),
       );
     const getSessionRuleset = vi.fn<() => Rule[]>().mockReturnValue([]);
-    const result = (await describeBashPathGate(
+    const result = (await describeGate(
       makeTcc({ input: { command: "cat .env" } }),
       checkPermission,
       getSessionRuleset,
@@ -135,7 +162,7 @@ describe("describeBashPathGate", () => {
         makeCheckResult({ state: "deny", matchedPattern: "*.env" }),
       );
     const getSessionRuleset = vi.fn<() => Rule[]>().mockReturnValue([]);
-    const result = (await describeBashPathGate(
+    const result = (await describeGate(
       makeTcc({ input: { command: "cat .env" } }),
       checkPermission,
       getSessionRuleset,
@@ -156,7 +183,7 @@ describe("describeBashPathGate", () => {
         origin: "session",
       },
     ]);
-    const result = await describeBashPathGate(
+    const result = await describeGate(
       makeTcc({ input: { command: "cat .env" } }),
       checkPermission,
       getSessionRuleset,
@@ -169,7 +196,7 @@ describe("describeBashPathGate", () => {
   it("returns null when command is missing", async () => {
     const checkPermission = vi.fn<CheckPermissionFn>();
     const getSessionRuleset = vi.fn<() => Rule[]>().mockReturnValue([]);
-    const result = await describeBashPathGate(
+    const result = await describeGate(
       makeTcc({ input: {} }),
       checkPermission,
       getSessionRuleset,
@@ -188,7 +215,7 @@ describe("describeBashPathGate", () => {
         return makeCheckResult({ state: "deny", matchedPattern: "*.env" });
       });
     const getSessionRuleset = vi.fn<() => Rule[]>().mockReturnValue([]);
-    const result = await describeBashPathGate(
+    const result = await describeGate(
       makeTcc({ input: { command: "cat src/foo.ts .env" } }),
       checkPermission,
       getSessionRuleset,
@@ -209,7 +236,7 @@ describe("describeBashPathGate", () => {
         return makeCheckResult({ state: "allow" });
       });
     const getSessionRuleset = vi.fn<() => Rule[]>().mockReturnValue([]);
-    const result = await describeBashPathGate(
+    const result = await describeGate(
       makeTcc({ input: { command: "cp .env README.md" } }),
       checkPermission,
       getSessionRuleset,
@@ -232,7 +259,7 @@ describe("describeBashPathGate", () => {
         return makeCheckResult({ state: "allow" });
       });
     const getSessionRuleset = vi.fn<() => Rule[]>().mockReturnValue([]);
-    const result = await describeBashPathGate(
+    const result = await describeGate(
       makeTcc({ input: { command: "echo test > .env" } }),
       checkPermission,
       getSessionRuleset,
@@ -252,7 +279,7 @@ describe("describeBashPathGate", () => {
       }),
     );
     const getSessionRuleset = vi.fn<() => Rule[]>().mockReturnValue([]);
-    const result = await describeBashPathGate(
+    const result = await describeGate(
       makeTcc({ input: { command: "cat .env" } }),
       checkPermission,
       getSessionRuleset,
@@ -280,7 +307,7 @@ describe("describeBashPathGate", () => {
         });
       });
     const getSessionRuleset = vi.fn<() => Rule[]>().mockReturnValue([]);
-    const result = await describeBashPathGate(
+    const result = await describeGate(
       makeTcc({ input: { command: "cat src/foo.ts .env" } }),
       checkPermission,
       getSessionRuleset,