@gotgenes/pi-permission-system 3.9.0 → 3.11.0

package/src/synthesize.ts

@@ -0,0 +1,152 @@
+import type { Rule, Ruleset } from "./rule";
+import type { PermissionDefaultPolicy, PermissionState } from "./types";
+
+/**
+ * Convert the merged `defaultPolicy` into catch-all rules at the lowest
+ * priority position in the composed ruleset.
+ *
+ * Produces 5 rules:
+ * 1. `{ surface: "*", pattern: "*" }` — universal fallback (tools default)
+ * 2. `{ surface: "bash", pattern: "*" }` — bash default
+ * 3. `{ surface: "mcp", pattern: "*" }` — mcp default
+ * 4. `{ surface: "skill", pattern: "*" }` — skill default
+ * 5. `{ surface: "special", pattern: "*" }` — special / external_directory default
+ *
+ * All rules carry `layer: "default"`. `evaluate()` ignores this field.
+ * The specific per-surface rules come after the universal rule so they win
+ * via last-match-wins when a surface-specific default differs from the
+ * tools default.
+ */
+export function synthesizeDefaults(defaults: PermissionDefaultPolicy): Ruleset {
+  return [
+    { surface: "*", pattern: "*", action: defaults.tools, layer: "default" },
+    { surface: "bash", pattern: "*", action: defaults.bash, layer: "default" },
+    { surface: "mcp", pattern: "*", action: defaults.mcp, layer: "default" },
+    {
+      surface: "skill",
+      pattern: "*",
+      action: defaults.skills,
+      layer: "default",
+    },
+    {
+      surface: "special",
+      pattern: "*",
+      action: defaults.special,
+      layer: "default",
+    },
+  ];
+}
+
+/**
+ * Per-scope override shape — the relevant keys extracted from `tools`.
+ * `undefined` means the scope did not configure that override.
+ */
+export interface OverrideScope {
+  bash?: PermissionState;
+  mcp?: PermissionState;
+}
+
+/**
+ * Convert per-scope `tools.bash` / `tools.mcp` entries into catch-all rules
+ * placed between defaults and config rules.
+ *
+ * Scopes must be passed in precedence order (lowest first, e.g. global →
+ * project → agent → project-agent). Later scopes produce later rules and
+ * therefore win via last-match-wins — identical to the current last-scope-wins
+ * logic for `bashDefault` / `mcpToolLevel`.
+ *
+ * Only scopes that explicitly define a value contribute a rule; `undefined`
+ * entries are skipped.
+ *
+ * All rules carry `layer: "override"`.
+ */
+export function synthesizeOverrides(
+  scopes: ReadonlyArray<OverrideScope>,
+): Ruleset {
+  const rules: Rule[] = [];
+  for (const scope of scopes) {
+    if (scope.bash !== undefined) {
+      rules.push({
+        surface: "bash",
+        pattern: "*",
+        action: scope.bash,
+        layer: "override",
+      });
+    }
+    if (scope.mcp !== undefined) {
+      rules.push({
+        surface: "mcp",
+        pattern: "*",
+        action: scope.mcp,
+        layer: "override",
+      });
+    }
+  }
+  return rules;
+}
+
+/**
+ * MCP metadata operation targets that are auto-allowed when any explicit MCP
+ * allow rule exists in the config layer.
+ */
+const MCP_BASELINE_TARGETS: readonly string[] = [
+  "mcp_status",
+  "mcp_list",
+  "mcp_search",
+  "mcp_describe",
+  "mcp_connect",
+];
+
+/**
+ * Conditionally synthesize MCP baseline auto-allow rules.
+ *
+ * Emits allow rules for the 5 MCP metadata targets only when `configRules`
+ * contains at least one `surface: "mcp", action: "allow"` rule. This replicates
+ * the `hasAnyMcpAllowRule` heuristic as actual rules.
+ *
+ * When `defaults.mcp === "allow"`, the synthesized default catch-all already
+ * covers all MCP targets — no separate baseline rules are needed (and this
+ * function is not called in that case).
+ *
+ * Baseline rules are placed BEFORE override rules in the composed array so
+ * that `tools.mcp` overrides beat baseline (preserving current behaviour where
+ * an explicit `tools.mcp` value always terminates the MCP decision).
+ *
+ * All rules carry `layer: "baseline"`.
+ */
+export function synthesizeBaseline(configRules: Ruleset): Ruleset {
+  const hasAnyMcpAllow = configRules.some(
+    (r) => r.surface === "mcp" && r.action === "allow",
+  );
+  if (!hasAnyMcpAllow) {
+    return [];
+  }
+  return MCP_BASELINE_TARGETS.map(
+    (target): Rule => ({
+      surface: "mcp",
+      pattern: target,
+      action: "allow",
+      layer: "baseline",
+    }),
+  );
+}
+
+/**
+ * Concatenate all rule layers into a single flat ruleset.
+ *
+ * Priority order (lowest → highest, i.e. earlier index → later index):
+ *   defaults → baseline → overrides → config
+ *
+ * Session rules are NOT included here — they are appended at call-time inside
+ * `checkPermission()` so that the cached composed ruleset remains session-agnostic.
+ *
+ * `evaluate()` scans from the end, so later layers override earlier ones.
+ */
+export function composeRuleset(
+  defaults: Ruleset,
+  baseline: Ruleset,
+  overrides: Ruleset,
+  config: Ruleset,
+): Ruleset {
+  return [...defaults, ...baseline, ...overrides, ...config];
+}

