@gotgenes/pi-permission-system 10.0.0 → 10.2.0

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

@@ -2,20 +2,23 @@ import { describe, expect, it, vi } from "vitest";
 
 import type { DenialContext } from "#src/denial-messages";
 import { EXTENSION_TAG } from "#src/denial-messages";
-import type { GateDescriptor } from "#src/handlers/gates/descriptor";
-import { runGateCheck } from "#src/handlers/gates/runner";
+import type { GateBypass } from "#src/handlers/gates/descriptor";
 import { SessionApproval } from "#src/session-approval";
-import { makeDescriptor, makeRunnerDeps } from "#test/helpers/gate-fixtures";
+import {
+  makeDenialDescriptor,
+  makeDescriptor,
+  makeGateRunner,
+} from "#test/helpers/gate-fixtures";
 import { makeCheckResult } from "#test/helpers/handler-fixtures";
 
-// ── tests ──────────────────────────────────────────────────────────────────
+// ── GateRunner — descriptor path ───────────────────────────────────────────
 
-describe("runGateCheck", () => {
+describe("GateRunner — descriptor path", () => {
   it("returns allow and emits policy_allow when policy is allow", async () => {
-    const deps = makeRunnerDeps();
-    const result = await runGateCheck(makeDescriptor(), null, "tc-1", deps);
+    const { runner, deps } = makeGateRunner();
+    const result = await runner.run(makeDescriptor(), null, "tc-1");
     expect(result).toEqual({ action: "allow" });
-    expect(deps.emitDecision).toHaveBeenCalledWith(
+    expect(deps.reporter.emitDecision).toHaveBeenCalledWith(
       expect.objectContaining({
         surface: "read",
         value: "read",
@@ -26,36 +29,31 @@ describe("runGateCheck", () => {
   });
 
   it("returns block and emits policy_deny when policy is deny", async () => {
-    const deps = makeRunnerDeps({
-      checkPermission: vi
-        .fn()
-        .mockReturnValue(
-          makeCheckResult({ state: "deny", matchedPattern: "*" }),
-        ),
+    const { runner, deps } = makeGateRunner({
+      resolveResult: makeCheckResult({ state: "deny", matchedPattern: "*" }),
     });
-    const result = await runGateCheck(makeDescriptor(), null, "tc-1", deps);
+    const result = await runner.run(makeDescriptor(), null, "tc-1");
     expect(result).toMatchObject({ action: "block" });
-    expect(deps.emitDecision).toHaveBeenCalledWith(
+    expect(deps.reporter.emitDecision).toHaveBeenCalledWith(
       expect.objectContaining({
         result: "deny",
         resolution: "policy_deny",
       }),
     );
-    expect(deps.writeReviewLog).toHaveBeenCalledWith(
+    expect(deps.reporter.writeReviewLog).toHaveBeenCalledWith(
       "permission_request.blocked",
       expect.objectContaining({ resolution: "policy_denied" }),
     );
   });
 
   it("returns allow and emits session_approved on session hit", async () => {
-    const deps = makeRunnerDeps({
-      checkPermission: vi
-        .fn()
-        .mockReturnValue(
-          makeCheckResult({ source: "session", matchedPattern: "git *" }),
-        ),
+    const { runner, deps } = makeGateRunner({
+      resolveResult: makeCheckResult({
+        source: "session",
+        matchedPattern: "git *",
+      }),
     });
-    const result = await runGateCheck(
+    const result = await runner.run(
       makeDescriptor({
         surface: "bash",
         input: { command: "git status" },
@@ -63,17 +61,16 @@ describe("runGateCheck", () => {
       }),
       null,
       "tc-1",
-      deps,
     );
     expect(result).toEqual({ action: "allow" });
-    expect(deps.writeReviewLog).toHaveBeenCalledWith(
+    expect(deps.reporter.writeReviewLog).toHaveBeenCalledWith(
       "permission_request.session_approved",
       expect.objectContaining({
         resolution: "session_approved",
         sessionApprovalPattern: "git *",
       }),
     );
-    expect(deps.emitDecision).toHaveBeenCalledWith(
+    expect(deps.reporter.emitDecision).toHaveBeenCalledWith(
       expect.objectContaining({
         resolution: "session_approved",
         matchedPattern: "git *",
@@ -82,19 +79,15 @@ describe("runGateCheck", () => {
   });
 
   it("returns allow and emits user_approved when ask + user approves", async () => {
-    const deps = makeRunnerDeps({
-      checkPermission: vi
-        .fn()
-        .mockReturnValue(
-          makeCheckResult({ state: "ask", matchedPattern: "*" }),
-        ),
+    const { runner, deps } = makeGateRunner({
+      resolveResult: makeCheckResult({ state: "ask", matchedPattern: "*" }),
       promptPermission: vi
         .fn()
         .mockResolvedValue({ approved: true, state: "approved" }),
     });
-    const result = await runGateCheck(makeDescriptor(), null, "tc-1", deps);
+    const result = await runner.run(makeDescriptor(), null, "tc-1");
     expect(result).toEqual({ action: "allow" });
-    expect(deps.emitDecision).toHaveBeenCalledWith(
+    expect(deps.reporter.emitDecision).toHaveBeenCalledWith(
       expect.objectContaining({
         result: "allow",
         resolution: "user_approved",
@@ -103,12 +96,8 @@ describe("runGateCheck", () => {
   });
 
   it("returns allow, emits user_approved_for_session, and records session rule on approved_for_session", async () => {
-    const deps = makeRunnerDeps({
-      checkPermission: vi
-        .fn()
-        .mockReturnValue(
-          makeCheckResult({ state: "ask", matchedPattern: "*" }),
-        ),
+    const { runner, deps } = makeGateRunner({
+      resolveResult: makeCheckResult({ state: "ask", matchedPattern: "*" }),
       promptPermission: vi
         .fn()
         .mockResolvedValue({ approved: true, state: "approved_for_session" }),
@@ -116,9 +105,9 @@ describe("runGateCheck", () => {
     const descriptor = makeDescriptor({
       sessionApproval: SessionApproval.single("read", "*"),
     });
-    const result = await runGateCheck(descriptor, null, "tc-1", deps);
+    const result = await runner.run(descriptor, null, "tc-1");
     expect(result).toEqual({ action: "allow" });
-    expect(deps.emitDecision).toHaveBeenCalledWith(
+    expect(deps.reporter.emitDecision).toHaveBeenCalledWith(
       expect.objectContaining({
         resolution: "user_approved_for_session",
       }),
@@ -129,12 +118,8 @@ describe("runGateCheck", () => {
   });
 
   it("calls recordSessionApproval once with the full SessionApproval when sessionApproval has multiple patterns", async () => {
-    const deps = makeRunnerDeps({
-      checkPermission: vi
-        .fn()
-        .mockReturnValue(
-          makeCheckResult({ state: "ask", matchedPattern: "*" }),
-        ),
+    const { runner, deps } = makeGateRunner({
+      resolveResult: makeCheckResult({ state: "ask", matchedPattern: "*" }),
       promptPermission: vi
         .fn()
         .mockResolvedValue({ approved: true, state: "approved_for_session" }),
@@ -144,26 +129,22 @@ describe("runGateCheck", () => {
       "/outside/b/*",
     ]);
     const descriptor = makeDescriptor({ sessionApproval: approval });
-    const result = await runGateCheck(descriptor, null, "tc-1", deps);
+    const result = await runner.run(descriptor, null, "tc-1");
     expect(result).toEqual({ action: "allow" });
     expect(deps.recordSessionApproval).toHaveBeenCalledTimes(1);
     expect(deps.recordSessionApproval).toHaveBeenCalledWith(approval);
   });
 
   it("returns block and emits user_denied when ask + user denies", async () => {
-    const deps = makeRunnerDeps({
-      checkPermission: vi
-        .fn()
-        .mockReturnValue(
-          makeCheckResult({ state: "ask", matchedPattern: "*" }),
-        ),
+    const { runner, deps } = makeGateRunner({
+      resolveResult: makeCheckResult({ state: "ask", matchedPattern: "*" }),
       promptPermission: vi
         .fn()
         .mockResolvedValue({ approved: false, state: "denied" }),
     });
-    const result = await runGateCheck(makeDescriptor(), null, "tc-1", deps);
+    const result = await runner.run(makeDescriptor(), null, "tc-1");
     expect(result).toMatchObject({ action: "block" });
-    expect(deps.emitDecision).toHaveBeenCalledWith(
+    expect(deps.reporter.emitDecision).toHaveBeenCalledWith(
       expect.objectContaining({
         result: "deny",
         resolution: "user_denied",
@@ -172,17 +153,13 @@ describe("runGateCheck", () => {
   });
 
   it("returns block and emits confirmation_unavailable when ask + no UI", async () => {
-    const deps = makeRunnerDeps({
-      checkPermission: vi
-        .fn()
-        .mockReturnValue(
-          makeCheckResult({ state: "ask", matchedPattern: "*" }),
-        ),
+    const { runner, deps } = makeGateRunner({
+      resolveResult: makeCheckResult({ state: "ask", matchedPattern: "*" }),
       canConfirm: vi.fn().mockReturnValue(false),
     });
-    const result = await runGateCheck(makeDescriptor(), null, "tc-1", deps);
+    const result = await runner.run(makeDescriptor(), null, "tc-1");
     expect(result).toMatchObject({ action: "block" });
-    expect(deps.emitDecision).toHaveBeenCalledWith(
+    expect(deps.reporter.emitDecision).toHaveBeenCalledWith(
       expect.objectContaining({
         result: "deny",
         resolution: "confirmation_unavailable",
@@ -191,73 +168,59 @@ describe("runGateCheck", () => {
   });
 
   it("emits auto_approved resolution when decision has autoApproved flag", async () => {
-    const deps = makeRunnerDeps({
-      checkPermission: vi
-        .fn()
-        .mockReturnValue(
-          makeCheckResult({ state: "ask", matchedPattern: "*" }),
-        ),
+    const { runner, deps } = makeGateRunner({
+      resolveResult: makeCheckResult({ state: "ask", matchedPattern: "*" }),
       promptPermission: vi.fn().mockResolvedValue({
         approved: true,
         state: "approved",
         autoApproved: true,
       }),
     });
-    const result = await runGateCheck(makeDescriptor(), null, "tc-1", deps);
+    const result = await runner.run(makeDescriptor(), null, "tc-1");
     expect(result).toEqual({ action: "allow" });
-    expect(deps.emitDecision).toHaveBeenCalledWith(
+    expect(deps.reporter.emitDecision).toHaveBeenCalledWith(
       expect.objectContaining({
         resolution: "auto_approved",
       }),
     );
   });
 
-  it("uses preResolved.state instead of calling checkPermission", async () => {
-    const deps = makeRunnerDeps();
+  it("uses preResolved.state instead of calling resolve", async () => {
+    const { runner, deps } = makeGateRunner();
     const descriptor = makeDescriptor({
       preResolved: { state: "deny" },
     });
-    const result = await runGateCheck(descriptor, null, "tc-1", deps);
+    const result = await runner.run(descriptor, null, "tc-1");
     expect(result).toMatchObject({ action: "block" });
-    expect(deps.checkPermission).not.toHaveBeenCalled();
-    expect(deps.emitDecision).toHaveBeenCalledWith(
+    expect(deps.resolve).not.toHaveBeenCalled();
+    expect(deps.reporter.emitDecision).toHaveBeenCalledWith(
       expect.objectContaining({
         resolution: "policy_deny",
       }),
     );
   });
 
-  it("uses preResolved.state allow without calling checkPermission", async () => {
-    const deps = makeRunnerDeps();
+  it("uses preResolved.state allow without calling resolve", async () => {
+    const { runner, deps } = makeGateRunner();
     const descriptor = makeDescriptor({
       preResolved: { state: "allow" },
     });
-    const result = await runGateCheck(descriptor, null, "tc-1", deps);
+    const result = await runner.run(descriptor, null, "tc-1");
     expect(result).toEqual({ action: "allow" });
-    expect(deps.checkPermission).not.toHaveBeenCalled();
-    expect(deps.emitDecision).toHaveBeenCalledWith(
+    expect(deps.resolve).not.toHaveBeenCalled();
+    expect(deps.reporter.emitDecision).toHaveBeenCalledWith(
       expect.objectContaining({
         resolution: "policy_allow",
       }),
     );
   });
 
-  it("passes agentName to checkPermission and decision event", async () => {
-    const deps = makeRunnerDeps();
-    const result = await runGateCheck(
-      makeDescriptor(),
-      "test-agent",
-      "tc-1",
-      deps,
-    );
+  it("passes agentName to resolve and decision event", async () => {
+    const { runner, deps } = makeGateRunner();
+    const result = await runner.run(makeDescriptor(), "test-agent", "tc-1");
     expect(result).toEqual({ action: "allow" });
-    expect(deps.checkPermission).toHaveBeenCalledWith(
-      "read",
-      {},
-      "test-agent",
-      [],
-    );
-    expect(deps.emitDecision).toHaveBeenCalledWith(
+    expect(deps.resolve).toHaveBeenCalledWith("read", {}, "test-agent");
+    expect(deps.reporter.emitDecision).toHaveBeenCalledWith(
       expect.objectContaining({
         agentName: "test-agent",
       }),
@@ -265,36 +228,28 @@ describe("runGateCheck", () => {
   });
 
   it("passes requestId from toolCallId to promptPermission", async () => {
-    const deps = makeRunnerDeps({
-      checkPermission: vi
-        .fn()
-        .mockReturnValue(
-          makeCheckResult({ state: "ask", matchedPattern: "*" }),
-        ),
+    const { runner, deps } = makeGateRunner({
+      resolveResult: makeCheckResult({ state: "ask", matchedPattern: "*" }),
     });
-    await runGateCheck(makeDescriptor(), null, "tc-42", deps);
+    await runner.run(makeDescriptor(), null, "tc-42");
     expect(deps.promptPermission).toHaveBeenCalledWith(
       expect.objectContaining({ requestId: "tc-42" }),
     );
   });
 
   it("does not call recordSessionApproval when user approves once (no sessionApproval)", async () => {
-    const deps = makeRunnerDeps({
-      checkPermission: vi
-        .fn()
-        .mockReturnValue(
-          makeCheckResult({ state: "ask", matchedPattern: "*" }),
-        ),
+    const { runner, deps } = makeGateRunner({
+      resolveResult: makeCheckResult({ state: "ask", matchedPattern: "*" }),
       promptPermission: vi
         .fn()
         .mockResolvedValue({ approved: true, state: "approved" }),
     });
-    await runGateCheck(makeDescriptor(), null, "tc-1", deps);
+    await runner.run(makeDescriptor(), null, "tc-1");
     expect(deps.recordSessionApproval).not.toHaveBeenCalled();
   });
 
-  it("uses preCheck result directly instead of calling checkPermission", async () => {
-    const deps = makeRunnerDeps();
+  it("uses preCheck result directly instead of calling resolve", async () => {
+    const { runner, deps } = makeGateRunner();
     const descriptor = makeDescriptor({
       preCheck: makeCheckResult({
         state: "deny",
@@ -302,10 +257,10 @@ describe("runGateCheck", () => {
         matchedPattern: "rm *",
       }),
     });
-    const result = await runGateCheck(descriptor, null, "tc-1", deps);
+    const result = await runner.run(descriptor, null, "tc-1");
     expect(result).toMatchObject({ action: "block" });
-    expect(deps.checkPermission).not.toHaveBeenCalled();
-    expect(deps.emitDecision).toHaveBeenCalledWith(
+    expect(deps.resolve).not.toHaveBeenCalled();
+    expect(deps.reporter.emitDecision).toHaveBeenCalledWith(
       expect.objectContaining({
         resolution: "policy_deny",
         origin: "global",
@@ -315,68 +270,31 @@ describe("runGateCheck", () => {
   });
 
   it("does not call recordSessionApproval when user approves for session but no sessionApproval on descriptor", async () => {
-    const deps = makeRunnerDeps({
-      checkPermission: vi
-        .fn()
-        .mockReturnValue(
-          makeCheckResult({ state: "ask", matchedPattern: "*" }),
-        ),
+    const { runner, deps } = makeGateRunner({
+      resolveResult: makeCheckResult({ state: "ask", matchedPattern: "*" }),
       promptPermission: vi
         .fn()
         .mockResolvedValue({ approved: true, state: "approved_for_session" }),
     });
     // No sessionApproval on descriptor
-    await runGateCheck(makeDescriptor(), null, "tc-1", deps);
+    await runner.run(makeDescriptor(), null, "tc-1");
     expect(deps.recordSessionApproval).not.toHaveBeenCalled();
   });
 
   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 deps = makeRunnerDeps({
-        checkPermission: vi
-          .fn()
-          .mockReturnValue(
-            makeCheckResult({ state: "deny", matchedPattern: "*" }),
-          ),
+      const { runner } = makeGateRunner({
+        resolveResult: makeCheckResult({ state: "deny", matchedPattern: "*" }),
       });
       const ctx: DenialContext = {
         kind: "tool",
         check: makeCheckResult({ state: "deny", matchedPattern: "*" }),
         agentName: "test-agent",
       };
-      const result = await runGateCheck(
-        makeDenialContextDescriptor(ctx),
+      const result = await runner.run(
+        makeDenialDescriptor(ctx),
         "test-agent",
         "tc-1",
-        deps,
       );
       expect(result.action).toBe("block");
       if (result.action === "block") {
@@ -386,24 +304,15 @@ describe("runGateCheck", () => {
     });
 
     it("uses denialContext to format unavailableReason with extension tag", async () => {
-      const deps = makeRunnerDeps({
-        checkPermission: vi
-          .fn()
-          .mockReturnValue(
-            makeCheckResult({ state: "ask", matchedPattern: "*" }),
-          ),
+      const { runner } = makeGateRunner({
+        resolveResult: makeCheckResult({ state: "ask", matchedPattern: "*" }),
         canConfirm: vi.fn().mockReturnValue(false),
       });
       const ctx: DenialContext = {
         kind: "tool",
         check: makeCheckResult({ state: "ask", matchedPattern: "*" }),
       };
-      const result = await runGateCheck(
-        makeDenialContextDescriptor(ctx),
-        null,
-        "tc-1",
-        deps,
-      );
+      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);
@@ -412,12 +321,8 @@ describe("runGateCheck", () => {
     });
 
     it("uses denialContext to format userDeniedReason with extension tag", async () => {
-      const deps = makeRunnerDeps({
-        checkPermission: vi
-          .fn()
-          .mockReturnValue(
-            makeCheckResult({ state: "ask", matchedPattern: "*" }),
-          ),
+      const { runner } = makeGateRunner({
+        resolveResult: makeCheckResult({ state: "ask", matchedPattern: "*" }),
         promptPermission: vi.fn().mockResolvedValue({
           approved: false,
           state: "denied",
@@ -428,12 +333,7 @@ describe("runGateCheck", () => {
         kind: "tool",
         check: makeCheckResult({ state: "ask", matchedPattern: "*" }),
       };
-      const result = await runGateCheck(
-        makeDenialContextDescriptor(ctx),
-        null,
-        "tc-1",
-        deps,
-      );
+      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);
@@ -442,3 +342,68 @@ describe("runGateCheck", () => {
     });
   });
 });
+
+// ── GateRunner.run — null and bypass dispatch ──────────────────────────────
+
+describe("GateRunner.run — null and bypass dispatch", () => {
+  it("returns allow for a null gate", async () => {
+    const { runner, deps } = makeGateRunner();
+    const result = await runner.run(null, null, "tc-1");
+    expect(result).toEqual({ action: "allow" });
+    expect(deps.reporter.writeReviewLog).not.toHaveBeenCalled();
+    expect(deps.reporter.emitDecision).not.toHaveBeenCalled();
+  });
+
+  it("returns allow for a bypass with no log or decision", async () => {
+    const { runner, deps } = makeGateRunner();
+    const bypass: GateBypass = { action: "allow" };
+    const result = await runner.run(bypass, null, "tc-1");
+    expect(result).toEqual({ action: "allow" });
+    expect(deps.reporter.writeReviewLog).not.toHaveBeenCalled();
+    expect(deps.reporter.emitDecision).not.toHaveBeenCalled();
+  });
+
+  it("fires writeReviewLog for a bypass with a log entry", async () => {
+    const { runner, deps } = makeGateRunner();
+    const bypass: GateBypass = {
+      action: "allow",
+      log: { event: "infra.bypass", details: { path: "/x" } },
+    };
+    await runner.run(bypass, null, "tc-1");
+    expect(deps.reporter.writeReviewLog).toHaveBeenCalledWith("infra.bypass", {
+      path: "/x",
+    });
+    expect(deps.reporter.emitDecision).not.toHaveBeenCalled();
+  });
+
+  it("fires emitDecision for a bypass with a decision", async () => {
+    const { runner, deps } = makeGateRunner();
+    const decision = {
+      surface: "path",
+      value: "/x",
+      result: "allow" as const,
+      resolution: "policy_allow" as const,
+      origin: null,
+      agentName: null,
+      matchedPattern: null,
+    };
+    const bypass: GateBypass = { action: "allow", decision };
+    await runner.run(bypass, null, "tc-1");
+    expect(deps.reporter.emitDecision).toHaveBeenCalledWith(decision);
+    expect(deps.reporter.writeReviewLog).not.toHaveBeenCalled();
+  });
+
+  it("routes a descriptor to the gate check logic and returns allow", async () => {
+    const { runner } = makeGateRunner();
+    const result = await runner.run(makeDescriptor(), null, "tc-1");
+    expect(result).toEqual({ action: "allow" });
+  });
+
+  it("routes a descriptor to the gate check logic and returns block", async () => {
+    const { runner } = makeGateRunner({
+      resolveResult: makeCheckResult({ state: "deny", matchedPattern: "*" }),
+    });
+    const result = await runner.run(makeDescriptor(), null, "tc-1");
+    expect(result).toMatchObject({ action: "block" });
+  });
+});