@gotgenes/pi-permission-system 3.4.0 → 3.6.0

package/CHANGELOG.md

@@ -5,6 +5,43 @@ 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)
+
+
+### Features
+
+* deprecate doom_loop special permission key ([68e70e7](https://github.com/gotgenes/pi-permission-system/commit/68e70e71b68e5a76a071ef4613da356a91080158))
+* remove doom_loop from type union and config-loader ([bf2f288](https://github.com/gotgenes/pi-permission-system/commit/bf2f2886a800187337e82954e812e6d05e9bd451))
+
+
+### Documentation
+
+* add architecture documents for current and target permission model ([aab1ac5](https://github.com/gotgenes/pi-permission-system/commit/aab1ac50c4478d2e393c2a796bf6fcc4ec606f79))
+* plan doom_loop deprecation ([#54](https://github.com/gotgenes/pi-permission-system/issues/54)) ([2e730f5](https://github.com/gotgenes/pi-permission-system/commit/2e730f52189dd2996ebbe90dd5d2b3206a45d1f6))
+* plan handler extraction from piPermissionSystemExtension ([#42](https://github.com/gotgenes/pi-permission-system/issues/42)) ([6ecd419](https://github.com/gotgenes/pi-permission-system/commit/6ecd4190fb9a60009eb695b4998ab8a1d1419139))
+* remove doom_loop from schema, example, and README ([7f422e0](https://github.com/gotgenes/pi-permission-system/commit/7f422e086f0052e0d9449dbd0122c57b923b053d))
+* **retro:** add retro notes for issue [#45](https://github.com/gotgenes/pi-permission-system/issues/45) ([14c5559](https://github.com/gotgenes/pi-permission-system/commit/14c55595c5abfaa51f8ec83369452db5f457836c))
+
 ## [3.4.0](https://github.com/gotgenes/pi-permission-system/compare/v3.3.0...v3.4.0) (2026-05-03)
 
 

package/README.md

@@ -137,7 +137,7 @@ The config file combines runtime knobs and permission policy in one object:
   "bash": { "git status": "allow", "git *": "ask" },
   "mcp": { "mcp_status": "allow" },
   "skills": { "*": "ask" },
-  "special": { "doom_loop": "deny", "external_directory": "ask" }
+  "special": { "external_directory": "ask" }
 }
 ```
 
@@ -353,13 +353,11 @@ Reserved permission checks:
 
 | Key                  | Description                                                                                                                                                                   |
 | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `doom_loop`          | Controls doom loop detection behavior                                                                                                                                         |
 | `external_directory` | Enforces ask/allow/deny decisions for path-bearing tools and bash commands that reference paths outside the active working directory                                          |
 
 ```jsonc
 {
   "special": {
-    "doom_loop": "deny",
     "external_directory": "ask",
   },
 }

package/config/config.example.json

@@ -27,7 +27,6 @@
     "*": "ask"
   },
   "special": {
-    "doom_loop": "deny",
     "external_directory": "ask"
   }
 }

package/package.json

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

package/schemas/permissions.schema.json

@@ -60,8 +60,8 @@
           "default": "ask"
         },
         "special": {
-          "description": "Default permission for special checks (doom_loop, external_directory) when no explicit rule matches.",
-          "markdownDescription": "Default permission for special checks (`doom_loop`, `external_directory`) when no explicit rule matches.",
+          "description": "Default permission for special checks (external_directory) when no explicit rule matches.",
+          "markdownDescription": "Default permission for special checks (`external_directory`) when no explicit rule matches.",
           "$ref": "#/$defs/permissionState",
           "default": "ask"
         }
@@ -122,10 +122,6 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "doom_loop": {
-          "description": "Controls doom loop detection behavior.",
-          "$ref": "#/$defs/permissionState"
-        },
         "external_directory": {
           "description": "Enforces permission checks for path-bearing file tools (read, write, edit, find, grep, ls) when they target paths outside the active working directory.",
           "markdownDescription": "Enforces permission checks for path-bearing file tools (`read`, `write`, `edit`, `find`, `grep`, `ls`) when they target paths outside the active working directory.\n\nEvaluated **before** the normal tool permission check — so `tools.read: \"allow\"` can permit ordinary reads while `external_directory: \"ask\"` still requires confirmation for paths outside `cwd`.",

package/src/config-loader.ts

@@ -36,6 +36,7 @@ export interface UnifiedConfigLoadResult {
 }
 
 const DEPRECATED_SPECIAL_KEYS: ReadonlySet<string> = new Set([
+  "doom_loop",
   "tool_call_limit",
 ]);
 
@@ -49,7 +50,7 @@ const BUILT_IN_TOOL_PERMISSION_NAMES = new Set([
   "ls",
 ]);
 
-const SPECIAL_PERMISSION_KEYS = new Set(["doom_loop", "external_directory"]);
+const SPECIAL_PERMISSION_KEYS = new Set(["external_directory"]);
 
 export function stripJsonComments(input: string): string {
   let output = "";

package/src/extension-config.ts

@@ -69,7 +69,6 @@ const PERMISSION_POLICY_KEYS: ReadonlySet<string> = new Set([
   "skills",
   "special",
   "external_directory",
-  "doom_loop",
 ]);
 
 export function detectMisplacedPermissionKeys(

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,
@@ -46,7 +48,7 @@ const BUILT_IN_TOOL_PERMISSION_NAMES = new Set([
   "find",
   "ls",
 ]);
-const SPECIAL_PERMISSION_KEYS = new Set(["doom_loop", "external_directory"]);
+const SPECIAL_PERMISSION_KEYS = new Set(["external_directory"]);
 const MCP_BASELINE_TARGETS = new Set([
   "mcp_status",
   "mcp_list",
@@ -156,6 +158,7 @@ function getConfiguredMcpServerNamesFromPaths(
 }
 
 const DEPRECATED_SPECIAL_KEYS: ReadonlySet<string> = new Set([
+  "doom_loop",
   "tool_call_limit",
 ]);
 
@@ -374,6 +377,8 @@ type ResolvedPermissions = {
   globalConfig: GlobalPermissionConfig;
   agentConfig: AgentPermissions;
   merged: GlobalPermissionConfig;
+  compiledBash: CompiledPermissionPatterns;
+  bashDefault: PermissionState;
   compiledSpecial: CompiledPermissionPatterns;
   compiledSkills: CompiledPermissionPatterns;
   compiledMcp: CompiledPermissionPatterns;
@@ -402,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,
@@ -700,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,
@@ -722,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 });
@@ -803,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",
       };
     }
@@ -826,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,
@@ -845,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",
       };
     }
@@ -867,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",
         };
       }
@@ -915,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/types.ts

@@ -15,7 +15,7 @@ export type BashPermissions = Record<string, PermissionState>;
 
 export type SkillPermissions = Record<string, PermissionState>;
 
-export type SpecialPermissionName = "doom_loop" | "external_directory";
+export type SpecialPermissionName = "external_directory";
 
 export type SpecialPermissions = Record<string, PermissionState>;
 

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

@@ -133,7 +133,7 @@ describe("loadUnifiedConfig", () => {
     expect(result.config.bash).toEqual({ "git *": "ask" });
   });
 
-  it("collects deprecated special key issues", () => {
+  it("collects deprecated special key issues (doom_loop and tool_call_limit)", () => {
     const configPath = join(tempDir, "config.json");
     writeFileSync(
       configPath,
@@ -143,9 +143,10 @@ describe("loadUnifiedConfig", () => {
     );
 
     const result = loadUnifiedConfig(configPath);
-    expect(result.issues).toHaveLength(1);
-    expect(result.issues[0]).toContain("tool_call_limit");
-    expect(result.config.special).toEqual({ doom_loop: "deny" });
+    expect(result.issues).toHaveLength(2);
+    expect(result.issues.some((i) => i.includes("doom_loop"))).toBe(true);
+    expect(result.issues.some((i) => i.includes("tool_call_limit"))).toBe(true);
+    expect(result.config.special).toBeUndefined();
   });
 });
 

package/tests/extension-config.test.ts

@@ -42,7 +42,6 @@ describe("detectMisplacedPermissionKeys", () => {
       skills: {},
       special: {},
       external_directory: {},
-      doom_loop: {},
     });
     expect(result).toEqual([
       "defaultPolicy",
@@ -52,10 +51,16 @@ describe("detectMisplacedPermissionKeys", () => {
       "skills",
       "special",
       "external_directory",
-      "doom_loop",
     ]);
   });
 
+  it("does not detect doom_loop as a misplaced permission key (deprecated)", () => {
+    const result = detectMisplacedPermissionKeys({
+      doom_loop: {},
+    });
+    expect(result).toEqual([]);
+  });
+
   it("ignores unknown keys that are not permission-rule keys", () => {
     const result = detectMisplacedPermissionKeys({
       debugLog: true,

package/tests/permission-system.test.ts

@@ -2115,7 +2115,7 @@ permission:
   }
 });
 
-test("external_directory permission is independent of doom_loop in the same special config", () => {
+test("external_directory permission is unaffected when doom_loop key is present in config (deprecated and ignored)", () => {
   const { manager, cleanup } = createManager({
     defaultPolicy: {
       tools: "allow",
@@ -2131,10 +2131,12 @@ test("external_directory permission is independent of doom_loop in the same spec
   });
 
   try {
+    // doom_loop is deprecated and stripped — falls through to defaultPolicy.tools
     const doomResult = manager.checkPermission("doom_loop", {});
-    assert.equal(doomResult.state, "deny");
-    assert.equal(doomResult.matchedPattern, "doom_loop");
+    assert.equal(doomResult.state, "allow"); // defaultPolicy.tools, not the stripped doom_loop: "deny"
+    assert.equal(doomResult.matchedPattern, undefined);
 
+    // external_directory still resolves from its own entry
     const extResult = manager.checkPermission("external_directory", {});
     assert.equal(extResult.state, "allow");
     assert.equal(extResult.matchedPattern, "external_directory");
@@ -2583,12 +2585,22 @@ test("normalizeRawPermission emits deprecation issue for special.tool_call_limit
   assert.equal(result.permissions.special?.tool_call_limit, undefined);
 });
 
-test("normalizeRawPermission emits no issues for valid special keys", () => {
+test("normalizeRawPermission emits deprecation issue for special.doom_loop (string)", () => {
+  const result = normalizeRawPermission({
+    special: { doom_loop: "ask" },
+  });
+  assert.equal(result.configIssues.length, 1);
+  assert.ok(result.configIssues[0].includes("doom_loop"));
+  assert.equal(result.permissions.special?.doom_loop, undefined);
+});
+
+test("normalizeRawPermission emits deprecation issue for special.doom_loop (deny)", () => {
   const result = normalizeRawPermission({
     special: { doom_loop: "deny" },
   });
-  assert.equal(result.configIssues.length, 0);
-  assert.equal(result.permissions.special?.doom_loop, "deny");
+  assert.equal(result.configIssues.length, 1);
+  assert.ok(result.configIssues[0].includes("doom_loop"));
+  assert.equal(result.permissions.special?.doom_loop, undefined);
 });
 
 test("normalizeRawPermission emits no issues when special is absent", () => {
@@ -2609,7 +2621,7 @@ test("PermissionManager.getConfigIssues returns deprecation for tool_call_limit
     bash: {},
     mcp: {},
     skills: {},
-    special: { tool_call_limit: "allow" as PermissionState, doom_loop: "deny" },
+    special: { tool_call_limit: "allow" as PermissionState },
   };
   const { manager, cleanup } = createManager(config);
   try {
@@ -2634,7 +2646,7 @@ test("PermissionManager.getConfigIssues returns empty array for clean config", (
     bash: {},
     mcp: {},
     skills: {},
-    special: { doom_loop: "deny" },
+    special: { external_directory: "ask" },
   };
   const { manager, cleanup } = createManager(config);
   try {
@@ -2645,6 +2657,58 @@ test("PermissionManager.getConfigIssues returns empty array for clean config", (
   }
 });
 
+// --- doom_loop config-loader deprecation tests (#54) ---
+
+test("PermissionManager.getConfigIssues returns deprecation for doom_loop in global config", () => {
+  const config: GlobalPermissionConfig = {
+    defaultPolicy: {
+      tools: "ask",
+      bash: "ask",
+      mcp: "ask",
+      skills: "ask",
+      special: "ask",
+    },
+    tools: {},
+    bash: {},
+    mcp: {},
+    skills: {},
+    special: { doom_loop: "deny" },
+  };
+  const { manager, cleanup } = createManager(config);
+  try {
+    const issues = manager.getConfigIssues();
+    assert.equal(issues.length, 1);
+    assert.ok(issues[0].includes("doom_loop"));
+  } finally {
+    cleanup();
+  }
+});
+
+test("checkPermission doom_loop falls through to defaultPolicy.tools when stripped by config-loader", () => {
+  const { manager, cleanup } = createManager({
+    defaultPolicy: {
+      tools: "allow",
+      bash: "ask",
+      mcp: "ask",
+      skills: "ask",
+      special: "deny",
+    },
+    tools: {},
+    bash: {},
+    mcp: {},
+    skills: {},
+    special: { doom_loop: "ask" },
+  });
+  try {
+    const result = manager.checkPermission("doom_loop", {});
+    // doom_loop stripped by config-loader — falls through to defaultPolicy.tools
+    assert.equal(result.state, "allow");
+    assert.equal(result.matchedPattern, undefined);
+  } finally {
+    cleanup();
+  }
+});
+
 // --- session-scoped approval tests (#45) ---
 
 test("session approval: first prompt with 'Yes, for this session' skips subsequent prompts under same prefix", async () => {

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