@gotgenes/pi-permission-system 5.5.1 → 5.6.1

package/src/handlers/tool-call.ts

@@ -10,17 +10,14 @@ import {
   checkRequestedToolRegistration,
   getToolNameFromValue,
 } from "../tool-registry";
-import { evaluateBashExternalDirectoryGate } from "./gates/bash-external-directory";
-import { evaluateExternalDirectoryGate } from "./gates/external-directory";
-import { evaluateSkillReadGate } from "./gates/skill-read";
-import { evaluateToolGate } from "./gates/tool";
-import type {
-  BashExternalDirectoryGateDeps,
-  ExternalDirectoryGateDeps,
-  SkillReadGateDeps,
-  ToolCallContext,
-  ToolGateDeps,
-} from "./gates/types";
+import { describeBashExternalDirectoryGate } from "./gates/bash-external-directory";
+import type { GateRunnerDeps } from "./gates/descriptor";
+import { isGateBypass } from "./gates/descriptor";
+import { describeExternalDirectoryGate } from "./gates/external-directory";
+import { runGateCheck } from "./gates/runner";
+import { describeSkillReadGate } from "./gates/skill-read";
+import { describeToolGate } from "./gates/tool";
+import type { ToolCallContext } from "./gates/types";
 import type { HandlerDeps, PromptPermissionDetails } from "./types";
 
 /**
@@ -92,10 +89,10 @@ export async function handleToolCall(
   const canConfirm = () => deps.canRequestPermissionConfirmation(ctx);
   const promptPermission = (details: PromptPermissionDetails) =>
     deps.promptPermission(ctx, details);
-  const emitDecision = (e: Parameters<ToolGateDeps["emitDecision"]>[0]) =>
+  const emitDecision: GateRunnerDeps["emitDecision"] = (e) =>
     emitDecisionEvent(deps.events, e);
   const { writeReviewLog } = deps;
-  const checkPermission: ToolGateDeps["checkPermission"] = (
+  const checkPermission: GateRunnerDeps["checkPermission"] = (
     surface,
     input,
     agent,
@@ -111,21 +108,8 @@ export async function handleToolCall(
   const approveSessionRule = (surface: string, pattern: string) =>
     deps.session.sessionRules.approve(surface, pattern);
 
-  // ── Skill-read gate ──────────────────────────────────────────────────────
-  const skillReadGateDeps: SkillReadGateDeps = {
-    getActiveSkillEntries: () => deps.session.activeSkillEntries,
-    writeReviewLog,
-    emitDecision,
-    canConfirm,
-    promptPermission,
-  };
-  const skillResult = await evaluateSkillReadGate(tcc, skillReadGateDeps);
-  if (skillResult?.action === "block") {
-    return { block: true, reason: skillResult.reason };
-  }
-
-  // ── External-directory gate (file tools) ─────────────────────────────────
-  const extDirGateDeps: ExternalDirectoryGateDeps = {
+  // ── Shared runner deps (built once, reused for all gates) ─────────────
+  const runnerDeps: GateRunnerDeps = {
     checkPermission,
     getSessionRuleset,
     approveSessionRule,
@@ -133,44 +117,91 @@ export async function handleToolCall(
     emitDecision,
     canConfirm,
     promptPermission,
-    getInfrastructureDirs: () => [
-      ...deps.piInfrastructureDirs,
-      ...deps.getPiInfrastructureReadPaths(),
-    ],
   };
-  const extDirResult = await evaluateExternalDirectoryGate(tcc, extDirGateDeps);
-  if (extDirResult?.action === "block") {
-    return { block: true, reason: extDirResult.reason };
-  }
 
-  // ── Bash external-directory gate ─────────────────────────────────────────
-  const bashExtGateDeps: BashExternalDirectoryGateDeps = {
-    checkPermission,
-    getSessionRuleset,
-    approveSessionRule,
-    writeReviewLog,
-    canConfirm,
-    promptPermission,
-  };
-  const bashExtResult = await evaluateBashExternalDirectoryGate(
+  // ── Skill-read gate (descriptor + runner) ────────────────────────────────
+  const skillDescriptor = describeSkillReadGate(
     tcc,
-    bashExtGateDeps,
+    () => deps.session.activeSkillEntries,
   );
-  if (bashExtResult?.action === "block") {
-    return { block: true, reason: bashExtResult.reason };
+  if (skillDescriptor) {
+    const skillResult = await runGateCheck(
+      skillDescriptor,
+      tcc.agentName,
+      tcc.toolCallId,
+      runnerDeps,
+    );
+    if (skillResult.action === "block") {
+      return { block: true, reason: skillResult.reason };
+    }
+  }
+
+  // ── External-directory gate (descriptor + runner) ─────────────────────────
+  const infraDirs = [
+    ...deps.piInfrastructureDirs,
+    ...deps.getPiInfrastructureReadPaths(),
+  ];
+  const extDirDesc = describeExternalDirectoryGate(tcc, infraDirs);
+  if (extDirDesc) {
+    if (isGateBypass(extDirDesc)) {
+      if (extDirDesc.log) {
+        writeReviewLog(extDirDesc.log.event, extDirDesc.log.details);
+      }
+      if (extDirDesc.decision) {
+        emitDecision(extDirDesc.decision);
+      }
+    } else {
+      const extDirResult = await runGateCheck(
+        extDirDesc,
+        tcc.agentName,
+        tcc.toolCallId,
+        runnerDeps,
+      );
+      if (extDirResult.action === "block") {
+        return { block: true, reason: extDirResult.reason };
+      }
+    }
   }
 
-  // ── Normal tool permission gate ──────────────────────────────────────────
-  const toolGateDeps: ToolGateDeps = {
+  // ── Bash external-directory gate (descriptor + runner) ─────────────────────
+  const bashExtDesc = await describeBashExternalDirectoryGate(
+    tcc,
     checkPermission,
     getSessionRuleset,
-    approveSessionRule,
-    writeReviewLog,
-    emitDecision,
-    canConfirm,
-    promptPermission,
-  };
-  const toolResult = await evaluateToolGate(tcc, toolGateDeps);
+  );
+  if (bashExtDesc) {
+    if (isGateBypass(bashExtDesc)) {
+      if (bashExtDesc.log) {
+        writeReviewLog(bashExtDesc.log.event, bashExtDesc.log.details);
+      }
+    } else {
+      const bashExtResult = await runGateCheck(
+        bashExtDesc,
+        tcc.agentName,
+        tcc.toolCallId,
+        runnerDeps,
+      );
+      if (bashExtResult.action === "block") {
+        return { block: true, reason: bashExtResult.reason };
+      }
+    }
+  }
+
+  // ── Normal tool permission gate (descriptor + runner) ───────────────────────────
+  const toolCheck = checkPermission(
+    tcc.toolName,
+    tcc.input,
+    tcc.agentName ?? undefined,
+    getSessionRuleset(),
+  );
+  const toolDescriptor = describeToolGate(tcc, toolCheck);
+  toolDescriptor.preCheck = toolCheck;
+  const toolResult = await runGateCheck(
+    toolDescriptor,
+    tcc.agentName,
+    tcc.toolCallId,
+    runnerDeps,
+  );
   if (toolResult.action === "block") {
     return { block: true, reason: toolResult.reason };
   }

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

@@ -1,13 +1,17 @@
 import { describe, expect, it, vi } from "vitest";
-
-import { evaluateBashExternalDirectoryGate } from "../../../src/handlers/gates/bash-external-directory";
+import { describeBashExternalDirectoryGate } from "../../../src/handlers/gates/bash-external-directory";
 import type {
-  BashExternalDirectoryGateDeps,
-  ToolCallContext,
-} from "../../../src/handlers/gates/types";
+  GateBypass,
+  GateDescriptor,
+} from "../../../src/handlers/gates/descriptor";
+import {
+  isGateBypass,
+  isGateDescriptor,
+} from "../../../src/handlers/gates/descriptor";
+import type { ToolCallContext } from "../../../src/handlers/gates/types";
 import type { PermissionCheckResult } from "../../../src/types";
 
-// ── helpers ─────────────��───────────────────────────────────────────���──────
+// ── helpers ────────────────────────────────────────────────────────────────
 
 function makeTcc(overrides: Partial<ToolCallContext> = {}): ToolCallContext {
   return {
@@ -33,158 +37,156 @@ function makeCheckResult(
   };
 }
 
-function makeBashExtGateDeps(
-  overrides: Partial<BashExternalDirectoryGateDeps> = {},
-): BashExternalDirectoryGateDeps {
-  return {
-    checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
-    getSessionRuleset: vi.fn().mockReturnValue([]),
-    approveSessionRule: vi.fn(),
-    writeReviewLog: vi.fn(),
-    canConfirm: vi.fn().mockReturnValue(true),
-    promptPermission: vi
-      .fn()
-      .mockResolvedValue({ approved: true, state: "approved" }),
-    ...overrides,
-  };
-}
-
-// ── tests ─────────────────────────────��───────────────────────────────���────
+// ── tests ──────────────────────────────────────────────────────────────────
 
-describe("evaluateBashExternalDirectoryGate", () => {
+describe("describeBashExternalDirectoryGate", () => {
   it("returns null when tool is not bash", async () => {
-    const tcc = makeTcc({ toolName: "read" });
-    const result = await evaluateBashExternalDirectoryGate(
-      tcc,
-      makeBashExtGateDeps(),
+    const result = await describeBashExternalDirectoryGate(
+      makeTcc({ toolName: "read" }),
+      vi.fn().mockReturnValue(makeCheckResult("ask")),
+      vi.fn().mockReturnValue([]),
     );
     expect(result).toBeNull();
   });
 
   it("returns null when no CWD", async () => {
-    const tcc = makeTcc({ cwd: undefined });
-    const result = await evaluateBashExternalDirectoryGate(
-      tcc,
-      makeBashExtGateDeps(),
+    const result = await describeBashExternalDirectoryGate(
+      makeTcc({ cwd: undefined }),
+      vi.fn().mockReturnValue(makeCheckResult("ask")),
+      vi.fn().mockReturnValue([]),
     );
     expect(result).toBeNull();
   });
 
   it("returns null when command has no external paths", async () => {
-    const tcc = makeTcc({ input: { command: "ls -la" } });
-    const result = await evaluateBashExternalDirectoryGate(
-      tcc,
-      makeBashExtGateDeps(),
+    const result = await describeBashExternalDirectoryGate(
+      makeTcc({ input: { command: "ls -la" } }),
+      vi.fn().mockReturnValue(makeCheckResult("ask")),
+      vi.fn().mockReturnValue([]),
     );
     expect(result).toBeNull();
   });
 
-  it("returns null and logs when all external paths are session-covered", async () => {
-    const deps = makeBashExtGateDeps({
-      checkPermission: vi
-        .fn()
-        .mockReturnValue(makeCheckResult("allow", { source: "session" })),
+  it("returns GateBypass when all external paths are session-covered", async () => {
+    const checkPermission = vi
+      .fn()
+      .mockReturnValue(makeCheckResult("allow", { source: "session" }));
+    const result = await describeBashExternalDirectoryGate(
+      makeTcc(),
+      checkPermission,
+      vi.fn().mockReturnValue([]),
+    );
+    expect(result).not.toBeNull();
+    expect(isGateBypass(result)).toBe(true);
+    const bypass = result as GateBypass;
+    expect(bypass.action).toBe("allow");
+    expect(bypass.log).toMatchObject({
+      event: "permission_request.session_approved",
+      details: expect.objectContaining({ resolution: "session_approved" }),
     });
-    const tcc = makeTcc();
-    const result = await evaluateBashExternalDirectoryGate(tcc, deps);
-    expect(result).toBeNull();
-    expect(deps.writeReviewLog).toHaveBeenCalledWith(
-      "permission_request.session_approved",
-      expect.objectContaining({ resolution: "session_approved" }),
+  });
+
+  it("returns GateDescriptor with multi-pattern sessionApproval for uncovered paths", async () => {
+    const checkPermission = vi.fn().mockReturnValue(makeCheckResult("ask"));
+    const result = await describeBashExternalDirectoryGate(
+      makeTcc({ input: { command: "diff /outside/a.ts /outside/b.ts" } }),
+      checkPermission,
+      vi.fn().mockReturnValue([]),
     );
+    expect(isGateDescriptor(result)).toBe(true);
+    const desc = result as GateDescriptor;
+    expect(desc.sessionApproval).toBeDefined();
+    expect(desc.sessionApproval).toHaveProperty("patterns");
+    const patterns = (desc.sessionApproval as { patterns: string[] }).patterns;
+    expect(patterns.length).toBeGreaterThan(0);
   });
 
-  it("blocks when policy is deny", async () => {
-    const deps = makeBashExtGateDeps({
-      checkPermission: vi.fn().mockReturnValue(makeCheckResult("deny")),
-    });
-    const tcc = makeTcc();
-    const result = await evaluateBashExternalDirectoryGate(tcc, deps);
-    expect(result).toMatchObject({ action: "block" });
+  it("uses config-level checkPermission for the policy state", async () => {
+    const checkPermission = vi
+      .fn()
+      .mockImplementation((surface: string, input: Record<string, unknown>) => {
+        // Path-specific check returns session for coverage filtering
+        if (input.path) return makeCheckResult("allow", { source: "special" });
+        // Config-level check (no path) returns deny
+        return makeCheckResult("deny");
+      });
+    const result = await describeBashExternalDirectoryGate(
+      makeTcc(),
+      checkPermission,
+      vi.fn().mockReturnValue([]),
+    );
+    expect(isGateDescriptor(result)).toBe(true);
+    // The descriptor should carry the deny state from the config-level check
+    // (it will be checked as preCheck by the runner)
+    const desc = result as GateDescriptor;
+    expect(desc.preCheck?.state).toBe("deny");
   });
 
-  it("allows without recording session rules when user approves once", async () => {
-    const deps = makeBashExtGateDeps({
-      checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
-      promptPermission: vi
-        .fn()
-        .mockResolvedValue({ approved: true, state: "approved" }),
-    });
-    const tcc = makeTcc();
-    const result = await evaluateBashExternalDirectoryGate(tcc, deps);
-    expect(result).toEqual({ action: "allow" });
-    expect(deps.approveSessionRule).not.toHaveBeenCalled();
+  it("descriptor surface is 'external_directory'", async () => {
+    const result = await describeBashExternalDirectoryGate(
+      makeTcc(),
+      vi.fn().mockReturnValue(makeCheckResult("ask")),
+      vi.fn().mockReturnValue([]),
+    );
+    const desc = result as GateDescriptor;
+    expect(desc.surface).toBe("external_directory");
   });
 
-  it("records one session rule per uncovered path on approved_for_session", async () => {
-    const deps = makeBashExtGateDeps({
-      checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
-      promptPermission: vi
-        .fn()
-        .mockResolvedValue({ approved: true, state: "approved_for_session" }),
-    });
-    // Command referencing two external paths
-    const tcc = makeTcc({
-      input: {
-        command: "diff /outside/a.ts /outside/b.ts",
-      },
-    });
-    const result = await evaluateBashExternalDirectoryGate(tcc, deps);
-    expect(result).toEqual({ action: "allow" });
-    // Each uncovered path gets its own session rule
-    expect(deps.approveSessionRule).toHaveBeenCalledTimes(2);
-    for (const call of (deps.approveSessionRule as ReturnType<typeof vi.fn>)
-      .mock.calls) {
-      expect(call[0]).toBe("external_directory");
-    }
+  it("descriptor decision surface is 'external_directory'", async () => {
+    const result = await describeBashExternalDirectoryGate(
+      makeTcc(),
+      vi.fn().mockReturnValue(makeCheckResult("ask")),
+      vi.fn().mockReturnValue([]),
+    );
+    const desc = result as GateDescriptor;
+    expect(desc.decision.surface).toBe("external_directory");
   });
 
-  it("blocks when user denies", async () => {
-    const deps = makeBashExtGateDeps({
-      checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
-      promptPermission: vi
-        .fn()
-        .mockResolvedValue({ approved: false, state: "denied" }),
-    });
-    const tcc = makeTcc();
-    const result = await evaluateBashExternalDirectoryGate(tcc, deps);
-    expect(result).toMatchObject({ action: "block" });
+  it("messages contain the command", async () => {
+    const result = await describeBashExternalDirectoryGate(
+      makeTcc({ input: { command: "cat /outside/file.ts" } }),
+      vi.fn().mockReturnValue(makeCheckResult("ask")),
+      vi.fn().mockReturnValue([]),
+    );
+    const desc = result as GateDescriptor;
+    expect(desc.messages.denyReason).toContain("cat /outside/file.ts");
+    expect(desc.messages.unavailableReason).toContain("cat /outside/file.ts");
   });
 
-  it("blocks when no UI available", async () => {
-    const deps = makeBashExtGateDeps({
-      checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
-      canConfirm: vi.fn().mockReturnValue(false),
+  it("promptDetails includes command and tool_call source", async () => {
+    const result = await describeBashExternalDirectoryGate(
+      makeTcc({ agentName: "agent-1", toolCallId: "tc-5" }),
+      vi.fn().mockReturnValue(makeCheckResult("ask")),
+      vi.fn().mockReturnValue([]),
+    );
+    const desc = result as GateDescriptor;
+    expect(desc.promptDetails).toMatchObject({
+      source: "tool_call",
+      agentName: "agent-1",
+      toolCallId: "tc-5",
+      toolName: "bash",
+      command: "cat /outside/project/file.ts",
     });
-    const tcc = makeTcc();
-    const result = await evaluateBashExternalDirectoryGate(tcc, deps);
-    expect(result).toMatchObject({ action: "block" });
   });
 
-  it("only prompts about uncovered paths when some are session-covered", async () => {
+  it("only includes uncovered paths when some are session-covered", async () => {
     const checkPermission = vi
       .fn()
-      .mockImplementation(
-        (
-          surface: string,
-          input: Record<string, unknown>,
-        ): PermissionCheckResult => {
-          if (
-            surface === "external_directory" &&
-            input.path === "/outside/a.ts"
-          ) {
-            return makeCheckResult("allow", { source: "session" });
-          }
-          return makeCheckResult("ask");
-        },
-      );
-    const deps = makeBashExtGateDeps({ checkPermission });
-    const tcc = makeTcc({
-      input: { command: "diff /outside/a.ts /outside/b.ts" },
-    });
-    const result = await evaluateBashExternalDirectoryGate(tcc, deps);
-    expect(result).toEqual({ action: "allow" });
-    // The prompt should have been called (for uncovered /outside/b.ts)
-    expect(deps.promptPermission).toHaveBeenCalled();
+      .mockImplementation((surface: string, input: Record<string, unknown>) => {
+        if (input.path === "/outside/a.ts") {
+          return makeCheckResult("allow", { source: "session" });
+        }
+        return makeCheckResult("ask");
+      });
+    const result = await describeBashExternalDirectoryGate(
+      makeTcc({ input: { command: "diff /outside/a.ts /outside/b.ts" } }),
+      checkPermission,
+      vi.fn().mockReturnValue([]),
+    );
+    expect(isGateDescriptor(result)).toBe(true);
+    const desc = result as GateDescriptor;
+    // Should have patterns only for the uncovered path
+    const patterns = (desc.sessionApproval as { patterns: string[] }).patterns;
+    expect(patterns.length).toBe(1);
   });
 });