@gotgenes/pi-permission-system 10.1.0 → 10.3.0

package/test/handlers/gates/runner.test.ts

@@ -2,12 +2,13 @@ import { describe, expect, it, vi } from "vitest";
 
 import type { DenialContext } from "#src/denial-messages";
 import { EXTENSION_TAG } from "#src/denial-messages";
-import type {
-  GateBypass,
-  GateDescriptor,
-} from "#src/handlers/gates/descriptor";
+import type { GateBypass } from "#src/handlers/gates/descriptor";
 import { SessionApproval } from "#src/session-approval";
-import { makeDescriptor, makeGateRunner } from "#test/helpers/gate-fixtures";
+import {
+  makeDenialDescriptor,
+  makeDescriptor,
+  makeGateRunner,
+} from "#test/helpers/gate-fixtures";
 import { makeCheckResult } from "#test/helpers/handler-fixtures";
 
 // ── GateRunner — descriptor path ───────────────────────────────────────────
@@ -29,11 +30,7 @@ describe("GateRunner — descriptor path", () => {
 
   it("returns block and emits policy_deny when policy is deny", async () => {
     const { runner, deps } = makeGateRunner({
-      resolve: vi
-        .fn()
-        .mockReturnValue(
-          makeCheckResult({ state: "deny", matchedPattern: "*" }),
-        ),
+      resolveResult: makeCheckResult({ state: "deny", matchedPattern: "*" }),
     });
     const result = await runner.run(makeDescriptor(), null, "tc-1");
     expect(result).toMatchObject({ action: "block" });
@@ -51,11 +48,10 @@ describe("GateRunner — descriptor path", () => {
 
   it("returns allow and emits session_approved on session hit", async () => {
     const { runner, deps } = makeGateRunner({
-      resolve: vi
-        .fn()
-        .mockReturnValue(
-          makeCheckResult({ source: "session", matchedPattern: "git *" }),
-        ),
+      resolveResult: makeCheckResult({
+        source: "session",
+        matchedPattern: "git *",
+      }),
     });
     const result = await runner.run(
       makeDescriptor({
@@ -84,11 +80,7 @@ describe("GateRunner — descriptor path", () => {
 
   it("returns allow and emits user_approved when ask + user approves", async () => {
     const { runner, deps } = makeGateRunner({
-      resolve: vi
-        .fn()
-        .mockReturnValue(
-          makeCheckResult({ state: "ask", matchedPattern: "*" }),
-        ),
+      resolveResult: makeCheckResult({ state: "ask", matchedPattern: "*" }),
       promptPermission: vi
         .fn()
         .mockResolvedValue({ approved: true, state: "approved" }),
@@ -105,11 +97,7 @@ describe("GateRunner — descriptor path", () => {
 
   it("returns allow, emits user_approved_for_session, and records session rule on approved_for_session", async () => {
     const { runner, deps } = makeGateRunner({
-      resolve: vi
-        .fn()
-        .mockReturnValue(
-          makeCheckResult({ state: "ask", matchedPattern: "*" }),
-        ),
+      resolveResult: makeCheckResult({ state: "ask", matchedPattern: "*" }),
       promptPermission: vi
         .fn()
         .mockResolvedValue({ approved: true, state: "approved_for_session" }),
@@ -131,11 +119,7 @@ describe("GateRunner — descriptor path", () => {
 
   it("calls recordSessionApproval once with the full SessionApproval when sessionApproval has multiple patterns", async () => {
     const { runner, deps } = makeGateRunner({
-      resolve: vi
-        .fn()
-        .mockReturnValue(
-          makeCheckResult({ state: "ask", matchedPattern: "*" }),
-        ),
+      resolveResult: makeCheckResult({ state: "ask", matchedPattern: "*" }),
       promptPermission: vi
         .fn()
         .mockResolvedValue({ approved: true, state: "approved_for_session" }),
@@ -153,11 +137,7 @@ describe("GateRunner — descriptor path", () => {
 
   it("returns block and emits user_denied when ask + user denies", async () => {
     const { runner, deps } = makeGateRunner({
-      resolve: vi
-        .fn()
-        .mockReturnValue(
-          makeCheckResult({ state: "ask", matchedPattern: "*" }),
-        ),
+      resolveResult: makeCheckResult({ state: "ask", matchedPattern: "*" }),
       promptPermission: vi
         .fn()
         .mockResolvedValue({ approved: false, state: "denied" }),
@@ -174,11 +154,7 @@ describe("GateRunner — descriptor path", () => {
 
   it("returns block and emits confirmation_unavailable when ask + no UI", async () => {
     const { runner, deps } = makeGateRunner({
-      resolve: vi
-        .fn()
-        .mockReturnValue(
-          makeCheckResult({ state: "ask", matchedPattern: "*" }),
-        ),
+      resolveResult: makeCheckResult({ state: "ask", matchedPattern: "*" }),
       canConfirm: vi.fn().mockReturnValue(false),
     });
     const result = await runner.run(makeDescriptor(), null, "tc-1");
@@ -193,11 +169,7 @@ describe("GateRunner — descriptor path", () => {
 
   it("emits auto_approved resolution when decision has autoApproved flag", async () => {
     const { runner, deps } = makeGateRunner({
-      resolve: vi
-        .fn()
-        .mockReturnValue(
-          makeCheckResult({ state: "ask", matchedPattern: "*" }),
-        ),
+      resolveResult: makeCheckResult({ state: "ask", matchedPattern: "*" }),
       promptPermission: vi.fn().mockResolvedValue({
         approved: true,
         state: "approved",
@@ -257,11 +229,7 @@ describe("GateRunner — descriptor path", () => {
 
   it("passes requestId from toolCallId to promptPermission", async () => {
     const { runner, deps } = makeGateRunner({
-      resolve: vi
-        .fn()
-        .mockReturnValue(
-          makeCheckResult({ state: "ask", matchedPattern: "*" }),
-        ),
+      resolveResult: makeCheckResult({ state: "ask", matchedPattern: "*" }),
     });
     await runner.run(makeDescriptor(), null, "tc-42");
     expect(deps.promptPermission).toHaveBeenCalledWith(
@@ -271,11 +239,7 @@ describe("GateRunner — descriptor path", () => {
 
   it("does not call recordSessionApproval when user approves once (no sessionApproval)", async () => {
     const { runner, deps } = makeGateRunner({
-      resolve: vi
-        .fn()
-        .mockReturnValue(
-          makeCheckResult({ state: "ask", matchedPattern: "*" }),
-        ),
+      resolveResult: makeCheckResult({ state: "ask", matchedPattern: "*" }),
       promptPermission: vi
         .fn()
         .mockResolvedValue({ approved: true, state: "approved" }),
@@ -307,11 +271,7 @@ describe("GateRunner — descriptor path", () => {
 
   it("does not call recordSessionApproval when user approves for session but no sessionApproval on descriptor", async () => {
     const { runner, deps } = makeGateRunner({
-      resolve: vi
-        .fn()
-        .mockReturnValue(
-          makeCheckResult({ state: "ask", matchedPattern: "*" }),
-        ),
+      resolveResult: makeCheckResult({ state: "ask", matchedPattern: "*" }),
       promptPermission: vi
         .fn()
         .mockResolvedValue({ approved: true, state: "approved_for_session" }),
@@ -322,41 +282,9 @@ describe("GateRunner — descriptor path", () => {
   });
 
   describe("denialContext formatting", () => {
-    function makeDenialContextDescriptor(
-      denialContext: DenialContext,
-      overrides: Partial<GateDescriptor> = {},
-    ): GateDescriptor {
-      return {
-        surface: "write",
-        input: {},
-        denialContext,
-        promptDetails: {
-          source: "tool_call",
-          agentName: null,
-          message: "Allow tool 'write'?",
-          toolCallId: "tc-1",
-          toolName: "write",
-        },
-        logContext: {
-          source: "tool_call",
-          toolCallId: "tc-1",
-          toolName: "write",
-        },
-        decision: {
-          surface: "write",
-          value: "write",
-        },
-        ...overrides,
-      };
-    }
-
     it("uses denialContext to format denyReason with extension tag", async () => {
       const { runner } = makeGateRunner({
-        resolve: vi
-          .fn()
-          .mockReturnValue(
-            makeCheckResult({ state: "deny", matchedPattern: "*" }),
-          ),
+        resolveResult: makeCheckResult({ state: "deny", matchedPattern: "*" }),
       });
       const ctx: DenialContext = {
         kind: "tool",
@@ -364,7 +292,7 @@ describe("GateRunner — descriptor path", () => {
         agentName: "test-agent",
       };
       const result = await runner.run(
-        makeDenialContextDescriptor(ctx),
+        makeDenialDescriptor(ctx),
         "test-agent",
         "tc-1",
       );
@@ -377,22 +305,14 @@ describe("GateRunner — descriptor path", () => {
 
     it("uses denialContext to format unavailableReason with extension tag", async () => {
       const { runner } = makeGateRunner({
-        resolve: vi
-          .fn()
-          .mockReturnValue(
-            makeCheckResult({ state: "ask", matchedPattern: "*" }),
-          ),
+        resolveResult: makeCheckResult({ state: "ask", matchedPattern: "*" }),
         canConfirm: vi.fn().mockReturnValue(false),
       });
       const ctx: DenialContext = {
         kind: "tool",
         check: makeCheckResult({ state: "ask", matchedPattern: "*" }),
       };
-      const result = await runner.run(
-        makeDenialContextDescriptor(ctx),
-        null,
-        "tc-1",
-      );
+      const result = await runner.run(makeDenialDescriptor(ctx), null, "tc-1");
       expect(result.action).toBe("block");
       if (result.action === "block") {
         expect(result.reason).toContain(EXTENSION_TAG);
@@ -402,11 +322,7 @@ describe("GateRunner — descriptor path", () => {
 
     it("uses denialContext to format userDeniedReason with extension tag", async () => {
       const { runner } = makeGateRunner({
-        resolve: vi
-          .fn()
-          .mockReturnValue(
-            makeCheckResult({ state: "ask", matchedPattern: "*" }),
-          ),
+        resolveResult: makeCheckResult({ state: "ask", matchedPattern: "*" }),
         promptPermission: vi.fn().mockResolvedValue({
           approved: false,
           state: "denied",
@@ -417,11 +333,7 @@ describe("GateRunner — descriptor path", () => {
         kind: "tool",
         check: makeCheckResult({ state: "ask", matchedPattern: "*" }),
       };
-      const result = await runner.run(
-        makeDenialContextDescriptor(ctx),
-        null,
-        "tc-1",
-      );
+      const result = await runner.run(makeDenialDescriptor(ctx), null, "tc-1");
       expect(result.action).toBe("block");
       if (result.action === "block") {
         expect(result.reason).toContain(EXTENSION_TAG);
@@ -489,11 +401,7 @@ describe("GateRunner.run — null and bypass dispatch", () => {
 
   it("routes a descriptor to the gate check logic and returns block", async () => {
     const { runner } = makeGateRunner({
-      resolve: vi
-        .fn()
-        .mockReturnValue(
-          makeCheckResult({ state: "deny", matchedPattern: "*" }),
-        ),
+      resolveResult: makeCheckResult({ state: "deny", matchedPattern: "*" }),
     });
     const result = await runner.run(makeDescriptor(), null, "tc-1");
     expect(result).toMatchObject({ action: "block" });

package/test/handlers/tool-call.test.ts

@@ -3,9 +3,11 @@ import { describe, expect, it, vi } from "vitest";
 import { getEventInput } from "#src/handlers/permission-gate-handler";
 
 import {
+  makeBashCommandCheck,
   makeCheckResult,
   makeCtx,
   makeHandler,
+  makeSurfaceCheck,
   makeToolCallEvent,
 } from "#test/helpers/handler-fixtures";
 
@@ -65,11 +67,7 @@ describe("handleToolCall", () => {
   });
 
   it("blocks when tool is not registered", async () => {
-    const { handler } = makeHandler({
-      toolRegistry: {
-        getAll: vi.fn().mockReturnValue([{ name: "read" }]),
-      },
-    });
+    const { handler } = makeHandler({ tools: ["read"] });
     const result = await handler.handleToolCall(
       makeToolCallEvent("unknown-tool"),
       makeCtx(),
@@ -170,16 +168,11 @@ describe("handleToolCall — external-directory gate", () => {
           .fn()
           .mockReturnValue(makeCheckResult({ state: "deny" })),
       },
-      toolRegistry: {
-        getAll: vi.fn().mockReturnValue([{ name: "read" }]),
-      },
+      tools: ["read"],
     });
-    const event = {
-      type: "tool_call",
-      toolCallId: "tc-ext",
-      name: "read",
+    const event = makeToolCallEvent("read", {
       input: { path: "/outside/project/file.ts" },
-    };
+    });
     const result = await handler.handleToolCall(event, makeCtx());
     expect(result).toMatchObject({ block: true });
   });
@@ -195,16 +188,11 @@ describe("handleToolCall — bash external-directory gate", () => {
           .fn()
           .mockReturnValue(makeCheckResult({ state: "deny" })),
       },
-      toolRegistry: {
-        getAll: vi.fn().mockReturnValue([{ name: "bash" }]),
-      },
+      tools: ["bash"],
     });
-    const event = {
-      type: "tool_call",
-      toolCallId: "tc-bash-ext",
-      name: "bash",
+    const event = makeToolCallEvent("bash", {
       input: { command: "cat /outside/project/file.ts" },
-    };
+    });
     const result = await handler.handleToolCall(event, makeCtx());
     expect(result).toMatchObject({ block: true });
   });
@@ -214,44 +202,24 @@ describe("handleToolCall — bash external-directory gate", () => {
 
 describe("handleToolCall — path gate (tools)", () => {
   it("blocks a read of .env when path surface denies *.env", async () => {
-    const checkPermission = vi
-      .fn()
-      .mockImplementation(
-        (surface: string, _input: unknown, _agentName?: string) => {
-          if (surface === "path") {
-            return makeCheckResult({ state: "deny", matchedPattern: "*.env" });
-          }
-          return makeCheckResult();
-        },
-      );
     const { handler } = makeHandler({
-      session: { checkPermission },
-      toolRegistry: {
-        getAll: vi.fn().mockReturnValue([{ name: "read" }]),
+      session: {
+        checkPermission: makeSurfaceCheck({
+          path: { state: "deny", matchedPattern: "*.env" },
+        }),
       },
+      tools: ["read"],
     });
-    const event = {
-      type: "tool_call",
-      toolCallId: "tc-path",
-      name: "read",
-      input: { path: ".env" },
-    };
+    const event = makeToolCallEvent("read", { input: { path: ".env" } });
     const result = await handler.handleToolCall(event, makeCtx());
     expect(result).toMatchObject({ block: true });
   });
 
   it("allows a read when path surface allows", async () => {
-    const { handler } = makeHandler({
-      toolRegistry: {
-        getAll: vi.fn().mockReturnValue([{ name: "read" }]),
-      },
-    });
-    const event = {
-      type: "tool_call",
-      toolCallId: "tc-path-ok",
-      name: "read",
+    const { handler } = makeHandler({ tools: ["read"] });
+    const event = makeToolCallEvent("read", {
       input: { path: "src/index.ts" },
-    };
+    });
     const result = await handler.handleToolCall(event, makeCtx());
     expect(result).toEqual({});
   });
@@ -261,28 +229,15 @@ describe("handleToolCall — path gate (tools)", () => {
 
 describe("handleToolCall — bash path gate", () => {
   it("blocks a bash command accessing .env when path surface denies", async () => {
-    const checkPermission = vi
-      .fn()
-      .mockImplementation(
-        (surface: string, _input: unknown, _agentName?: string) => {
-          if (surface === "path") {
-            return makeCheckResult({ state: "deny", matchedPattern: "*.env" });
-          }
-          return makeCheckResult();
-        },
-      );
     const { handler } = makeHandler({
-      session: { checkPermission },
-      toolRegistry: {
-        getAll: vi.fn().mockReturnValue([{ name: "bash" }]),
+      session: {
+        checkPermission: makeSurfaceCheck({
+          path: { state: "deny", matchedPattern: "*.env" },
+        }),
       },
+      tools: ["bash"],
     });
-    const event = {
-      type: "tool_call",
-      toolCallId: "tc-bash-path",
-      name: "bash",
-      input: { command: "cat .env" },
-    };
+    const event = makeToolCallEvent("bash", { input: { command: "cat .env" } });
     const result = await handler.handleToolCall(event, makeCtx());
     expect(result).toMatchObject({ block: true });
   });
@@ -292,108 +247,44 @@ describe("handleToolCall — bash path gate", () => {
 
 describe("handleToolCall — bash command chain gate", () => {
   it("blocks a chain when a later sub-command is denied (#301)", async () => {
-    const checkPermission = vi
-      .fn()
-      .mockImplementation((surface: string, input: unknown) => {
-        if (surface === "bash") {
-          const command = (input as { command?: string }).command ?? "";
-          return /^npm\b/.test(command)
-            ? makeCheckResult({
-                state: "deny",
-                source: "bash",
-                command,
-                matchedPattern: "npm *",
-              })
-            : makeCheckResult({
-                state: "allow",
-                source: "bash",
-                command,
-                matchedPattern: "echo *",
-              });
-        }
-        return makeCheckResult({ state: "allow" });
-      });
     const { handler } = makeHandler({
-      session: { checkPermission },
-      toolRegistry: {
-        getAll: vi.fn().mockReturnValue([{ name: "bash" }]),
+      session: {
+        checkPermission: makeBashCommandCheck({
+          deny: /^npm\b/,
+          denyMatched: "npm *",
+          allowMatched: "echo *",
+        }),
       },
+      tools: ["bash"],
     });
-    const event = {
-      type: "tool_call",
-      toolCallId: "tc-bash-chain",
-      name: "bash",
+    const event = makeToolCallEvent("bash", {
       input: { command: "echo start && npm install compromised-package" },
-    };
+    });
     const result = await handler.handleToolCall(event, makeCtx());
     expect(result).toMatchObject({ block: true });
   });
 
   it("blocks a command nested inside command substitution (#306)", async () => {
-    const checkPermission = vi
-      .fn()
-      .mockImplementation((surface: string, input: unknown) => {
-        if (surface === "bash") {
-          const command = (input as { command?: string }).command ?? "";
-          return /^rm\b/.test(command)
-            ? makeCheckResult({
-                state: "deny",
-                source: "bash",
-                command,
-                matchedPattern: "rm *",
-              })
-            : makeCheckResult({
-                state: "allow",
-                source: "bash",
-                command,
-                matchedPattern: "echo *",
-              });
-        }
-        return makeCheckResult({ state: "allow" });
-      });
     const { handler } = makeHandler({
-      session: { checkPermission },
-      toolRegistry: {
-        getAll: vi.fn().mockReturnValue([{ name: "bash" }]),
+      session: {
+        checkPermission: makeBashCommandCheck({
+          deny: /^rm\b/,
+          denyMatched: "rm *",
+          allowMatched: "echo *",
+        }),
       },
+      tools: ["bash"],
     });
-    const event = {
-      type: "tool_call",
-      toolCallId: "tc-bash-substitution",
-      name: "bash",
+    const event = makeToolCallEvent("bash", {
       input: { command: "echo $(rm -rf foo)" },
-    };
+    });
     const result = await handler.handleToolCall(event, makeCtx());
     expect(result).toMatchObject({ block: true });
   });
 
   it("allows a single non-chained bash command", async () => {
-    const checkPermission = vi
-      .fn()
-      .mockImplementation((surface: string, input: unknown) => {
-        if (surface === "bash") {
-          const command = (input as { command?: string }).command ?? "";
-          return makeCheckResult({
-            state: "allow",
-            source: "bash",
-            command,
-            matchedPattern: "echo *",
-          });
-        }
-        return makeCheckResult({ state: "allow" });
-      });
-    const { handler } = makeHandler({
-      session: { checkPermission },
-      toolRegistry: {
-        getAll: vi.fn().mockReturnValue([{ name: "bash" }]),
-      },
-    });
-    const event = {
-      type: "tool_call",
-      toolCallId: "tc-bash-single",
-      name: "bash",
-      input: { command: "echo hi" },
-    };
+    const { handler } = makeHandler({ tools: ["bash"] });
+    const event = makeToolCallEvent("bash", { input: { command: "echo hi" } });
     const result = await handler.handleToolCall(event, makeCtx());
     expect(result).toEqual({});
   });

package/test/helpers/gate-fixtures.ts

@@ -2,8 +2,8 @@
  * Shared gate-level test fixtures for gate descriptor and runner tests.
  */
 import { vi } from "vitest";
-
 import type { DecisionReporter } from "#src/decision-reporter";
+import type { DenialContext } from "#src/denial-messages";
 import type { GatePrompter } from "#src/gate-prompter";
 import type { GateDescriptor } from "#src/handlers/gates/descriptor";
 import { GateRunner } from "#src/handlers/gates/runner";
@@ -90,6 +90,7 @@ export function makeReporter(
  */
 export function makeGateRunner(
   overrides: {
+    resolveResult?: PermissionCheckResult;
     resolve?: PermissionResolver["resolve"];
     recordSessionApproval?: SessionApprovalRecorder["recordSessionApproval"];
     canConfirm?: GatePrompter["canConfirm"];
@@ -102,7 +103,9 @@ export function makeGateRunner(
     overrides.resolve ??
     vi
       .fn<PermissionResolver["resolve"]>()
-      .mockReturnValue(makeCheckResult({ matchedPattern: "*" }));
+      .mockReturnValue(
+        overrides.resolveResult ?? makeCheckResult({ matchedPattern: "*" }),
+      );
   const recordSessionApproval =
     overrides.recordSessionApproval ??
     (vi.fn() as SessionApprovalRecorder["recordSessionApproval"]);
@@ -132,6 +135,42 @@ export function makeGateRunner(
   };
 }
 
+/**
+ * Gate descriptor variant with write-surface defaults and a caller-supplied
+ * denialContext.
+ *
+ * Use instead of `makeDescriptor` when the test exercises denial-message
+ * formatting — the write surface and its matching promptDetails/logContext
+ * keep the message helpers' field access consistent.
+ */
+export function makeDenialDescriptor(
+  denialContext: DenialContext,
+  overrides: Partial<GateDescriptor> = {},
+): GateDescriptor {
+  return {
+    surface: "write",
+    input: {},
+    denialContext,
+    promptDetails: {
+      source: "tool_call",
+      agentName: null,
+      message: "Allow tool 'write'?",
+      toolCallId: "tc-1",
+      toolName: "write",
+    },
+    logContext: {
+      source: "tool_call",
+      toolCallId: "tc-1",
+      toolName: "write",
+    },
+    decision: {
+      surface: "write",
+      value: "write",
+    },
+    ...overrides,
+  };
+}
+
 /**
  * Tool-call context factory with bash defaults.
  *
@@ -151,6 +190,31 @@ export function makeTcc(
   };
 }
 
+/**
+ * Resolver whose `resolve` dispatches on `input.path`, falling back to a
+ * default result for any path not in the map.
+ *
+ * Use when a test needs different results for different path tokens without
+ * writing a full `mockImplementation` block.
+ *
+ * Return type is intentionally unannotated so callers retain full `vi.fn()`
+ * mock access (`mock.calls`, `toHaveBeenCalledWith`, etc.).
+ */
+export function makePathDispatchResolver(
+  byPath: Record<string, PermissionCheckResult>,
+  defaultResult: PermissionCheckResult,
+) {
+  const resolve = vi.fn<PermissionResolver["resolve"]>();
+  resolve.mockImplementation((_surface, input) => {
+    const path = (input as Record<string, unknown>).path;
+    if (typeof path === "string" && path in byPath) {
+      return byPath[path];
+    }
+    return defaultResult;
+  });
+  return { resolve };
+}
+
 /**
  * Path-surface check result factory.
  *