@gotgenes/pi-permission-system 5.15.0 → 5.17.0

package/src/pattern-suggest.ts

@@ -1,4 +1,5 @@
 import { prefix } from "./bash-arity";
+import { PATH_BEARING_TOOLS } from "./path-utils";
 import { deriveApprovalPattern } from "./session-rules";
 
 /** The suggestion returned for a "Yes, for this session" dialog option. */
@@ -69,7 +70,11 @@ function buildLabel(pattern: string, surface: string): string {
     case "external_directory":
       return `Yes, allow access to external directory "${pattern}" for this session`;
     default:
-      // Tool surfaces (read, write, edit, grep, find, ls, extension tools)
+      // Path-bearing tools with a specific path pattern show the pattern.
+      if (PATH_BEARING_TOOLS.has(surface) && pattern !== "*") {
+        return `Yes, allow ${surface} "${pattern}" for this session`;
+      }
+      // Tool surfaces with catch-all or extension tools.
       return `Yes, allow tool "${surface}" for this session`;
   }
 }
@@ -100,7 +105,12 @@ export function suggestSessionPattern(
       pattern = deriveApprovalPattern(value);
       break;
     default:
-      // Tool surfaces (read, write, edit, grep, find, ls, extension tools)
+      // Path-bearing tools: derive a directory-scoped pattern from the path.
+      if (PATH_BEARING_TOOLS.has(surface) && value !== "*") {
+        pattern = deriveApprovalPattern(value);
+        break;
+      }
+      // Extension tools / fallback.
       pattern = "*";
       break;
   }

package/src/permission-manager.ts

@@ -30,7 +30,7 @@ const BUILT_IN_TOOL_PERMISSION_NAMES = new Set([
   "find",
   "ls",
 ]);
-const SPECIAL_PERMISSION_KEYS = new Set(["external_directory"]);
+const SPECIAL_PERMISSION_KEYS = new Set(["external_directory", "path"]);
 
 /** Universal fallback when permission["*"] is absent from all scopes. */
 const DEFAULT_UNIVERSAL_FALLBACK: PermissionState = "ask";

package/src/rule.ts

@@ -79,6 +79,33 @@ export function evaluate(
  * evaluating the first candidate so the caller always receives a concrete
  * result.
  */
+/**
+ * Evaluate a surface against multiple values, returning the most restrictive
+ * non-allow result (deny > ask > allow).
+ *
+ * Used by the cross-cutting `path` surface to aggregate permission decisions
+ * across multiple file paths extracted from a single tool call or bash command.
+ *
+ * Returns `null` when all values evaluate to `allow` (no restriction).
+ * Returns the first `deny` immediately (short-circuit).
+ * Returns the first `ask` if no `deny` is found.
+ */
+export function evaluateMostRestrictive(
+  surface: string,
+  values: string[],
+  rules: Ruleset,
+): { rule: Rule; value: string } | null {
+  let worst: { rule: Rule; value: string } | null = null;
+  for (const value of values) {
+    const rule = evaluate(surface, value, rules);
+    if (rule.action === "deny") return { rule, value };
+    if (rule.action === "ask" && worst?.rule.action !== "ask") {
+      worst = { rule, value };
+    }
+  }
+  return worst;
+}
+
 export function evaluateFirst(
   surface: string,
   values: string[],

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

@@ -9,7 +9,10 @@ vi.mock("node:os", () => {
   };
 });
 
-import { extractExternalPathsFromBashCommand } from "../src/handlers/gates/bash-path-extractor";
+import {
+  extractExternalPathsFromBashCommand,
+  extractTokensForPathRules,
+} from "../src/handlers/gates/bash-path-extractor";
 import {
   formatBashExternalDirectoryAskPrompt,
   formatBashExternalDirectoryDenyReason,
@@ -887,3 +890,80 @@ describe("formatBashExternalDirectoryDenyReason", () => {
     expect(result).toContain("my-agent");
   });
 });
