@gotgenes/pi-permission-system 5.16.0 → 5.17.0

package/tests/handlers/external-directory-integration.test.ts

@@ -47,9 +47,29 @@ function makeCheckPermission(
   return vi
     .fn()
     .mockImplementation((surface: string): PermissionCheckResult => {
-      const state =
-        surface === "external_directory" ? externalDirectoryState : toolState;
-      return { state, toolName: surface, source: "tool", origin: "builtin" };
+      if (surface === "external_directory") {
+        return {
+          state: externalDirectoryState,
+          toolName: surface,
+          source: "tool",
+          origin: "builtin",
+        };
+      }
+      // The cross-cutting path gate runs before ext-dir; keep it transparent.
+      if (surface === "path") {
+        return {
+          state: "allow",
+          toolName: surface,
+          source: "special",
+          origin: "builtin",
+        };
+      }
+      return {
+        state: toolState,
+        toolName: surface,
+        source: "tool",
+        origin: "builtin",
+      };
     });
 }
 
@@ -294,6 +314,67 @@ describe("external_directory policy state — allow", () => {
   });
 });
 
+// #144: allow external reads, gate external writes
+describe("external_directory — allow external reads, gate external writes (#144)", () => {
+  it("allows read of external path when external_directory and read are both allow", async () => {
+    const { handler } = makeHandler({
+      session: { checkPermission: makeCheckPermission("allow", "allow") },
+    });
+    const event = makeToolCallEvent("read", { path: EXTERNAL_PATH });
+    const result = await handler.handleToolCall(event, makeCtx());
+    expect(result).toEqual({});
+  });
+
+  it("prompts for write to external path when external_directory allows but write is ask", async () => {
+    const prompt = vi
+      .fn()
+      .mockResolvedValue({ approved: true, state: "approved" });
+    const { handler } = makeHandler({
+      session: {
+        checkPermission: makeCheckPermission("allow", "ask"),
+        prompt,
+      },
+    });
+    const event = makeToolCallEvent("write", { path: EXTERNAL_PATH });
+    const result = await handler.handleToolCall(event, makeCtx());
+    // external_directory passes; write gate prompts and user approves
+    expect(result).toEqual({});
+    expect(prompt).toHaveBeenCalledOnce();
+  });
+
+  it("blocks write to external path when external_directory allows but write is deny", async () => {
+    const { handler } = makeHandler({
+      session: { checkPermission: makeCheckPermission("allow", "deny") },
+    });
+    const event = makeToolCallEvent("write", { path: EXTERNAL_PATH });
+    const result = await handler.handleToolCall(event, makeCtx());
+    expect(result.block).toBe(true);
+  });
+
+  it("emits separate decision events for external_directory and write surfaces", async () => {
+    const { handler, events } = makeHandler({
+      session: { checkPermission: makeCheckPermission("allow", "deny") },
+    });
+    const event = makeToolCallEvent("write", { path: EXTERNAL_PATH });
+    await handler.handleToolCall(event, makeCtx());
+    const decisions = getDecisionEvents(events);
+    const extDirDecision = decisions.find(
+      (d) => d.surface === "external_directory",
+    );
+    const writeDecision = decisions.find((d) => d.surface === "write");
+    expect(extDirDecision).toMatchObject({
+      surface: "external_directory",
+      result: "allow",
+      resolution: "policy_allow",
+    });
+    expect(writeDecision).toMatchObject({
+      surface: "write",
+      result: "deny",
+      resolution: "policy_deny",
+    });
+  });
+});
+
 describe("external_directory policy state — deny", () => {
   it("blocks with reason containing the external path", async () => {
     const { handler } = makeHandler({

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

@@ -0,0 +1,260 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+// Mock node:os so tilde-expansion is deterministic across platforms.
+vi.mock("node:os", () => {
+  const homedir = vi.fn(() => "/mock/home");
+  return {
+    homedir,
+    default: { homedir },
+  };
+});
+
+import { describeBashPathGate } from "../../../src/handlers/gates/bash-path";
+import type {
+  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 { Rule } from "../../../src/rule";
+import type { PermissionCheckResult } from "../../../src/types";
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+function makeTcc(overrides: Partial<ToolCallContext> = {}): ToolCallContext {
+  return {
+    toolName: "bash",
+    agentName: null,
+    input: { command: "cat .env" },
+    toolCallId: "tc-1",
+    cwd: "/test/project",
+    ...overrides,
+  };
+}
+
+function makeCheckResult(
+  overrides: Partial<PermissionCheckResult> = {},
+): PermissionCheckResult {
+  return {
+    toolName: "path",
+    state: "allow",
+    source: "special",
+    origin: "global",
+    ...overrides,
+  };
+}
+
+type CheckPermissionFn = (
+  surface: string,
+  input: unknown,
+  agentName?: string,
+  sessionRules?: Rule[],
+) => PermissionCheckResult;
+
+// ── 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(
+      makeTcc({ toolName: "read", input: { path: ".env" } }),
+      checkPermission,
+      getSessionRuleset,
+    );
+    expect(result).toBeNull();
+  });
+
+  it("returns null when no tokens are extracted", async () => {
+    const checkPermission = vi.fn<CheckPermissionFn>();
+    const getSessionRuleset = vi.fn<() => Rule[]>().mockReturnValue([]);
+    const result = await describeBashPathGate(
+      makeTcc({ input: { command: "echo hello" } }),
+      checkPermission,
+      getSessionRuleset,
+    );
+    expect(result).toBeNull();
+  });
+
+  it("returns null when all tokens evaluate to allow", async () => {
+    const checkPermission = vi
+      .fn<CheckPermissionFn>()
+      .mockReturnValue(makeCheckResult({ state: "allow" }));
+    const getSessionRuleset = vi.fn<() => Rule[]>().mockReturnValue([]);
+    const result = await describeBashPathGate(
+      makeTcc({ input: { command: "cat .env" } }),
+      checkPermission,
+      getSessionRuleset,
+    );
+    expect(result).toBeNull();
+  });
+
+  it("returns GateDescriptor when a token evaluates to deny", async () => {
+    const checkPermission = vi.fn<CheckPermissionFn>().mockReturnValue(
+      makeCheckResult({
+        state: "deny",
+        matchedPattern: "*.env",
+      }),
+    );
+    const getSessionRuleset = vi.fn<() => Rule[]>().mockReturnValue([]);
+    const result = await describeBashPathGate(
+      makeTcc({ input: { command: "cat .env" } }),
+      checkPermission,
+      getSessionRuleset,
+    );
+    expect(result).not.toBeNull();
+    expect(isGateDescriptor(result)).toBe(true);
+    const desc = result as GateDescriptor;
+    expect(desc.surface).toBe("path");
+    expect(desc.preCheck?.state).toBe("deny");
+  });
+
+  it("returns GateDescriptor when a token evaluates to ask", async () => {
+    const checkPermission = vi
+      .fn<CheckPermissionFn>()
+      .mockReturnValue(makeCheckResult({ state: "ask" }));
+    const getSessionRuleset = vi.fn<() => Rule[]>().mockReturnValue([]);
+    const result = await describeBashPathGate(
+      makeTcc({ input: { command: "cat .env" } }),
+      checkPermission,
+      getSessionRuleset,
+    );
+    expect(result).not.toBeNull();
+    expect(isGateDescriptor(result)).toBe(true);
+    const desc = result as GateDescriptor;
+    expect(desc.preCheck?.state).toBe("ask");
+  });
+
+  it("descriptor includes triggering token in prompt message", async () => {
+    const checkPermission = vi
+      .fn<CheckPermissionFn>()
+      .mockReturnValue(makeCheckResult({ state: "deny" }));
+    const getSessionRuleset = vi.fn<() => Rule[]>().mockReturnValue([]);
+    const result = (await describeBashPathGate(
+      makeTcc({ input: { command: "cat .env" } }),
+      checkPermission,
+      getSessionRuleset,
+    )) as GateDescriptor;
+    expect(result.messages.denyReason).toContain(".env");
+    expect(result.promptDetails.message).toContain(".env");
+  });
+
+  it("descriptor decision uses surface 'path'", async () => {
+    const checkPermission = vi
+      .fn<CheckPermissionFn>()
+      .mockReturnValue(makeCheckResult({ state: "deny" }));
+    const getSessionRuleset = vi.fn<() => Rule[]>().mockReturnValue([]);
+    const result = (await describeBashPathGate(
+      makeTcc({ input: { command: "cat .env" } }),
+      checkPermission,
+      getSessionRuleset,
+    )) as GateDescriptor;
+    expect(result.decision.surface).toBe("path");
+  });
+
+  it("returns GateBypass when session rule covers the path", async () => {
+    const checkPermission = vi
+      .fn<CheckPermissionFn>()
+      .mockReturnValue(makeCheckResult({ state: "allow", source: "session" }));
+    const getSessionRuleset = vi.fn<() => Rule[]>().mockReturnValue([
+      {
+        surface: "path",
+        pattern: "*",
+        action: "allow",
+        layer: "session",
+        origin: "session",
+      },
+    ]);
+    const result = await describeBashPathGate(
+      makeTcc({ input: { command: "cat .env" } }),
+      checkPermission,
+      getSessionRuleset,
+    );
+    expect(result).not.toBeNull();
+    expect(isGateBypass(result)).toBe(true);
+    expect((result as GateBypass).action).toBe("allow");
+  });
+
+  it("returns null when command is missing", async () => {
+    const checkPermission = vi.fn<CheckPermissionFn>();
+    const getSessionRuleset = vi.fn<() => Rule[]>().mockReturnValue([]);
+    const result = await describeBashPathGate(
+      makeTcc({ input: {} }),
+      checkPermission,
+      getSessionRuleset,
+    );
+    expect(result).toBeNull();
+  });
+
+  it("evaluates most restrictive across multiple tokens", async () => {
+    const checkPermission = vi
+      .fn<CheckPermissionFn>()
+      .mockImplementation((_surface, input) => {
+        const record = input as Record<string, unknown>;
+        if (record.path === "src/foo.ts") {
+          return makeCheckResult({ state: "allow" });
+        }
+        return makeCheckResult({ state: "deny", matchedPattern: "*.env" });
+      });
+    const getSessionRuleset = vi.fn<() => Rule[]>().mockReturnValue([]);
+    const result = await describeBashPathGate(
+      makeTcc({ input: { command: "cat src/foo.ts .env" } }),
+      checkPermission,
+      getSessionRuleset,
+    );
+    expect(result).not.toBeNull();
+    expect(isGateDescriptor(result)).toBe(true);
+    expect((result as GateDescriptor).preCheck?.state).toBe("deny");
+  });
+
+  it("deny wins in multi-token: cp .env README.md", async () => {
+    const checkPermission = vi
+      .fn<CheckPermissionFn>()
+      .mockImplementation((_surface, input) => {
+        const record = input as Record<string, unknown>;
+        if (record.path === ".env") {
+          return makeCheckResult({ state: "deny", matchedPattern: "*.env" });
+        }
+        return makeCheckResult({ state: "allow" });
+      });
+    const getSessionRuleset = vi.fn<() => Rule[]>().mockReturnValue([]);
+    const result = await describeBashPathGate(
+      makeTcc({ input: { command: "cp .env README.md" } }),
+      checkPermission,
+      getSessionRuleset,
+    );
+    expect(result).not.toBeNull();
+    expect(isGateDescriptor(result)).toBe(true);
+    const desc = result as GateDescriptor;
+    expect(desc.preCheck?.state).toBe("deny");
+    expect(desc.decision.value).toBe(".env");
+  });
+
+  it("extracts redirect target: echo test > .env triggers deny", async () => {
+    const checkPermission = vi
+      .fn<CheckPermissionFn>()
+      .mockImplementation((_surface, input) => {
+        const record = input as Record<string, unknown>;
+        if (record.path === ".env") {
+          return makeCheckResult({ state: "deny", matchedPattern: "*.env" });
+        }
+        return makeCheckResult({ state: "allow" });
+      });
+    const getSessionRuleset = vi.fn<() => Rule[]>().mockReturnValue([]);
+    const result = await describeBashPathGate(
+      makeTcc({ input: { command: "echo test > .env" } }),
+      checkPermission,
+      getSessionRuleset,
+    );
+    expect(result).not.toBeNull();
+    expect(isGateDescriptor(result)).toBe(true);
+    expect((result as GateDescriptor).preCheck?.state).toBe("deny");
+  });
+});

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

@@ -0,0 +1,149 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type { GateDescriptor } from "../../../src/handlers/gates/descriptor";
+import { isGateDescriptor } from "../../../src/handlers/gates/descriptor";
+import { describePathGate } from "../../../src/handlers/gates/path";
+import type { ToolCallContext } from "../../../src/handlers/gates/types";
+import type { PermissionCheckResult } from "../../../src/types";
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+function makeTcc(overrides: Partial<ToolCallContext> = {}): ToolCallContext {
+  return {
+    toolName: "read",
+    agentName: null,
+    input: { path: ".env" },
+    toolCallId: "tc-1",
+    cwd: "/test/project",
+    ...overrides,
+  };
+}
+
+function makeCheckResult(
+  overrides: Partial<PermissionCheckResult> = {},
+): PermissionCheckResult {
+  return {
+    toolName: "path",
+    state: "allow",
+    source: "special",
+    origin: "global",
+    ...overrides,
+  };
+}
+
+type CheckPermissionFn = (
+  surface: string,
+  input: unknown,
+  agentName?: string,
+  sessionRules?: unknown[],
+) => PermissionCheckResult;
+
+// ── tests ──────────────────────────────────────────────────────────────────
+
+describe("describePathGate", () => {
+  it("returns null for non-path-bearing tools", () => {
+    const checkPermission = vi.fn<CheckPermissionFn>();
+    const result = describePathGate(
+      makeTcc({ toolName: "bash", input: { command: "ls" } }),
+      checkPermission,
+    );
+    expect(result).toBeNull();
+    expect(checkPermission).not.toHaveBeenCalled();
+  });
+
+  it("returns null when tool has no extractable path", () => {
+    const checkPermission = vi.fn<CheckPermissionFn>();
+    const result = describePathGate(
+      makeTcc({ toolName: "read", input: {} }),
+      checkPermission,
+    );
+    expect(result).toBeNull();
+  });
+
+  it("returns null when path check result is allow", () => {
+    const checkPermission = vi
+      .fn<CheckPermissionFn>()
+      .mockReturnValue(makeCheckResult({ state: "allow" }));
+    const result = describePathGate(makeTcc(), checkPermission);
+    expect(result).toBeNull();
+  });
+
+  it("returns GateDescriptor when path check result is deny", () => {
+    const checkPermission = vi.fn<CheckPermissionFn>().mockReturnValue(
+      makeCheckResult({
+        state: "deny",
+        matchedPattern: "*.env",
+      }),
+    );
+    const result = describePathGate(makeTcc(), checkPermission);
+    expect(result).not.toBeNull();
+    expect(isGateDescriptor(result)).toBe(true);
+    const desc = result as GateDescriptor;
+    expect(desc.surface).toBe("path");
+    expect(desc.preCheck?.state).toBe("deny");
+  });
+
+  it("returns GateDescriptor when path check result is ask", () => {
+    const checkPermission = vi.fn<CheckPermissionFn>().mockReturnValue(
+      makeCheckResult({
+        state: "ask",
+        matchedPattern: "*.env",
+      }),
+    );
+    const result = describePathGate(makeTcc(), checkPermission);
+    expect(result).not.toBeNull();
+    expect(isGateDescriptor(result)).toBe(true);
+    const desc = result as GateDescriptor;
+    expect(desc.surface).toBe("path");
+    expect(desc.preCheck?.state).toBe("ask");
+  });
+
+  it("descriptor has correct session approval surface and pattern", () => {
+    const checkPermission = vi
+      .fn<CheckPermissionFn>()
+      .mockReturnValue(makeCheckResult({ state: "ask" }));
+    const result = describePathGate(
+      makeTcc({ input: { path: "/test/project/src/.env" } }),
+      checkPermission,
+    ) as GateDescriptor;
+    expect(result.sessionApproval).toBeDefined();
+    expect(result.sessionApproval).toHaveProperty("surface", "path");
+    expect(result.sessionApproval).toHaveProperty("pattern");
+  });
+
+  it("descriptor messages reference the file path", () => {
+    const checkPermission = vi
+      .fn<CheckPermissionFn>()
+      .mockReturnValue(makeCheckResult({ state: "deny" }));
+    const result = describePathGate(
+      makeTcc(),
+      checkPermission,
+    ) as GateDescriptor;
+    expect(result.messages.denyReason).toContain(".env");
+    expect(result.messages.unavailableReason).toContain(".env");
+  });
+
+  it("descriptor decision uses surface 'path' and the file path as value", () => {
+    const checkPermission = vi
+      .fn<CheckPermissionFn>()
+      .mockReturnValue(makeCheckResult({ state: "deny" }));
+    const result = describePathGate(
+      makeTcc(),
+      checkPermission,
+    ) as GateDescriptor;
+    expect(result.decision.surface).toBe("path");
+    expect(result.decision.value).toBe(".env");
+  });
+
+  it("passes agentName to checkPermission", () => {
+    const checkPermission = vi
+      .fn<CheckPermissionFn>()
+      .mockReturnValue(makeCheckResult({ state: "allow" }));
+    describePathGate(makeTcc({ agentName: "my-agent" }), checkPermission);
+    expect(checkPermission).toHaveBeenCalledWith(
+      "path",
+      { path: ".env" },
+      "my-agent",
+    );
+  });
+});

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

@@ -297,3 +297,81 @@ describe("handleToolCall — bash external-directory gate", () => {
     expect(result).toMatchObject({ block: true });
   });
 });
