@gotgenes/pi-permission-system 5.16.0 → 5.18.0

package/src/permission-event-rpc.ts

@@ -6,6 +6,7 @@
  * permission prompts without importing this package.
  */
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { buildInputForSurface } from "./input-normalizer";
 import type {
   PermissionPromptDecision,
   RequestPermissionOptions,
@@ -79,26 +80,6 @@ function errorReply(error: string): PermissionsRpcReply {
   };
 }
 
-/**
- * Construct a surface-appropriate input object from a raw value string.
- *
- * Note: MCP inputs are complex (server name + tool name derivation). Callers
- * providing an MCP surface receive a best-effort policy evaluation using the
- * value as a pre-qualified target string. Pass the fully-qualified target
- * (e.g. "exa:search" or "exa") directly.
- */
-function buildInputForSurface(
-  surface: string,
-  value: string | undefined,
-): unknown {
-  const v = value ?? "";
-  if (surface === "bash") return { command: v };
-  if (surface === "skill") return { name: v };
-  if (surface === "external_directory") return { path: v };
-  // MCP and tool surfaces: normalizeInput handles them from the surface alone.
-  return {};
-}
-
 // ── RPC handler: permissions:rpc:check ────────────────────────────────────
 
 function handleCheckRpc(

package/src/permission-events.ts

@@ -30,7 +30,19 @@ export const PERMISSIONS_READY_CHANNEL = "permissions:ready";
 /** Emitted after every permission gate resolution. */
 export const PERMISSIONS_DECISION_CHANNEL = "permissions:decision";
 
-/** RPC request channel — query the permission policy (no prompting). */
+/**
+ * RPC request channel — query the permission policy (no prompting).
+ *
+ * @deprecated Use the `Symbol.for()`-backed service accessor instead:
+ * ```typescript
+ * const { getPermissionsService } = await import("@gotgenes/pi-permission-system");
+ * const service = getPermissionsService();
+ * if (service) {
+ *   const result = service.checkPermission("bash", "git push");
+ * }
+ * ```
+ * The event-bus RPC remains available as a zero-dependency fallback.
+ */
 export const PERMISSIONS_RPC_CHECK_CHANNEL = "permissions:rpc:check";
 
 /** RPC request channel — forward a permission prompt to the parent UI. */
@@ -88,7 +100,12 @@ export interface PermissionDecisionEvent {
 
 // ── permissions:rpc:check ──────────────────────────────────────────────────
 
-/** Request payload for `permissions:rpc:check`. */
+/**
+ * Request payload for `permissions:rpc:check`.
+ *
+ * @deprecated Prefer `getPermissionsService().checkPermission()` from the
+ * service accessor module. See `PERMISSIONS_RPC_CHECK_CHANNEL` for details.
+ */
 export interface PermissionsCheckRequest {
   requestId: string;
   /** Permission surface to evaluate. */
@@ -99,7 +116,12 @@ export interface PermissionsCheckRequest {
   agentName?: string;
 }
 
-/** Data field in a successful `permissions:rpc:check` reply. */
+/**
+ * Data field in a successful `permissions:rpc:check` reply.
+ *
+ * @deprecated Prefer `getPermissionsService().checkPermission()` from the
+ * service accessor module. See `PERMISSIONS_RPC_CHECK_CHANNEL` for details.
+ */
 export interface PermissionsCheckReplyData {
   result: "allow" | "deny" | "ask";
   matchedPattern: string | null;

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/src/service.ts

@@ -0,0 +1,75 @@
+/**
+ * Cross-extension service accessor backed by `Symbol.for()` on `globalThis`.
+ *
+ * `Symbol.for()` is process-global by spec, so it survives jiti's per-extension
+ * module isolation (`moduleCache: false`). A consumer doing
+ * `import("@gotgenes/pi-permission-system")` gets a fresh module copy, but
+ * `getPermissionsService()` reads from the same `globalThis` slot the provider
+ * wrote to — enabling direct, synchronous, type-safe function calls.
+ *
+ * Best practice: call `getPermissionsService()` per use rather than caching the
+ * reference — this ensures resilience across `/reload` and load-order edge cases.
+ */
+
+import type { PermissionCheckResult, PermissionState } from "./types";
+
+export type { PermissionCheckResult, PermissionState };
+
+/** Process-global key for the service slot. */
+const SERVICE_KEY = Symbol.for("@gotgenes/pi-permission-system:service");
+
+/**
+ * Public interface exposed to other extensions via `getPermissionsService()`.
+ *
+ * Mirrors the simplified RPC signature — surface + optional value + optional
+ * agent name — and delegates to `PermissionManager.checkPermission()` with
+ * current session rules internally.
+ */
+export interface PermissionsService {
+  /**
+   * Query the permission policy for a surface and value.
+   *
+   * @param surface   - Permission surface: "bash", "read", "mcp", "skill",
+   *                    "external_directory", etc.
+   * @param value     - The value to evaluate: command string, tool name, skill
+   *                    name, or path. Omit or pass `undefined` for a
+   *                    surface-level query.
+   * @param agentName - Optional agent name for per-agent policy resolution.
+   * @returns Full check result including state, matched pattern, and origin.
+   */
+  checkPermission(
+    surface: string,
+    value?: string,
+    agentName?: string,
+  ): PermissionCheckResult;
+}
+
+/**
+ * Store a `PermissionsService` on `globalThis` so other extensions can
+ * retrieve it via `getPermissionsService()`.
+ *
+ * Overwrites any previously published service — safe for `/reload`.
+ */
+export function publishPermissionsService(service: PermissionsService): void {
+  (globalThis as Record<symbol, unknown>)[SERVICE_KEY] = service;
+}
+
+/**
+ * Retrieve the published `PermissionsService`, or `undefined` if the
+ * permission-system extension has not loaded (or has been unloaded).
+ */
+export function getPermissionsService(): PermissionsService | undefined {
+  return (globalThis as Record<symbol, unknown>)[SERVICE_KEY] as
+    | PermissionsService
+    | undefined;
+}
+
+/**
+ * Remove the service from `globalThis`.
+ *
+ * Called during `session_shutdown` to avoid stale references after the
+ * extension is torn down.
+ */
+export function unpublishPermissionsService(): void {
+  delete (globalThis as Record<symbol, unknown>)[SERVICE_KEY];
+}

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");
+  });
+});