package/src/types.ts

@@ -41,5 +41,5 @@ export interface PermissionCheckResult {
   matchedPattern?: string;
   command?: string;
   target?: string;
-  source: "tool" | "bash" | "mcp" | "skill" | "special" | "default";
+  source: "tool" | "bash" | "mcp" | "skill" | "special" | "default" | "session";
 }

package/tests/handlers/before-agent-start.test.ts

@@ -74,12 +74,11 @@ function makeRuntime(
     lastActiveToolsCacheKey: null,
     lastPromptStateCacheKey: null,
     lastConfigWarning: null,
-    sessionApprovalCache: {
+    sessionRules: {
       approve: vi.fn(),
-      has: vi.fn(),
-      findMatchingPrefix: vi.fn(),
+      getRuleset: vi.fn().mockReturnValue([]),
       clear: vi.fn(),
-    } as unknown as ExtensionRuntime["sessionApprovalCache"],
+    } as unknown as ExtensionRuntime["sessionRules"],
     permissionForwardingContext: null,
     permissionForwardingTimer: null,
     isProcessingForwardedRequests: false,

package/tests/handlers/input.test.ts

@@ -53,12 +53,11 @@ function makeRuntime(
     lastActiveToolsCacheKey: null,
     lastPromptStateCacheKey: null,
     lastConfigWarning: null,
-    sessionApprovalCache: {
+    sessionRules: {
       approve: vi.fn(),
-      has: vi.fn(),
-      findMatchingPrefix: vi.fn(),
+      getRuleset: vi.fn().mockReturnValue([]),
       clear: vi.fn(),
-    } as unknown as ExtensionRuntime["sessionApprovalCache"],
+    } as unknown as ExtensionRuntime["sessionRules"],
     permissionForwardingContext: null,
     permissionForwardingTimer: null,
     isProcessingForwardedRequests: false,

package/tests/handlers/lifecycle.test.ts

@@ -8,7 +8,7 @@ import {
 import type { HandlerDeps } from "../../src/handlers/types";
 import type { PermissionManager } from "../../src/permission-manager";
 import type { ExtensionRuntime } from "../../src/runtime";
-import type { SessionApprovalCache } from "../../src/session-approval-cache";
+import type { SessionRules } from "../../src/session-rules";
 import type { SkillPromptEntry } from "../../src/skill-prompt-sanitizer";
 
 // ── active-agent stub ──────────────────────────────────────────────────────
@@ -59,13 +59,12 @@ function makePermissionManager(
   };
 }
 
-function makeSessionApprovalCache(): SessionApprovalCache {
+function makeSessionRules(): SessionRules {
   return {
     approve: vi.fn(),
-    has: vi.fn().mockReturnValue(false),
-    findMatchingPrefix: vi.fn().mockReturnValue(null),
+    getRuleset: vi.fn().mockReturnValue([]),
     clear: vi.fn(),
-  } as unknown as SessionApprovalCache;
+  } as unknown as SessionRules;
 }
 
 function makeRuntime(
@@ -85,7 +84,7 @@ function makeRuntime(
     lastActiveToolsCacheKey: null,
     lastPromptStateCacheKey: null,
     lastConfigWarning: null,
-    sessionApprovalCache: makeSessionApprovalCache(),
+    sessionRules: makeSessionRules(),
     permissionForwardingContext: null,
     permissionForwardingTimer: null,
     isProcessingForwardedRequests: false,
@@ -330,10 +329,10 @@ describe("handleSessionShutdown", () => {
     expect(deps.runtime.lastPromptStateCacheKey).toBeNull();
   });
 
-  it("clears the session approval cache", async () => {
+  it("clears the session rules", async () => {
     const deps = makeDeps();
     await handleSessionShutdown(deps);
-    expect(deps.runtime.sessionApprovalCache.clear).toHaveBeenCalledOnce();
+    expect(deps.runtime.sessionRules.clear).toHaveBeenCalledOnce();
   });
 
   it("stops forwarded permission polling", async () => {

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

@@ -74,12 +74,11 @@ function makeRuntime(
     lastActiveToolsCacheKey: null,
     lastPromptStateCacheKey: null,
     lastConfigWarning: null,
-    sessionApprovalCache: {
+    sessionRules: {
       approve: vi.fn(),
-      has: vi.fn().mockReturnValue(false),
-      findMatchingPrefix: vi.fn().mockReturnValue(null),
+      getRuleset: vi.fn().mockReturnValue([]),
       clear: vi.fn(),
-    } as unknown as ExtensionRuntime["sessionApprovalCache"],
+    } as unknown as ExtensionRuntime["sessionRules"],
     permissionForwardingContext: null,
     permissionForwardingTimer: null,
     isProcessingForwardedRequests: false,
@@ -339,12 +338,17 @@ describe("handleToolCall — external-directory gate", () => {
   it("allows when session has an existing approval for the external path", async () => {
     const deps = makeDeps({
       runtime: makeRuntime({
-        sessionApprovalCache: {
+        sessionRules: {
           approve: vi.fn(),
-          has: vi.fn().mockReturnValue(false),
-          findMatchingPrefix: vi.fn().mockReturnValue("/outside/project/"),
+          getRuleset: vi.fn().mockReturnValue([
+            {
+              surface: "external_directory",
+              pattern: "/outside/project/*",
+              action: "allow",
+            },
+          ]),
           clear: vi.fn(),
-        } as unknown as ExtensionRuntime["sessionApprovalCache"],
+        } as unknown as ExtensionRuntime["sessionRules"],
       }),
       getAllTools: vi.fn().mockReturnValue([{ name: "read" }]),
     });
@@ -359,18 +363,17 @@ describe("handleToolCall — external-directory gate", () => {
   });
 
   it("approves session when user selects approved_for_session", async () => {
-    const approveCache = {
+    const sessionRules = {
       approve: vi.fn(),
-      has: vi.fn().mockReturnValue(false),
-      findMatchingPrefix: vi.fn().mockReturnValue(null),
+      getRuleset: vi.fn().mockReturnValue([]),
       clear: vi.fn(),
-    } as unknown as ExtensionRuntime["sessionApprovalCache"];
+    } as unknown as ExtensionRuntime["sessionRules"];
     const deps = makeDeps({
       runtime: makeRuntime({
         permissionManager: {
           checkPermission: vi.fn().mockReturnValue(makePermissionResult("ask")),
         } as unknown as ExtensionRuntime["permissionManager"],
-        sessionApprovalCache: approveCache,
+        sessionRules,
       }),
       getAllTools: vi.fn().mockReturnValue([{ name: "read" }]),
       canRequestPermissionConfirmation: vi.fn().mockReturnValue(true),
@@ -385,7 +388,7 @@ describe("handleToolCall — external-directory gate", () => {
       input: { path: "/outside/project/file.ts" },
     };
     await handleToolCall(deps, event, makeCtx());
-    expect(approveCache.approve).toHaveBeenCalledWith(
+    expect(sessionRules.approve).toHaveBeenCalledWith(
       "external_directory",
       expect.any(String),
     );
@@ -419,13 +422,18 @@ describe("handleToolCall — bash external-directory gate", () => {
   it("skips bash external gate when all referenced paths are session-approved", async () => {
     const deps = makeDeps({
       runtime: makeRuntime({
-        sessionApprovalCache: {
+        sessionRules: {
           approve: vi.fn(),
-          // All paths are covered
-          has: vi.fn().mockReturnValue(true),
-          findMatchingPrefix: vi.fn().mockReturnValue(null),
+          // /outside/project/* covers /outside/project/file.ts
+          getRuleset: vi.fn().mockReturnValue([
+            {
+              surface: "external_directory",
+              pattern: "/outside/project/*",
+              action: "allow",
+            },
+          ]),
           clear: vi.fn(),
-        } as unknown as ExtensionRuntime["sessionApprovalCache"],
+        } as unknown as ExtensionRuntime["sessionRules"],
       }),
       getAllTools: vi.fn().mockReturnValue([{ name: "bash" }]),
     });

package/tests/permission-system.test.ts

@@ -46,7 +46,11 @@ import {
   checkRequestedToolRegistration,
   getToolNameFromValue,
 } from "../src/tool-registry";
-import type { PermissionState, ScopeConfig } from "../src/types";
+import type {
+  PermissionCheckResult,
+  PermissionState,
+  ScopeConfig,
+} from "../src/types";
 import {
   canResolveAskPermissionRequest,
   shouldAutoApprovePermissionState,
@@ -2969,3 +2973,193 @@ test("session approval: regular 'Yes' does not create session approval", async (
     rmSync(rootDir, { recursive: true, force: true });
   }
 });
+
+// ---------------------------------------------------------------------------
+// Session-aware checkPermission() integration
+// ---------------------------------------------------------------------------
+
+test("checkPermission returns source 'session' when session rules cover the external_directory path", () => {
+  const { manager, cleanup } = createManager({
+    defaultPolicy: {
+      tools: "allow",
+      bash: "allow",
+      mcp: "allow",
+      skills: "allow",
+      special: "ask",
+    },
+  });
+
+  try {
+    const sessionRules = [
+      {
+        surface: "external_directory",
+        pattern: "/other/project/*",
+        action: "allow" as const,
+        layer: "session" as const,
+      },
+    ];
+
+    const result = manager.checkPermission(
+      "external_directory",
+      { path: "/other/project/src/foo.ts" },
+      undefined,
+      sessionRules,
+    );
+    assert.equal(result.state, "allow");
+    assert.equal(result.source, "session");
+    assert.equal(result.matchedPattern, "/other/project/*");
+  } finally {
+    cleanup();
+  }
+});
+
+test("checkPermission falls back to config policy when session rules do not cover the path", () => {
+  const { manager, cleanup } = createManager({
+    defaultPolicy: {
+      tools: "allow",
+      bash: "allow",
+      mcp: "allow",
+      skills: "allow",
+      special: "deny",
+    },
+  });
+
+  try {
+    const sessionRules = [
+      {
+        surface: "external_directory",
+        pattern: "/other/project/*",
+        action: "allow" as const,
+        layer: "session" as const,
+      },
+    ];
+
+    // Path NOT under /other/project/ — session rules don't match.
+    const result = manager.checkPermission(
+      "external_directory",
+      { path: "/completely/different/path.ts" },
+      undefined,
+      sessionRules,
+    );
+    assert.equal(result.state, "deny");
+    assert.equal(result.source, "special");
+  } finally {
+    cleanup();
+  }
+});
+
+test("checkPermission with empty session rules is identical to call without sessionRules arg", () => {
+  const { manager, cleanup } = createManager({
+    defaultPolicy: {
+      tools: "allow",
+      bash: "allow",
+      mcp: "allow",
+      skills: "allow",
+      special: "ask",
+    },
+    special: { external_directory: "deny" },
+  });
+
+  try {
+    const withEmpty = manager.checkPermission(
+      "external_directory",
+      { path: "/other/project/foo.ts" },
+      undefined,
+      [],
+    );
+    const withoutArg = manager.checkPermission("external_directory", {
+      path: "/other/project/foo.ts",
+    });
+    const expected: PermissionCheckResult = {
+      toolName: "external_directory",
+      state: "deny",
+      matchedPattern: "external_directory",
+      source: "special",
+    };
+    assert.deepEqual(withEmpty, expected);
+    assert.deepEqual(withoutArg, expected);
+  } finally {
+    cleanup();
+  }
+});
+
+test("session rules for one surface do not affect checks on other surfaces", () => {
+  const { manager, cleanup } = createManager({
+    defaultPolicy: {
+      tools: "ask",
+      bash: "ask",
+      mcp: "ask",
+      skills: "ask",
+      special: "ask",
+    },
+  });
+
+  try {
+    const sessionRules = [
+      {
+        surface: "external_directory",
+        pattern: "/other/project/*",
+        action: "allow" as const,
+        layer: "session" as const,
+      },
+    ];
+
+    // Bash check — session rules should not affect bash decisions.
+    const bashResult = manager.checkPermission(
+      "bash",
+      { command: "git status" },
+      undefined,
+      sessionRules,
+    );
+    assert.equal(bashResult.state, "ask");
+    assert.equal(bashResult.source, "bash");
+
+    // MCP check — session rules should not affect MCP decisions.
+    const mcpResult = manager.checkPermission(
+      "mcp",
+      { tool: "exa:search" },
+      undefined,
+      sessionRules,
+    );
+    assert.equal(mcpResult.state, "ask");
+    assert.equal(mcpResult.source, "default");
+  } finally {
+    cleanup();
+  }
+});
+
+test("session rules override config deny for external_directory", () => {
+  const { manager, cleanup } = createManager({
+    defaultPolicy: {
+      tools: "allow",
+      bash: "allow",
+      mcp: "allow",
+      skills: "allow",
+      special: "ask",
+    },
+    special: { external_directory: "deny" },
+  });
+
+  try {
+    const sessionRules = [
+      {
+        surface: "external_directory",
+        pattern: "/other/project/*",
+        action: "allow" as const,
+        layer: "session" as const,
+      },
+    ];
+
+    // Session approval overrides config deny for the covered path.
+    const result = manager.checkPermission(
+      "external_directory",
+      { path: "/other/project/src/foo.ts" },
+      undefined,
+      sessionRules,
+    );
+    assert.equal(result.state, "allow");
+    assert.equal(result.source, "session");
+  } finally {
+    cleanup();
+  }
+});

package/tests/rule.test.ts

@@ -137,4 +137,35 @@ describe("evaluate", () => {
     expect(result.pattern).toBe("git status");
     expect(result.action).toBe("ask");
   });
+
+  test("rule.layer is ignored by evaluate() — matching is identical with or without it", () => {
+    const withLayer: Rule = {
+      surface: "bash",
+      pattern: "git *",
+      action: "allow",
+      layer: "config",
+    };
+    const withoutLayer: Rule = {
+      surface: "bash",
+      pattern: "git *",
+      action: "allow",
+    };
+    const withDefault: Rule = {
+      surface: "bash",
+      pattern: "*",
+      action: "ask",
+      layer: "default",
+    };
+    // Both rules with and without layer field produce the same match.
+    expect(evaluate("bash", "git status", [withLayer]).action).toBe("allow");
+    expect(evaluate("bash", "git status", [withoutLayer]).action).toBe("allow");
+    // Layer metadata does not affect last-match-wins ordering.
+    const ruleset: Rule[] = [withDefault, withLayer];
+    expect(evaluate("bash", "git status", ruleset)).toEqual(withLayer);
+    // A rule with layer: "default" still wins if it is last in the array.
+    const reversedRuleset: Rule[] = [withLayer, withDefault];
+    expect(evaluate("bash", "git status", reversedRuleset)).toEqual(
+      withDefault,
+    );
+  });
 });

package/tests/runtime.test.ts

@@ -68,8 +68,9 @@ vi.mock("../src/subagent-context", () => ({
   isSubagentExecutionContext: vi.fn().mockReturnValue(false),
 }));
 
-vi.mock("../src/session-approval-cache", () => ({
-  SessionApprovalCache: vi.fn(),
+vi.mock("../src/session-rules", () => ({
+  SessionRules: vi.fn(),
+  deriveApprovalPattern: vi.fn(),
 }));
 
 import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
@@ -184,9 +185,9 @@ describe("createExtensionRuntime", () => {
     expect(runtime.isProcessingForwardedRequests).toBe(false);
   });
 
-  it("creates a sessionApprovalCache instance", () => {
+  it("creates a sessionRules instance", () => {
     const runtime = createExtensionRuntime({ agentDir: "/test/agent" });
-    expect(runtime.sessionApprovalCache).toBeDefined();
+    expect(runtime.sessionRules).toBeDefined();
   });
 
   // ── Mutable state is writable ──────────────────────────────────────────