+
+describe("extractTokensForPathRules", () => {
+  test("extracts dot-files: cat .env", async () => {
+    const tokens = await extractTokensForPathRules("cat .env");
+    expect(tokens).toContain(".env");
+  });
+
+  test("extracts relative dot-paths: git add src/.env", async () => {
+    const tokens = await extractTokensForPathRules("git add src/.env");
+    expect(tokens).toContain("src/.env");
+  });
+
+  test("extracts nothing from plain words: echo hello", async () => {
+    const tokens = await extractTokensForPathRules("echo hello");
+    expect(tokens).toHaveLength(0);
+  });
+
+  test("extracts ./src and skips flags: rm -rf ./src", async () => {
+    const tokens = await extractTokensForPathRules("rm -rf ./src");
+    expect(tokens).toContain("./src");
+    expect(tokens).not.toContain("-rf");
+  });
+
+  test("extracts absolute paths: cat /etc/hosts", async () => {
+    const tokens = await extractTokensForPathRules("cat /etc/hosts");
+    expect(tokens).toContain("/etc/hosts");
+  });
+
+  test("skips URLs: curl https://example.com", async () => {
+    const tokens = await extractTokensForPathRules("curl https://example.com");
+    expect(tokens).not.toContain("https://example.com");
+  });
+
+  test("extracts slash-containing tokens: cat src/foo.ts", async () => {
+    const tokens = await extractTokensForPathRules("cat src/foo.ts");
+    expect(tokens).toContain("src/foo.ts");
+  });
+
+  test("skips heredoc content", async () => {
+    const tokens = await extractTokensForPathRules("cat <<EOF\n.env\nEOF");
+    expect(tokens).not.toContain(".env");
+  });
+
+  test("skips @scope/package patterns", async () => {
+    const tokens = await extractTokensForPathRules(
+      "npm install @scope/package",
+    );
+    expect(tokens).not.toContain("@scope/package");
+  });
+
+  test("skips env assignments", async () => {
+    const tokens = await extractTokensForPathRules("FOO=/bar command");
+    expect(tokens).not.toContain("FOO=/bar");
+  });
+
+  test("skips bare-slash tokens", async () => {
+    const tokens = await extractTokensForPathRules("ls /");
+    expect(tokens).not.toContain("/");
+  });
+
+  test("extracts redirect targets: echo test > .env", async () => {
+    const tokens = await extractTokensForPathRules("echo test > .env");
+    expect(tokens).toContain(".env");
+  });
+
+  test("extracts multiple path tokens: cp .env .env.backup", async () => {
+    const tokens = await extractTokensForPathRules("cp .env .env.backup");
+    expect(tokens).toContain(".env");
+    expect(tokens).toContain(".env.backup");
+  });
+
+  test("deduplicates repeated tokens", async () => {
+    const tokens = await extractTokensForPathRules("cat .env && rm .env");
+    const envCount = tokens.filter((t) => t === ".env").length;
+    expect(envCount).toBe(1);
+  });
+});

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/helpers.test.ts

@@ -26,9 +26,22 @@ describe("deriveDecisionValue", () => {
     expect(deriveDecisionValue("mcp", {})).toBe("mcp");
   });
 
-  it("returns toolName for other tools", () => {
+  it("returns toolName for non-path-bearing tools", () => {
+    expect(deriveDecisionValue("my_extension_tool", {})).toBe(
+      "my_extension_tool",
+    );
+  });
+
+  it("returns path for path-bearing tools when path is provided", () => {
+    expect(deriveDecisionValue("read", {}, "/project/src/main.ts")).toBe(
+      "/project/src/main.ts",
+    );
+    expect(deriveDecisionValue("write", {}, "src/.env")).toBe("src/.env");
+  });
+
+  it("falls back to toolName for path-bearing tools when path is missing", () => {
     expect(deriveDecisionValue("read", {})).toBe("read");
-    expect(deriveDecisionValue("write", { command: "ignored" })).toBe("write");
+    expect(deriveDecisionValue("write", {}, undefined)).toBe("write");
   });
 });