@gotgenes/pi-permission-system 5.5.0 → 5.6.0

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

@@ -0,0 +1,361 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type {
+  GateDescriptor,
+  GateRunnerDeps,
+} from "../../../src/handlers/gates/descriptor";
+import { runGateCheck } from "../../../src/handlers/gates/runner";
+import type { PermissionCheckResult } from "../../../src/types";
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+function makeDescriptor(
+  overrides: Partial<GateDescriptor> = {},
+): GateDescriptor {
+  return {
+    surface: "read",
+    input: {},
+    messages: {
+      denyReason: "Tool 'read' is denied.",
+      unavailableReason: "No UI available.",
+      userDeniedReason: (d) => `User denied. ${d.denialReason ?? ""}`,
+    },
+    promptDetails: {
+      source: "tool_call",
+      agentName: null,
+      message: "Allow tool 'read'?",
+      toolCallId: "tc-1",
+      toolName: "read",
+    },
+    logContext: {
+      source: "tool_call",
+      toolCallId: "tc-1",
+      toolName: "read",
+    },
+    decision: {
+      surface: "read",
+      value: "read",
+    },
+    ...overrides,
+  };
+}
+
+function makeCheckResult(
+  state: "allow" | "deny" | "ask",
+  overrides: Partial<PermissionCheckResult> = {},
+): PermissionCheckResult {
+  return {
+    state,
+    toolName: "read",
+    source: "tool",
+    origin: "builtin",
+    matchedPattern: "*",
+    ...overrides,
+  };
+}
+
+function makeRunnerDeps(
+  overrides: Partial<GateRunnerDeps> = {},
+): GateRunnerDeps {
+  return {
+    checkPermission: vi.fn().mockReturnValue(makeCheckResult("allow")),
+    getSessionRuleset: vi.fn().mockReturnValue([]),
+    approveSessionRule: vi.fn(),
+    writeReviewLog: vi.fn(),
+    emitDecision: vi.fn(),
+    canConfirm: vi.fn().mockReturnValue(true),
+    promptPermission: vi
+      .fn()
+      .mockResolvedValue({ approved: true, state: "approved" }),
+    ...overrides,
+  };
+}
+
+// ── tests ──────────────────────────────────────────────────────────────────
+
+describe("runGateCheck", () => {
+  it("returns allow and emits policy_allow when policy is allow", async () => {
+    const deps = makeRunnerDeps();
+    const result = await runGateCheck(makeDescriptor(), null, "tc-1", deps);
+    expect(result).toEqual({ action: "allow" });
+    expect(deps.emitDecision).toHaveBeenCalledWith(
+      expect.objectContaining({
+        surface: "read",
+        value: "read",
+        result: "allow",
+        resolution: "policy_allow",
+      }),
+    );
+  });
+
+  it("returns block and emits policy_deny when policy is deny", async () => {
+    const deps = makeRunnerDeps({
+      checkPermission: vi.fn().mockReturnValue(makeCheckResult("deny")),
+    });
+    const result = await runGateCheck(makeDescriptor(), null, "tc-1", deps);
+    expect(result).toMatchObject({ action: "block" });
+    expect(deps.emitDecision).toHaveBeenCalledWith(
+      expect.objectContaining({
+        result: "deny",
+        resolution: "policy_deny",
+      }),
+    );
+    expect(deps.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("allow", {
+          source: "session",
+          matchedPattern: "git *",
+        }),
+      ),
+    });
+    const result = await runGateCheck(
+      makeDescriptor({
+        surface: "bash",
+        input: { command: "git status" },
+        decision: { surface: "bash", value: "git status" },
+      }),
+      null,
+      "tc-1",
+      deps,
+    );
+    expect(result).toEqual({ action: "allow" });
+    expect(deps.writeReviewLog).toHaveBeenCalledWith(
+      "permission_request.session_approved",
+      expect.objectContaining({
+        resolution: "session_approved",
+        sessionApprovalPattern: "git *",
+      }),
+    );
+    expect(deps.emitDecision).toHaveBeenCalledWith(
+      expect.objectContaining({
+        resolution: "session_approved",
+        matchedPattern: "git *",
+      }),
+    );
+  });
+
+  it("returns allow and emits user_approved when ask + user approves", async () => {
+    const deps = makeRunnerDeps({
+      checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
+      promptPermission: vi
+        .fn()
+        .mockResolvedValue({ approved: true, state: "approved" }),
+    });
+    const result = await runGateCheck(makeDescriptor(), null, "tc-1", deps);
+    expect(result).toEqual({ action: "allow" });
+    expect(deps.emitDecision).toHaveBeenCalledWith(
+      expect.objectContaining({
+        result: "allow",
+        resolution: "user_approved",
+      }),
+    );
+  });
+
+  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("ask")),
+      promptPermission: vi
+        .fn()
+        .mockResolvedValue({ approved: true, state: "approved_for_session" }),
+    });
+    const descriptor = makeDescriptor({
+      sessionApproval: { surface: "read", pattern: "*" },
+    });
+    const result = await runGateCheck(descriptor, null, "tc-1", deps);
+    expect(result).toEqual({ action: "allow" });
+    expect(deps.emitDecision).toHaveBeenCalledWith(
+      expect.objectContaining({
+        resolution: "user_approved_for_session",
+      }),
+    );
+    expect(deps.approveSessionRule).toHaveBeenCalledWith("read", "*");
+  });
+
+  it("calls approveSessionRule once per pattern when sessionApproval has multiple patterns", async () => {
+    const deps = makeRunnerDeps({
+      checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
+      promptPermission: vi
+        .fn()
+        .mockResolvedValue({ approved: true, state: "approved_for_session" }),
+    });
+    const descriptor = makeDescriptor({
+      sessionApproval: {
+        surface: "external_directory",
+        patterns: ["/outside/a/*", "/outside/b/*"],
+      },
+    });
+    const result = await runGateCheck(descriptor, null, "tc-1", deps);
+    expect(result).toEqual({ action: "allow" });
+    expect(deps.approveSessionRule).toHaveBeenCalledTimes(2);
+    expect(deps.approveSessionRule).toHaveBeenCalledWith(
+      "external_directory",
+      "/outside/a/*",
+    );
+    expect(deps.approveSessionRule).toHaveBeenCalledWith(
+      "external_directory",
+      "/outside/b/*",
+    );
+  });
+
+  it("returns block and emits user_denied when ask + user denies", async () => {
+    const deps = makeRunnerDeps({
+      checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
+      promptPermission: vi
+        .fn()
+        .mockResolvedValue({ approved: false, state: "denied" }),
+    });
+    const result = await runGateCheck(makeDescriptor(), null, "tc-1", deps);
+    expect(result).toMatchObject({ action: "block" });
+    expect(deps.emitDecision).toHaveBeenCalledWith(
+      expect.objectContaining({
+        result: "deny",
+        resolution: "user_denied",
+      }),
+    );
+  });
+
+  it("returns block and emits confirmation_unavailable when ask + no UI", async () => {
+    const deps = makeRunnerDeps({
+      checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
+      canConfirm: vi.fn().mockReturnValue(false),
+    });
+    const result = await runGateCheck(makeDescriptor(), null, "tc-1", deps);
+    expect(result).toMatchObject({ action: "block" });
+    expect(deps.emitDecision).toHaveBeenCalledWith(
+      expect.objectContaining({
+        result: "deny",
+        resolution: "confirmation_unavailable",
+      }),
+    );
+  });
+
+  it("emits auto_approved resolution when decision has autoApproved flag", async () => {
+    const deps = makeRunnerDeps({
+      checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
+      promptPermission: vi.fn().mockResolvedValue({
+        approved: true,
+        state: "approved",
+        autoApproved: true,
+      }),
+    });
+    const result = await runGateCheck(makeDescriptor(), null, "tc-1", deps);
+    expect(result).toEqual({ action: "allow" });
+    expect(deps.emitDecision).toHaveBeenCalledWith(
+      expect.objectContaining({
+        resolution: "auto_approved",
+      }),
+    );
+  });
+
+  it("uses preResolved.state instead of calling checkPermission", async () => {
+    const deps = makeRunnerDeps();
+    const descriptor = makeDescriptor({
+      preResolved: { state: "deny" },
+    });
+    const result = await runGateCheck(descriptor, null, "tc-1", deps);
+    expect(result).toMatchObject({ action: "block" });
+    expect(deps.checkPermission).not.toHaveBeenCalled();
+    expect(deps.emitDecision).toHaveBeenCalledWith(
+      expect.objectContaining({
+        resolution: "policy_deny",
+      }),
+    );
+  });
+
+  it("uses preResolved.state allow without calling checkPermission", async () => {
+    const deps = makeRunnerDeps();
+    const descriptor = makeDescriptor({
+      preResolved: { state: "allow" },
+    });
+    const result = await runGateCheck(descriptor, null, "tc-1", deps);
+    expect(result).toEqual({ action: "allow" });
+    expect(deps.checkPermission).not.toHaveBeenCalled();
+    expect(deps.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,
+    );
+    expect(result).toEqual({ action: "allow" });
+    expect(deps.checkPermission).toHaveBeenCalledWith(
+      "read",
+      {},
+      "test-agent",
+      [],
+    );
+    expect(deps.emitDecision).toHaveBeenCalledWith(
+      expect.objectContaining({
+        agentName: "test-agent",
+      }),
+    );
+  });
+
+  it("passes requestId from toolCallId to promptPermission", async () => {
+    const deps = makeRunnerDeps({
+      checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
+    });
+    await runGateCheck(makeDescriptor(), null, "tc-42", deps);
+    expect(deps.promptPermission).toHaveBeenCalledWith(
+      expect.objectContaining({ requestId: "tc-42" }),
+    );
+  });
+
+  it("does not call approveSessionRule when user approves once (no sessionApproval)", async () => {
+    const deps = makeRunnerDeps({
+      checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
+      promptPermission: vi
+        .fn()
+        .mockResolvedValue({ approved: true, state: "approved" }),
+    });
+    await runGateCheck(makeDescriptor(), null, "tc-1", deps);
+    expect(deps.approveSessionRule).not.toHaveBeenCalled();
+  });
+
+  it("uses preCheck result directly instead of calling checkPermission", async () => {
+    const deps = makeRunnerDeps();
+    const descriptor = makeDescriptor({
+      preCheck: makeCheckResult("deny", {
+        origin: "global",
+        matchedPattern: "rm *",
+      }),
+    });
+    const result = await runGateCheck(descriptor, null, "tc-1", deps);
+    expect(result).toMatchObject({ action: "block" });
+    expect(deps.checkPermission).not.toHaveBeenCalled();
+    expect(deps.emitDecision).toHaveBeenCalledWith(
+      expect.objectContaining({
+        resolution: "policy_deny",
+        origin: "global",
+        matchedPattern: "rm *",
+      }),
+    );
+  });
+
+  it("does not call approveSessionRule when user approves for session but no sessionApproval on descriptor", async () => {
+    const deps = makeRunnerDeps({
+      checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
+      promptPermission: vi
+        .fn()
+        .mockResolvedValue({ approved: true, state: "approved_for_session" }),
+    });
+    // No sessionApproval on descriptor
+    await runGateCheck(makeDescriptor(), null, "tc-1", deps);
+    expect(deps.approveSessionRule).not.toHaveBeenCalled();
+  });
+});