+
+// ── path gate (tools) ─────────────────────────────────────────────────────
+
+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 makePermissionResult("deny");
+          }
+          return makePermissionResult("allow");
+        },
+      );
+    const { handler } = makeHandler({
+      session: { checkPermission },
+      toolRegistry: {
+        getAll: vi.fn().mockReturnValue([{ name: "read" }]),
+      },
+    });
+    const event = {
+      type: "tool_call",
+      toolCallId: "tc-path",
+      name: "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",
+      input: { path: "src/index.ts" },
+    };
+    const result = await handler.handleToolCall(event, makeCtx());
+    expect(result).toEqual({});
+  });
+});
+
+// ── bash path gate ────────────────────────────────────────────────────────
+
+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 makePermissionResult("deny");
+          }
+          return makePermissionResult("allow");
+        },
+      );
+    const { handler } = makeHandler({
+      session: { checkPermission },
+      toolRegistry: {
+        getAll: vi.fn().mockReturnValue([{ name: "bash" }]),
+      },
+    });
+    const event = {
+      type: "tool_call",
+      toolCallId: "tc-bash-path",
+      name: "bash",
+      input: { command: "cat .env" },
+    };
+    const result = await handler.handleToolCall(event, makeCtx());
+    expect(result).toMatchObject({ block: true });
+  });
+});

package/tests/input-normalizer.test.ts

@@ -3,6 +3,30 @@ import { normalizeInput } from "../src/input-normalizer";
 import { createMcpPermissionTargets } from "../src/mcp-targets";
 
 describe("normalizeInput — non-MCP surfaces", () => {
+  describe("special / path", () => {
+    it("uses path from input as the lookup value", () => {
+      const result = normalizeInput("path", { path: ".env" }, []);
+      expect(result.surface).toBe("path");
+      expect(result.values).toEqual([".env"]);
+      expect(result.resultExtras).toEqual({});
+    });
+
+    it("falls back to '*' when path is missing", () => {
+      const result = normalizeInput("path", {}, []);
+      expect(result.values).toEqual(["*"]);
+    });
+
+    it("falls back to '*' when path is not a string", () => {
+      const result = normalizeInput("path", { path: 42 }, []);
+      expect(result.values).toEqual(["*"]);
+    });
+
+    it("handles null input", () => {
+      const result = normalizeInput("path", null, []);
+      expect(result.values).toEqual(["*"]);
+    });
+  });
+
   describe("special / external_directory", () => {
     it("uses path from input as the lookup value", () => {
       const result = normalizeInput(