@gotgenes/pi-permission-system 3.5.0 → 3.6.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.6.0](https://github.com/gotgenes/pi-permission-system/compare/v3.5.0...v3.6.0) (2026-05-03)
+
+
+### Features
+
+* add Rule, Ruleset, getDefaultAction, and evaluate() in src/rule.ts ([482e00a](https://github.com/gotgenes/pi-permission-system/commit/482e00a04289f46f14c4b94486fbd98232159d66))
+* add wildcardMatch convenience function to wildcard-matcher ([fa65219](https://github.com/gotgenes/pi-permission-system/commit/fa6521954a71ab146f14b87dc0723434a6dfd5ae))
+
+
+### Bug Fixes
+
+* replace findLast with manual backwards loop in evaluate() ([1911f37](https://github.com/gotgenes/pi-permission-system/commit/1911f37dd6074d926f959aeefa3d795b29d1681c))
+
+
+### Documentation
+
+* mark [#55](https://github.com/gotgenes/pi-permission-system/issues/55) complete in target architecture refactoring sequence ([0c87289](https://github.com/gotgenes/pi-permission-system/commit/0c87289d053a7f8c33aaa21a515db28d097a1925))
+* plan extract pure evaluate() function ([#55](https://github.com/gotgenes/pi-permission-system/issues/55)) ([fd11860](https://github.com/gotgenes/pi-permission-system/commit/fd118606ba90af83d2d9eb5e752e76353beaf0ba))
+* **retro:** add retro notes for issue [#54](https://github.com/gotgenes/pi-permission-system/issues/54) ([d7c5e8a](https://github.com/gotgenes/pi-permission-system/commit/d7c5e8aaae31fa658bcfb235547662bf226e6855))
+
 ## [3.5.0](https://github.com/gotgenes/pi-permission-system/compare/v3.4.0...v3.5.0) (2026-05-03)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "files": [

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

@@ -0,0 +1,158 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+import type { Rule, Ruleset } from "../src/rule";
+import { evaluate, getDefaultAction } from "../src/rule";
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("getDefaultAction", () => {
+  test("returns 'ask' for bash surface", () => {
+    expect(getDefaultAction("bash")).toBe("ask");
+  });
+
+  test("returns 'ask' for mcp surface", () => {
+    expect(getDefaultAction("mcp")).toBe("ask");
+  });
+
+  test("returns 'ask' for skill surface", () => {
+    expect(getDefaultAction("skill")).toBe("ask");
+  });
+
+  test("returns 'ask' for special surface", () => {
+    expect(getDefaultAction("special")).toBe("ask");
+  });
+
+  test("returns 'ask' for tools surface", () => {
+    expect(getDefaultAction("tools")).toBe("ask");
+  });
+
+  test("returns 'ask' for unknown surface (least privilege)", () => {
+    expect(getDefaultAction("unknown_surface")).toBe("ask");
+    expect(getDefaultAction("")).toBe("ask");
+    expect(getDefaultAction("external_directory")).toBe("ask");
+  });
+});
+
+describe("evaluate", () => {
+  const allowBashGit: Rule = {
+    surface: "bash",
+    pattern: "git *",
+    action: "allow",
+  };
+  const denyBashGitPush: Rule = {
+    surface: "bash",
+    pattern: "git push *",
+    action: "deny",
+  };
+  const allowRead: Rule = { surface: "read", pattern: "*", action: "allow" };
+  const askMcp: Rule = { surface: "mcp", pattern: "*", action: "ask" };
+  const allowSkillLibrarian: Rule = {
+    surface: "skill",
+    pattern: "librarian",
+    action: "allow",
+  };
+  const askSpecialExtDir: Rule = {
+    surface: "special",
+    pattern: "external_directory",
+    action: "ask",
+  };
+
+  test("returns matching rule when a rule matches", () => {
+    const ruleset: Ruleset = [allowBashGit];
+    const result = evaluate("bash", "git status", ruleset);
+    expect(result).toEqual(allowBashGit);
+  });
+
+  test("returns synthetic rule with default action when no rules match", () => {
+    const result = evaluate("bash", "npm install", [allowBashGit]);
+    expect(result.surface).toBe("bash");
+    expect(result.pattern).toBe("npm install");
+    expect(result.action).toBe("ask"); // getDefaultAction("bash")
+  });
+
+  test("returns synthetic rule for empty ruleset", () => {
+    const result = evaluate("mcp", "exa_search", []);
+    expect(result.surface).toBe("mcp");
+    expect(result.pattern).toBe("exa_search");
+    expect(result.action).toBe("ask");
+  });
+
+  test("matches rules for all permission surfaces", () => {
+    expect(evaluate("read", "src/foo.ts", [allowRead]).action).toBe("allow");
+    expect(evaluate("mcp", "exa_search", [askMcp]).action).toBe("ask");
+    expect(evaluate("skill", "librarian", [allowSkillLibrarian]).action).toBe(
+      "allow",
+    );
+    expect(
+      evaluate("special", "external_directory", [askSpecialExtDir]).action,
+    ).toBe("ask");
+  });
+
+  test("last-match-wins: later conflicting rule overrides earlier", () => {
+    const ruleset: Ruleset = [allowBashGit, denyBashGitPush];
+    const result = evaluate("bash", "git push origin main", ruleset);
+    expect(result).toEqual(denyBashGitPush);
+  });
+
+  test("last-match-wins: broad deny followed by specific allow", () => {
+    const denyAll: Rule = { surface: "bash", pattern: "*", action: "deny" };
+    const allowStatus: Rule = {
+      surface: "bash",
+      pattern: "git status",
+      action: "allow",
+    };
+    const result = evaluate("bash", "git status", [denyAll, allowStatus]);
+    expect(result).toEqual(allowStatus);
+  });
+
+  test("wildcard surface in rule matches any surface value", () => {
+    const universalAllow: Rule = {
+      surface: "*",
+      pattern: "*",
+      action: "allow",
+    };
+    expect(evaluate("bash", "anything", [universalAllow]).action).toBe("allow");
+    expect(evaluate("mcp", "something", [universalAllow]).action).toBe("allow");
+    expect(evaluate("skill", "librarian", [universalAllow]).action).toBe(
+      "allow",
+    );
+  });
+
+  test("specific surface rule does not match a different surface", () => {
+    const ruleset: Ruleset = [allowBashGit];
+    // bash rule should not match mcp surface
+    const result = evaluate("mcp", "git status", ruleset);
+    expect(result.action).toBe("ask"); // falls back to default
+  });
+
+  test("multiple rulesets: rules from later rulesets take priority", () => {
+    const globalRules: Ruleset = [
+      { surface: "bash", pattern: "git *", action: "ask" },
+    ];
+    const agentRules: Ruleset = [
+      { surface: "bash", pattern: "git *", action: "allow" },
+    ];
+    const result = evaluate("bash", "git status", globalRules, agentRules);
+    expect(result.action).toBe("allow"); // agent rule wins
+  });
+
+  test("multiple rulesets: earlier rulesets used when later rulesets have no match", () => {
+    const globalRules: Ruleset = [
+      { surface: "bash", pattern: "git *", action: "allow" },
+    ];
+    const agentRules: Ruleset = [
+      { surface: "bash", pattern: "npm *", action: "deny" },
+    ];
+    // git status matches global but not agent rule
+    const result = evaluate("bash", "git status", globalRules, agentRules);
+    expect(result.action).toBe("allow"); // global rule is the last match for this pattern
+  });
+
+  test("no rulesets at all returns synthetic default", () => {
+    const result = evaluate("bash", "git status");
+    expect(result.surface).toBe("bash");
+    expect(result.pattern).toBe("git status");
+    expect(result.action).toBe("ask");
+  });
+});

package/tests/wildcard-matcher.test.ts

@@ -5,6 +5,7 @@ import {
   compileWildcardPatternEntries,
   findCompiledWildcardMatch,
   findCompiledWildcardMatchForNames,
+  wildcardMatch,
 } from "../src/wildcard-matcher";
 
 afterEach(() => {
@@ -178,3 +179,41 @@ describe("findCompiledWildcardMatchForNames", () => {
     expect(compiled.regex.test("echo hello")).toBe(false);
   });
 });
+
+describe("wildcardMatch", () => {
+  test("'*' pattern matches any value", () => {
+    expect(wildcardMatch("*", "anything")).toBe(true);
+    expect(wildcardMatch("*", "")).toBe(true);
+    expect(wildcardMatch("*", "bash")).toBe(true);
+  });
+
+  test("exact pattern matches identical value", () => {
+    expect(wildcardMatch("read", "read")).toBe(true);
+    expect(wildcardMatch("external_directory", "external_directory")).toBe(
+      true,
+    );
+  });
+
+  test("exact pattern does not match a different value", () => {
+    expect(wildcardMatch("read", "write")).toBe(false);
+    expect(wildcardMatch("read", "readonly")).toBe(false);
+    expect(wildcardMatch("read", "read ")).toBe(false);
+  });
+
+  test("glob pattern matches with wildcard", () => {
+    expect(wildcardMatch("git *", "git status")).toBe(true);
+    expect(wildcardMatch("git *", "git push origin main")).toBe(true);
+    expect(wildcardMatch("git *", "npm install")).toBe(false);
+  });
+
+  test("glob with no trailing space matches longer string", () => {
+    expect(wildcardMatch("git*", "git")).toBe(true);
+    expect(wildcardMatch("git*", "git status")).toBe(true);
+    expect(wildcardMatch("git*", "npm")).toBe(false);
+  });
+
+  test("regex special characters in pattern are treated as literals", () => {
+    expect(wildcardMatch("tool.name", "tool.name")).toBe(true);
+    expect(wildcardMatch("tool.name", "toolXname")).toBe(false);
+  });
+});