package/tests/handlers/gates/skill-read.test.ts

@@ -1,9 +1,8 @@
 import { describe, expect, it, vi } from "vitest";
 
-import { evaluateSkillReadGate } from "../../../src/handlers/gates/skill-read";
+import type { GateDescriptor } from "../../../src/handlers/gates/descriptor";
+import { describeSkillReadGate } from "../../../src/handlers/gates/skill-read";
 import type { ToolCallContext } from "../../../src/handlers/gates/types";
-import type { HandlerDeps } from "../../../src/handlers/types";
-import type { PermissionEventBus } from "../../../src/permission-events";
 import type { SkillPromptEntry } from "../../../src/skill-prompt-sanitizer";
 
 // ── SDK stubs ──────────────────────────────────────────────────────────────
@@ -40,165 +39,115 @@ function makeTcc(overrides: Partial<ToolCallContext> = {}): ToolCallContext {
   };
 }
 
-function makeEvents(): PermissionEventBus {
-  return { emit: vi.fn(), on: vi.fn().mockReturnValue(() => undefined) };
-}
-
-function makeRuntime(
-  overrides: Record<string, unknown> = {},
-): HandlerDeps["runtime"] {
-  return {
-    activeSkillEntries: [],
-    writeReviewLog: vi.fn(),
-    ...overrides,
-  } as unknown as HandlerDeps["runtime"];
-}
-
-function makeDeps(overrides: Record<string, unknown> = {}): HandlerDeps {
-  const { runtime: runtimeOverrides, events, ...rest } = overrides;
-  return {
-    runtime: makeRuntime(runtimeOverrides as Record<string, unknown>),
-    events: events ?? makeEvents(),
-    canRequestPermissionConfirmation: vi.fn().mockReturnValue(true),
-    promptPermission: vi
-      .fn()
-      .mockResolvedValue({ approved: true, state: "approved" }),
-    ...rest,
-  } as unknown as HandlerDeps;
-}
-
 // ── tests ──────────────────────────────────────────────────────────────────
 
