@gotgenes/pi-permission-system 3.5.0 → 3.7.0

package/src/permission-manager.ts

@@ -12,6 +12,8 @@ import {
 } from "./common";
 import { loadUnifiedConfig, stripJsonComments } from "./config-loader";
 import { getGlobalConfigPath } from "./config-paths";
+import type { Rule, Ruleset } from "./rule";
+import { evaluate } from "./rule";
 import type {
   AgentPermissions,
   BashPermissions,
@@ -375,6 +377,8 @@ type ResolvedPermissions = {
   globalConfig: GlobalPermissionConfig;
   agentConfig: AgentPermissions;
   merged: GlobalPermissionConfig;
+  compiledBash: CompiledPermissionPatterns;
+  bashDefault: PermissionState;
   compiledSpecial: CompiledPermissionPatterns;
   compiledSkills: CompiledPermissionPatterns;
   compiledMcp: CompiledPermissionPatterns;
@@ -403,6 +407,21 @@ function compilePermissionPatternsFromSources(
   return compileWildcardPatternEntries(entries);
 }
 
+/**
+ * Convert compiled wildcard patterns into a Ruleset for use with evaluate().
+ * The returned Rule objects are the same references as the input; evaluate()
+ * uses reference equality to distinguish an explicit match from the synthetic
+ * default it returns when nothing matches.
+ */
+function compiledToRuleset(
+  surface: string,
+  patterns: CompiledPermissionPatterns,
+): Ruleset {
+  return patterns.map(
+    (p): Rule => ({ surface, pattern: p.pattern, action: p.state }),
+  );
+}
+
 function findCompiledPermissionMatch(
   patterns: CompiledPermissionPatterns,
   name: string,
@@ -701,10 +720,18 @@ export class PermissionManager {
       projectConfig.tools?.bash ||
       merged.tools?.bash ||
       merged.defaultPolicy.bash;
+    const compiledBash = compilePermissionPatternsFromSources(
+      globalConfig.bash,
+      projectConfig.bash,
+      agentConfig.bash,
+      projectAgentConfig.bash,
+    );
     const value: ResolvedPermissions = {
       globalConfig,
       agentConfig,
       merged,
+      compiledBash,
+      bashDefault,
       compiledSpecial: compilePermissionPatternsFromSources(
         globalConfig.special,
         projectConfig.special,
@@ -723,15 +750,7 @@ export class PermissionManager {
         agentConfig.mcp,
         projectAgentConfig.mcp,
       ),
-      bashFilter: new BashFilter(
-        compilePermissionPatternsFromSources(
-          globalConfig.bash,
-          projectConfig.bash,
-          agentConfig.bash,
-          projectAgentConfig.bash,
-        ),
-        bashDefault,
-      ),
+      bashFilter: new BashFilter(compiledBash, bashDefault),
     };
 
     this.resolvedPermissionsCache.set(cacheKey, { stamp, value });
@@ -804,22 +823,23 @@ export class PermissionManager {
     const {
       agentConfig: _agentConfig,
       merged,
+      compiledBash,
+      bashDefault,
       compiledSpecial,
       compiledSkills,
       compiledMcp,
-      bashFilter,
+      bashFilter: _bashFilter,
     } = this.resolvePermissions(agentName);
     const normalizedToolName = toolName.trim();
 
     if (SPECIAL_PERMISSION_KEYS.has(normalizedToolName)) {
-      const result = findCompiledPermissionMatch(
-        compiledSpecial,
-        normalizedToolName,
-      );
+      const specialRuleset = compiledToRuleset("special", compiledSpecial);
+      const rule = evaluate("special", normalizedToolName, specialRuleset);
+      const explicit = specialRuleset.includes(rule);
       return {
         toolName,
-        state: result?.state || merged.defaultPolicy.special,
-        matchedPattern: result?.matchedPattern,
+        state: explicit ? rule.action : merged.defaultPolicy.special,
+        matchedPattern: explicit ? rule.pattern : undefined,
         source: "special",
       };
     }
@@ -827,15 +847,16 @@ export class PermissionManager {
     if (normalizedToolName === "skill") {
       const skillName = toRecord(input).name;
       if (typeof skillName === "string") {
-        const result = findCompiledPermissionMatch(compiledSkills, skillName);
+        const skillRuleset = compiledToRuleset("skill", compiledSkills);
+        const rule = evaluate("skill", skillName, skillRuleset);
+        const explicit = skillRuleset.includes(rule);
         return {
           toolName,
-          state: result?.state || merged.defaultPolicy.skills,
-          matchedPattern: result?.matchedPattern,
+          state: explicit ? rule.action : merged.defaultPolicy.skills,
+          matchedPattern: explicit ? rule.pattern : undefined,
           source: "skill",
         };
       }
-
       return {
         toolName,
         state: merged.defaultPolicy.skills,
@@ -846,13 +867,14 @@ export class PermissionManager {
     if (normalizedToolName === "bash") {
       const record = toRecord(input);
       const command = typeof record.command === "string" ? record.command : "";
-      const result = bashFilter.check(command);
-
+      const bashRuleset = compiledToRuleset("bash", compiledBash);
+      const rule = evaluate("bash", command, bashRuleset);
+      const explicit = bashRuleset.includes(rule);
       return {
         toolName,
-        state: result.state,
-        command: result.command,
-        matchedPattern: result.matchedPattern,
+        state: explicit ? rule.action : bashDefault,
+        command,
+        matchedPattern: explicit ? rule.pattern : undefined,
         source: "bash",
       };
     }
@@ -868,16 +890,21 @@ export class PermissionManager {
       const fallbackTarget = mcpTargets[0] || "mcp";
       const toolLevelMcpState = merged.tools?.mcp;
 
-      const mcpMatch = findCompiledPermissionMatchForNames(
-        compiledMcp,
-        mcpTargets,
-      );
-      if (mcpMatch) {
+      const mcpRuleset = compiledToRuleset("mcp", compiledMcp);
+      let mcpExplicitMatch: { target: string; rule: Rule } | null = null;
+      for (const target of mcpTargets) {
+        const rule = evaluate("mcp", target, mcpRuleset);
+        if (mcpRuleset.includes(rule)) {
+          mcpExplicitMatch = { target, rule };
+          break;
+        }
+      }
+      if (mcpExplicitMatch) {
         return {
           toolName,
-          state: mcpMatch.state,
-          matchedPattern: mcpMatch.matchedPattern,
-          target: mcpMatch.matchedName,
+          state: mcpExplicitMatch.rule.action,
+          matchedPattern: mcpExplicitMatch.rule.pattern,
+          target: mcpExplicitMatch.target,
           source: "mcp",
         };
       }
@@ -916,19 +943,24 @@ export class PermissionManager {
       };
     }
 
+    const toolRuleset: Ruleset = Object.entries(merged.tools ?? {}).map(
+      ([name, action]) => ({ surface: "tool", pattern: name, action }),
+    );
+    const toolRule = evaluate("tool", normalizedToolName, toolRuleset);
+    const explicitTool = toolRuleset.includes(toolRule);
+
     if (BUILT_IN_TOOL_PERMISSION_NAMES.has(normalizedToolName)) {
       return {
         toolName,
-        state: merged.tools?.[normalizedToolName] || merged.defaultPolicy.tools,
+        state: explicitTool ? toolRule.action : merged.defaultPolicy.tools,
         source: "tool",
       };
     }
 
-    const explicitToolPermission = merged.tools?.[normalizedToolName];
-    if (explicitToolPermission) {
+    if (explicitTool) {
       return {
         toolName,
-        state: explicitToolPermission,
+        state: toolRule.action,
         source: "tool",
       };
     }

package/src/rule.ts

@@ -0,0 +1,58 @@
+import type { PermissionState } from "./types";
+import { wildcardMatch } from "./wildcard-matcher";
+
+/** A single permission rule — the atomic unit of policy. */
+export interface Rule {
+  /** The permission surface: "bash", "read", "mcp", "skill", "external_directory", etc. */
+  surface: string;
+  /** The match pattern: a command glob, tool name, skill name, or "*". */
+  pattern: string;
+  /** The permission decision. */
+  action: PermissionState;
+}
+
+/** An ordered list of rules. Later rules take priority (last-match-wins). */
+export type Ruleset = Rule[];
+
+const SURFACE_DEFAULTS: Record<string, PermissionState> = {
+  tools: "ask",
+  bash: "ask",
+  mcp: "ask",
+  skill: "ask",
+  special: "ask",
+};
+
+/**
+ * Returns the default action for a surface when no rules match.
+ * Defaults to "ask" for unknown surfaces (least privilege).
+ */
+export function getDefaultAction(surface: string): PermissionState {
+  return SURFACE_DEFAULTS[surface] ?? "ask";
+}
+
+/**
+ * Pure permission evaluation.
+ *
+ * Flattens all provided rulesets and returns the last rule whose surface and
+ * pattern both wildcard-match the supplied values (last-match-wins, so later
+ * rulesets / later entries have higher priority).
+ *
+ * When no rule matches, returns a synthetic rule using getDefaultAction().
+ */
+export function evaluate(
+  surface: string,
+  pattern: string,
+  ...rulesets: Ruleset[]
+): Rule {
+  const rules = rulesets.flat();
+  for (let i = rules.length - 1; i >= 0; i -= 1) {
+    const rule = rules[i];
+    if (
+      wildcardMatch(rule.surface, surface) &&
+      wildcardMatch(rule.pattern, pattern)
+    ) {
+      return rule;
+    }
+  }
+  return { surface, pattern, action: getDefaultAction(surface) };
+}

package/src/wildcard-matcher.ts

@@ -62,6 +62,15 @@ export function findCompiledWildcardMatch<TState>(
   return null;
 }
 
+/**
+ * Test whether `value` matches `pattern` using wildcard rules.
+ * `*` in the pattern matches any sequence of characters (including empty).
+ * Used by evaluate() for rule matching.
+ */
+export function wildcardMatch(pattern: string, value: string): boolean {
+  return compileWildcardPattern(pattern, null).regex.test(value);
+}
+
 export function findCompiledWildcardMatchForNames<TState>(
   patterns: readonly CompiledWildcardPattern<TState>[],
   names: readonly string[],

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

@@ -0,0 +1,274 @@
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  handleBeforeAgentStart,
+  shouldExposeTool,
+} from "../../src/handlers/before-agent-start";
+import type { HandlerDeps } from "../../src/handlers/types";
+import type { PermissionManager } from "../../src/permission-manager";
+import type { SkillPromptEntry } from "../../src/skill-prompt-sanitizer";
+
+// ── SDK stubs ──────────────────────────────────────────────────────────────
+vi.mock("@mariozechner/pi-coding-agent", async (importOriginal) => {
+  const original =
+    await importOriginal<typeof import("@mariozechner/pi-coding-agent")>();
+  return {
+    ...original,
+    isToolCallEventType: vi.fn().mockReturnValue(false),
+  };
+});
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+function makeCtx(overrides: Partial<ExtensionContext> = {}): ExtensionContext {
+  return {
+    cwd: "/test/project",
+    hasUI: true,
+    ui: {
+      setStatus: vi.fn(),
+      notify: vi.fn(),
+      select: vi.fn(),
+      input: vi.fn(),
+    },
+    sessionManager: {
+      getEntries: vi.fn().mockReturnValue([]),
+      getSessionDir: vi.fn().mockReturnValue("/sessions/test"),
+      addEntry: vi.fn(),
+    },
+    ...overrides,
+  } as unknown as ExtensionContext;
+}
+
+function makeEvent(systemPrompt = "You are an assistant.") {
+  return { systemPrompt };
+}
+
+/** Minimal PermissionManager stub for shouldExposeTool / policy-cache tests. */
+function makePm(
+  toolPermission: "allow" | "deny" | "ask" = "allow",
+): PermissionManager {
+  return {
+    getToolPermission: vi.fn().mockReturnValue(toolPermission),
+    getPolicyCacheStamp: vi.fn().mockReturnValue("stamp-1"),
+    getConfigIssues: vi.fn().mockReturnValue([]),
+    checkPermission: vi.fn().mockReturnValue({ state: "allow" }),
+  } as unknown as PermissionManager;
+}
+
+function makeDeps(overrides: Partial<HandlerDeps> = {}): HandlerDeps {
+  const pm = makePm();
+  return {
+    getPermissionManager: vi.fn().mockReturnValue(pm),
+    setPermissionManager: vi.fn(),
+    getRuntimeContext: vi.fn().mockReturnValue(null),
+    setRuntimeContext: vi.fn(),
+    getActiveSkillEntries: vi.fn().mockReturnValue([] as SkillPromptEntry[]),
+    setActiveSkillEntries: vi.fn(),
+    getLastKnownActiveAgentName: vi.fn().mockReturnValue(null),
+    setLastKnownActiveAgentName: vi.fn(),
+    getLastActiveToolsCacheKey: vi.fn().mockReturnValue(null),
+    setLastActiveToolsCacheKey: vi.fn(),
+    getLastPromptStateCacheKey: vi.fn().mockReturnValue(null),
+    setLastPromptStateCacheKey: vi.fn(),
+    sessionApprovalCache: {
+      approve: vi.fn(),
+      has: vi.fn(),
+      findMatchingPrefix: vi.fn(),
+      clear: vi.fn(),
+    } as unknown as HandlerDeps["sessionApprovalCache"],
+    createPermissionManagerForCwd: vi.fn().mockReturnValue(makePm()),
+    refreshExtensionConfig: vi.fn(),
+    notifyWarning: vi.fn(),
+    logResolvedConfigPaths: vi.fn(),
+    resolveAgentName: vi.fn().mockReturnValue(null),
+    canRequestPermissionConfirmation: vi.fn().mockReturnValue(false),
+    promptPermission: vi
+      .fn()
+      .mockResolvedValue({ approved: true, state: "approved" }),
+    createPermissionRequestId: vi.fn().mockReturnValue("test-id"),
+    startForwardedPermissionPolling: vi.fn(),
+    stopForwardedPermissionPolling: vi.fn(),
+    writeReviewLog: vi.fn(),
+    writeDebugLog: vi.fn(),
+    getAllTools: vi.fn().mockReturnValue([]),
+    setActiveTools: vi.fn(),
+    ...overrides,
+  };
+}
+
+// ── shouldExposeTool (pure helper) ─────────────────────────────────────────
+
+describe("shouldExposeTool", () => {
+  it("returns true when tool permission is allow", () => {
+    const pm = makePm("allow");
+    expect(shouldExposeTool("read", null, pm)).toBe(true);
+  });
+
+  it("returns true when tool permission is ask", () => {
+    const pm = makePm("ask");
+    expect(shouldExposeTool("bash", "agent-x", pm)).toBe(true);
+  });
+
+  it("returns false when tool permission is deny", () => {
+    const pm = makePm("deny");
+    expect(shouldExposeTool("write", null, pm)).toBe(false);
+  });
+
+  it("passes agentName through to getToolPermission", () => {
+    const pm = makePm("allow");
+    shouldExposeTool("read", "my-agent", pm);
+    expect(pm.getToolPermission).toHaveBeenCalledWith("read", "my-agent");
+  });
+
+  it("converts null agentName to undefined for getToolPermission", () => {
+    const pm = makePm("allow");
+    shouldExposeTool("read", null, pm);
+    expect(pm.getToolPermission).toHaveBeenCalledWith("read", undefined);
+  });
+});
+
+// ── handleBeforeAgentStart ─────────────────────────────────────────────────
+
+describe("handleBeforeAgentStart", () => {
+  it("refreshes extension config with ctx", async () => {
+    const ctx = makeCtx();
+    const deps = makeDeps();
+    await handleBeforeAgentStart(deps, makeEvent(), ctx);
+    expect(deps.refreshExtensionConfig).toHaveBeenCalledWith(ctx);
+  });
+
+  it("starts forwarded permission polling", async () => {
+    const ctx = makeCtx();
+    const deps = makeDeps();
+    await handleBeforeAgentStart(deps, makeEvent(), ctx);
+    expect(deps.startForwardedPermissionPolling).toHaveBeenCalledWith(ctx);
+  });
+
+  it("resolves agent name using systemPrompt", async () => {
+    const ctx = makeCtx();
+    const deps = makeDeps();
+    await handleBeforeAgentStart(
+      deps,
+      makeEvent("<active_agent name='x'>"),
+      ctx,
+    );
+    expect(deps.resolveAgentName).toHaveBeenCalledWith(
+      ctx,
+      "<active_agent name='x'>",
+    );
+  });
+
+  it("filters out denied tools from allowed list", async () => {
+    const pm = makePm("deny");
+    const deps = makeDeps({
+      getPermissionManager: vi.fn().mockReturnValue(pm),
+      getAllTools: vi
+        .fn()
+        .mockReturnValue([{ name: "write" }, { name: "read" }]),
+    });
+    // write is deny, read is deny (same pm stub — both denied)
+    await handleBeforeAgentStart(deps, makeEvent(), makeCtx());
+    expect(deps.setActiveTools).toHaveBeenCalledWith([]);
+  });
+
+  it("includes allowed and ask tools in the active list", async () => {
+    const pm = makePm("allow");
+    const deps = makeDeps({
+      getPermissionManager: vi.fn().mockReturnValue(pm),
+      getAllTools: vi
+        .fn()
+        .mockReturnValue([{ name: "read" }, { name: "write" }]),
+    });
+    await handleBeforeAgentStart(deps, makeEvent(), makeCtx());
+    expect(deps.setActiveTools).toHaveBeenCalledWith(["read", "write"]);
+  });
+
+  it("updates the active-tools cache key after applying", async () => {
+    const deps = makeDeps({
+      getAllTools: vi.fn().mockReturnValue([{ name: "read" }]),
+      getLastActiveToolsCacheKey: vi.fn().mockReturnValue(null),
+    });
+    await handleBeforeAgentStart(deps, makeEvent(), makeCtx());
+    expect(deps.setLastActiveToolsCacheKey).toHaveBeenCalledOnce();
+  });
+
+  it("skips setActiveTools when cache key is unchanged", async () => {
+    // Pre-populate the cache key to match what would be computed for ["read"]
+    const { createActiveToolsCacheKey } = await import(
+      "../../src/before-agent-start-cache"
+    );
+    const key = createActiveToolsCacheKey(["read"]);
+    const deps = makeDeps({
+      getAllTools: vi.fn().mockReturnValue([{ name: "read" }]),
+      getLastActiveToolsCacheKey: vi.fn().mockReturnValue(key),
+    });
+    await handleBeforeAgentStart(deps, makeEvent(), makeCtx());
+    expect(deps.setActiveTools).not.toHaveBeenCalled();
+  });
+
+  it("updates the prompt-state cache key and returns modified systemPrompt", async () => {
+    // Provide a systemPrompt that sanitizeAvailableToolsSection will modify:
+    // it strips denied tools from the "Available tools:" section.
+    const systemPrompt = `You are an assistant.\n\nAvailable tools:\n- read\n- write\n`;
+    const deps = makeDeps({
+      getAllTools: vi.fn().mockReturnValue([]),
+      getLastPromptStateCacheKey: vi.fn().mockReturnValue(null),
+    });
+    const result = await handleBeforeAgentStart(
+      deps,
+      makeEvent(systemPrompt),
+      makeCtx(),
+    );
+    // The prompt was modified, so systemPrompt should be returned
+    expect(result).toHaveProperty("systemPrompt");
+    expect(deps.setLastPromptStateCacheKey).toHaveBeenCalledOnce();
+  });
+
+  it("returns empty object when systemPrompt is unchanged", async () => {
+    const prompt = "No tools section here.";
+    const deps = makeDeps({
+      getAllTools: vi.fn().mockReturnValue([]),
+      getLastPromptStateCacheKey: vi.fn().mockReturnValue(null),
+    });
+    const result = await handleBeforeAgentStart(
+      deps,
+      makeEvent(prompt),
+      makeCtx(),
+    );
+    expect(result).toEqual({});
+  });
+
+  it("stores resolved skill entries on deps", async () => {
+    const deps = makeDeps({
+      getAllTools: vi.fn().mockReturnValue([]),
+      getLastPromptStateCacheKey: vi.fn().mockReturnValue(null),
+    });
+    await handleBeforeAgentStart(deps, makeEvent(), makeCtx());
+    expect(deps.setActiveSkillEntries).toHaveBeenCalledOnce();
+  });
+
+  it("returns empty object and skips prompt work when prompt cache key is unchanged", async () => {
+    const { createBeforeAgentStartPromptStateKey } = await import(
+      "../../src/before-agent-start-cache"
+    );
+    const pm = makePm("allow");
+    const ctx = makeCtx({ cwd: "/proj" });
+    const allowedTools: string[] = ["read"];
+    const key = createBeforeAgentStartPromptStateKey({
+      agentName: null,
+      cwd: "/proj",
+      permissionStamp: "stamp-1",
+      systemPrompt: "hello",
+      allowedToolNames: allowedTools,
+    });
+    const deps = makeDeps({
+      getPermissionManager: vi.fn().mockReturnValue(pm),
+      getAllTools: vi.fn().mockReturnValue([{ name: "read" }]),
+      getLastPromptStateCacheKey: vi.fn().mockReturnValue(key),
+    });
+    const result = await handleBeforeAgentStart(deps, makeEvent("hello"), ctx);
+    expect(result).toEqual({});
+    expect(deps.setActiveSkillEntries).not.toHaveBeenCalled();
+  });
+});