-describe("evaluateSkillReadGate", () => {
-  it("returns null when tool is not read", async () => {
-    const tcc = makeTcc({ toolName: "write" });
-    const deps = makeDeps({
-      runtime: { activeSkillEntries: [makeSkillEntry()] },
-    });
-    const result = await evaluateSkillReadGate(tcc, deps);
+describe("describeSkillReadGate", () => {
+  it("returns null when tool is not read", () => {
+    const result = describeSkillReadGate(makeTcc({ toolName: "write" }), () => [
+      makeSkillEntry(),
+    ]);
     expect(result).toBeNull();
   });
 
-  it("returns null when no active skill entries", async () => {
-    const tcc = makeTcc();
-    const deps = makeDeps({ runtime: { activeSkillEntries: [] } });
-    const result = await evaluateSkillReadGate(tcc, deps);
+  it("returns null when no active skill entries", () => {
+    const result = describeSkillReadGate(makeTcc(), () => []);
     expect(result).toBeNull();
   });
 
-  it("returns null when read path does not match any skill", async () => {
-    const tcc = makeTcc({ input: { path: "/test/project/src/index.ts" } });
-    const deps = makeDeps({
-      runtime: { activeSkillEntries: [makeSkillEntry()] },
-    });
-    const result = await evaluateSkillReadGate(tcc, deps);
+  it("returns null when read path does not match any skill", () => {
+    const result = describeSkillReadGate(
+      makeTcc({ input: { path: "/test/project/src/index.ts" } }),
+      () => [makeSkillEntry()],
+    );
     expect(result).toBeNull();
   });
 
-  it("returns allow when skill state is allow", async () => {
-    const tcc = makeTcc();
-    const deps = makeDeps({
-      runtime: {
-        activeSkillEntries: [makeSkillEntry({ state: "allow" })],
-      },
-    });
-    const result = await evaluateSkillReadGate(tcc, deps);
-    expect(result).toEqual({ action: "allow" });
+  it("returns null when input has no path", () => {
+    const result = describeSkillReadGate(makeTcc({ input: {} }), () => [
+      makeSkillEntry(),
+    ]);
+    expect(result).toBeNull();
   });
 
-  it("returns block when skill state is deny", async () => {
-    const tcc = makeTcc();
-    const deps = makeDeps({
-      runtime: {
-        activeSkillEntries: [makeSkillEntry({ state: "deny" })],
-      },
-    });
-    const result = await evaluateSkillReadGate(tcc, deps);
-    expect(result).toMatchObject({ action: "block" });
+  it("returns GateDescriptor with preResolved.state matching skill entry state (ask)", () => {
+    const result = describeSkillReadGate(makeTcc(), () => [
+      makeSkillEntry({ state: "ask" }),
+    ]);
+    expect(result).not.toBeNull();
+    const desc = result as GateDescriptor;
+    expect(desc.preResolved).toEqual({ state: "ask" });
   });
 
-  it("returns allow when state is ask and user approves", async () => {
-    const tcc = makeTcc();
-    const deps = makeDeps({
-      runtime: {
-        activeSkillEntries: [makeSkillEntry({ state: "ask" })],
-      },
-      promptPermission: vi
-        .fn()
-        .mockResolvedValue({ approved: true, state: "approved" }),
-    });
-    const result = await evaluateSkillReadGate(tcc, deps);
-    expect(result).toEqual({ action: "allow" });
+  it("returns GateDescriptor with preResolved.state matching skill entry state (allow)", () => {
+    const result = describeSkillReadGate(makeTcc(), () => [
+      makeSkillEntry({ state: "allow" }),
+    ]);
+    expect(result).not.toBeNull();
+    const desc = result as GateDescriptor;
+    expect(desc.preResolved).toEqual({ state: "allow" });
   });
 
-  it("returns block when state is ask and user denies", async () => {
-    const tcc = makeTcc();
-    const deps = makeDeps({
-      runtime: {
-        activeSkillEntries: [makeSkillEntry({ state: "ask" })],
-      },
-      promptPermission: vi
-        .fn()
-        .mockResolvedValue({ approved: false, state: "denied" }),
-    });
-    const result = await evaluateSkillReadGate(tcc, deps);
-    expect(result).toMatchObject({ action: "block" });
+  it("returns GateDescriptor with preResolved.state matching skill entry state (deny)", () => {
+    const result = describeSkillReadGate(makeTcc(), () => [
+      makeSkillEntry({ state: "deny" }),
+    ]);
+    expect(result).not.toBeNull();
+    const desc = result as GateDescriptor;
+    expect(desc.preResolved).toEqual({ state: "deny" });
   });
 
-  it("returns block when state is ask and no UI available", async () => {
-    const tcc = makeTcc();
-    const deps = makeDeps({
-      runtime: {
-        activeSkillEntries: [makeSkillEntry({ state: "ask" })],
-      },
-      canRequestPermissionConfirmation: vi.fn().mockReturnValue(false),
+  it("decision surface is 'skill' and decision value is the skill name", () => {
+    const result = describeSkillReadGate(makeTcc(), () => [
+      makeSkillEntry({ name: "my-skill" }),
+    ]) as GateDescriptor;
+    expect(result.decision.surface).toBe("skill");
+    expect(result.decision.value).toBe("my-skill");
+  });
+
+  it("messages contain the skill name", () => {
+    const result = describeSkillReadGate(makeTcc(), () => [
+      makeSkillEntry({ name: "librarian" }),
+    ]) as GateDescriptor;
+    expect(result.messages.denyReason).toContain("librarian");
+    expect(result.messages.unavailableReason).toContain("librarian");
+    const deniedMsg = result.messages.userDeniedReason({
+      approved: false,
+      state: "denied",
     });
-    const result = await evaluateSkillReadGate(tcc, deps);
-    expect(result).toMatchObject({ action: "block" });
+    expect(deniedMsg).toContain("librarian");
   });
 
-  it("emits decision event with correct fields on deny", async () => {
-    const events = makeEvents();
-    const tcc = makeTcc({ agentName: "test-agent" });
-    const deps = makeDeps({
-      runtime: {
-        activeSkillEntries: [makeSkillEntry({ state: "deny" })],
-      },
-      events,
+  it("promptDetails includes skill_read source and skillName", () => {
+    const result = describeSkillReadGate(
+      makeTcc({ agentName: "test-agent", toolCallId: "tc-42" }),
+      () => [makeSkillEntry({ name: "my-skill" })],
+    ) as GateDescriptor;
+    expect(result.promptDetails).toMatchObject({
+      source: "skill_read",
+      agentName: "test-agent",
+      toolCallId: "tc-42",
+      toolName: "read",
+      skillName: "my-skill",
     });
-    await evaluateSkillReadGate(tcc, deps);
-    expect(events.emit).toHaveBeenCalledWith(
-      "permissions:decision",
-      expect.objectContaining({
-        surface: "skill",
-        value: "librarian",
-        result: "deny",
-        resolution: "policy_deny",
-        origin: null,
-        agentName: "test-agent",
-        matchedPattern: null,
-      }),
-    );
+    expect(result.promptDetails.message).toBeDefined();
   });
 
-  it("emits decision event with correct fields on allow", async () => {
-    const events = makeEvents();
-    const tcc = makeTcc();
-    const deps = makeDeps({
-      runtime: {
-        activeSkillEntries: [makeSkillEntry({ state: "allow" })],
-      },
-      events,
+  it("logContext includes skill_read source and skillName", () => {
+    const result = describeSkillReadGate(
+      makeTcc({ agentName: "agent-1" }),
+      () => [makeSkillEntry({ name: "librarian" })],
+    ) as GateDescriptor;
+    expect(result.logContext).toMatchObject({
+      source: "skill_read",
+      skillName: "librarian",
+      agentName: "agent-1",
     });
-    await evaluateSkillReadGate(tcc, deps);
-    expect(events.emit).toHaveBeenCalledWith(
-      "permissions:decision",
-      expect.objectContaining({
-        surface: "skill",
-        value: "librarian",
-        result: "allow",
-        resolution: "policy_allow",
-      }),
-    );
+  });
+
+  it("surface is 'skill' on the descriptor", () => {
+    const result = describeSkillReadGate(makeTcc(), () => [
+      makeSkillEntry(),
+    ]) as GateDescriptor;
+    expect(result.surface).toBe("skill");
   });
 });