pi-permission-system 0.1.7 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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).
 
+## [0.2.0] - 2026-03-12
+
+### Added
+- `getToolPermission()` method to retrieve tool-level permission state without evaluating command-level rules, useful for tool injection decisions
+
+## [0.1.8] - 2026-03-10
+
+### Changed
+- Refactored pattern compilation to support multiple sources for proper global+agent pattern merging
+- Simplified `wildcard-matcher.ts` by removing unused `wildcardCount` and `literalLength` properties
+- `BashFilter` now accepts pre-compiled patterns via `BashPermissionSource` type
+- Replaced `compilePermissionPatterns` with `compilePermissionPatternsFromSources` for cleaner API
+
+### Fixed
+- Permission pattern priority now correctly implements last-match-wins hierarchy (opencode-style)
+- MCP tool-level deny no longer blocks specific MCP allow patterns
+
+### Tests
+- Updated tests to reflect last-match-wins behavior
+- Added test for specific MCP rules winning over `tools.mcp: deny`
+- Rearranged test pattern declarations for clarity
+
 ## [0.1.7] - 2026-03-10
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # 🔐 pi-permission-system
 
-[![Version](https://img.shields.io/badge/version-0.1.7-blue.svg)](package.json)
+[![Version](https://img.shields.io/badge/version-0.2.0-blue.svg)](package.json)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 Permission enforcement extension for the Pi coding agent that provides centralized, deterministic permission gates for tool, bash, MCP, skill, and special operations.
@@ -181,18 +181,13 @@ Controls built-in tools by exact name (no wildcards):
 
 ### `bash`
 
-Command patterns use `*` wildcards and match against the full command string. Patterns are sorted by specificity:
-
-1. Fewer wildcards wins
-2. Longer literal text wins  
-3. Longer overall pattern wins
+Command patterns use `*` wildcards and match against the full command string. If multiple patterns match, the **last matching rule wins**.
 
 ```jsonc
 {
   "bash": {
-    "git status": "allow",
-    "git diff": "allow",
     "git *": "ask",
+    "git status": "allow",
     "rm -rf *": "deny"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-permission-system",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "main": "./index.ts",

package/src/bash-filter.ts

@@ -7,6 +7,12 @@ import {
 
 type CompiledPattern = CompiledWildcardPattern<PermissionState>;
 
+type BashPermissionSource = BashPermissions | readonly CompiledPattern[];
+
+function isCompiledPatternList(value: BashPermissionSource): value is readonly CompiledPattern[] {
+  return Array.isArray(value);
+}
+
 export interface BashPermissionCheck {
   state: PermissionState;
   matchedPattern?: string;
@@ -17,10 +23,12 @@ export class BashFilter {
   private readonly compiledPatterns: CompiledPattern[];
 
   constructor(
-    private readonly permissions: BashPermissions,
+    permissions: BashPermissionSource,
     private readonly defaultState: PermissionState,
   ) {
-    this.compiledPatterns = compileWildcardPatterns(permissions);
+    this.compiledPatterns = isCompiledPatternList(permissions)
+      ? [...permissions]
+      : compileWildcardPatterns(permissions);
   }
 
   check(command: string): BashPermissionCheck {

package/src/common.ts

@@ -1,82 +1,82 @@
-import type { PermissionState } from "./types.js";
-
-export function toRecord(value: unknown): Record<string, unknown> {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    return {};
-  }
-
-  return value as Record<string, unknown>;
-}
-
-export function getNonEmptyString(value: unknown): string | null {
-  if (typeof value !== "string") {
-    return null;
-  }
-
-  const trimmed = value.trim();
-  return trimmed.length > 0 ? trimmed : null;
-}
-
-export function isPermissionState(value: unknown): value is PermissionState {
-  return value === "allow" || value === "deny" || value === "ask";
-}
-
-type StackNode = { indent: number; target: Record<string, unknown> };
-
-export function parseSimpleYamlMap(input: string): Record<string, unknown> {
-  const root: Record<string, unknown> = {};
-  const stack: StackNode[] = [{ indent: -1, target: root }];
-
-  const lines = input.split(/\r?\n/);
-  for (const rawLine of lines) {
-    if (!rawLine.trim() || rawLine.trimStart().startsWith("#")) {
-      continue;
-    }
-
-    const indent = rawLine.length - rawLine.trimStart().length;
-    const line = rawLine.trim();
-    const separatorIndex = line.indexOf(":");
-    if (separatorIndex <= 0) {
-      continue;
-    }
-
-    const key = line.slice(0, separatorIndex).trim().replace(/^['"]|['"]$/g, "");
-    const rawValue = line.slice(separatorIndex + 1).trim();
-
-    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
-      stack.pop();
-    }
-
-    const current = stack[stack.length - 1].target;
-
-    if (!rawValue) {
-      const child: Record<string, unknown> = {};
-      current[key] = child;
-      stack.push({ indent, target: child });
-      continue;
-    }
-
-    let scalar = rawValue;
-    if ((scalar.startsWith('"') && scalar.endsWith('"')) || (scalar.startsWith("'") && scalar.endsWith("'"))) {
-      scalar = scalar.slice(1, -1);
-    }
-
-    current[key] = scalar;
-  }
-
-  return root;
-}
-
-export function extractFrontmatter(markdown: string): string {
-  const normalized = markdown.replace(/\r\n/g, "\n");
-  if (!normalized.startsWith("---\n")) {
-    return "";
-  }
-
-  const end = normalized.indexOf("\n---", 4);
-  if (end === -1) {
-    return "";
-  }
-
-  return normalized.slice(4, end);
-}
+import type { PermissionState } from "./types.js";
+
+export function toRecord(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+
+  return value as Record<string, unknown>;
+}
+
+export function getNonEmptyString(value: unknown): string | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+export function isPermissionState(value: unknown): value is PermissionState {
+  return value === "allow" || value === "deny" || value === "ask";
+}
+
+type StackNode = { indent: number; target: Record<string, unknown> };
+
+export function parseSimpleYamlMap(input: string): Record<string, unknown> {
+  const root: Record<string, unknown> = {};
+  const stack: StackNode[] = [{ indent: -1, target: root }];
+
+  const lines = input.split(/\r?\n/);
+  for (const rawLine of lines) {
+    if (!rawLine.trim() || rawLine.trimStart().startsWith("#")) {
+      continue;
+    }
+
+    const indent = rawLine.length - rawLine.trimStart().length;
+    const line = rawLine.trim();
+    const separatorIndex = line.indexOf(":");
+    if (separatorIndex <= 0) {
+      continue;
+    }
+
+    const key = line.slice(0, separatorIndex).trim().replace(/^['"]|['"]$/g, "");
+    const rawValue = line.slice(separatorIndex + 1).trim();
+
+    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
+      stack.pop();
+    }
+
+    const current = stack[stack.length - 1].target;
+
+    if (!rawValue) {
+      const child: Record<string, unknown> = {};
+      current[key] = child;
+      stack.push({ indent, target: child });
+      continue;
+    }
+
+    let scalar = rawValue;
+    if ((scalar.startsWith('"') && scalar.endsWith('"')) || (scalar.startsWith("'") && scalar.endsWith("'"))) {
+      scalar = scalar.slice(1, -1);
+    }
+
+    current[key] = scalar;
+  }
+
+  return root;
+}
+
+export function extractFrontmatter(markdown: string): string {
+  const normalized = markdown.replace(/\r\n/g, "\n");
+  if (!normalized.startsWith("---\n")) {
+    return "";
+  }
+
+  const end = normalized.indexOf("\n---", 4);
+  if (end === -1) {
+    return "";
+  }
+
+  return normalized.slice(4, end);
+}

package/src/index.ts

@@ -844,8 +844,11 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       return false;
     }
 
-    const check = permissionManager.checkPermission(toolName, {}, agentName ?? undefined);
-    return check.state !== "deny";
+    // Use tool-level permission check for tool injection decisions
+    // This ensures that agent-specific tool deny rules (e.g., bash: deny) are respected
+    // before any command-level permissions are considered
+    const toolPermission = permissionManager.getToolPermission(toolName, agentName ?? undefined);
+    return toolPermission !== "deny";
   };
 
   pi.on("session_start", async (_event, ctx) => {

package/src/permission-manager.ts

@@ -13,7 +13,7 @@ import type {
   PermissionState,
 } from "./types.js";
 import {
-  compileWildcardPatterns,
+  compileWildcardPatternEntries,
   findCompiledWildcardMatch,
   findCompiledWildcardMatchForNames,
   type CompiledWildcardPattern,
@@ -367,14 +367,26 @@ type ResolvedPermissions = {
   bashFilter: BashFilter;
 };
 
-function compilePermissionPatterns(
-  permissions: Record<string, PermissionState> | undefined,
+function compilePermissionPatternsFromSources(
+  ...sources: Array<Record<string, PermissionState> | undefined>
 ): CompiledPermissionPatterns {
-  if (!permissions || Object.keys(permissions).length === 0) {
+  const entries: Array<readonly [string, PermissionState]> = [];
+
+  for (const source of sources) {
+    if (!source) {
+      continue;
+    }
+
+    for (const entry of Object.entries(source)) {
+      entries.push(entry);
+    }
+  }
+
+  if (entries.length === 0) {
     return [];
   }
 
-  return compileWildcardPatterns(permissions);
+  return compileWildcardPatternEntries(entries);
 }
 
 function findCompiledPermissionMatch(patterns: CompiledPermissionPatterns, name: string) {
@@ -542,10 +554,10 @@ export class PermissionManager {
       globalConfig,
       agentConfig,
       merged,
-      compiledSpecial: compilePermissionPatterns(merged.special),
-      compiledSkills: compilePermissionPatterns(merged.skills),
-      compiledMcp: compilePermissionPatterns(merged.mcp),
-      bashFilter: new BashFilter(merged.bash || {}, bashDefault),
+      compiledSpecial: compilePermissionPatternsFromSources(globalConfig.special, agentConfig.special),
+      compiledSkills: compilePermissionPatternsFromSources(globalConfig.skills, agentConfig.skills),
+      compiledMcp: compilePermissionPatternsFromSources(globalConfig.mcp, agentConfig.mcp),
+      bashFilter: new BashFilter(compilePermissionPatternsFromSources(globalConfig.bash, agentConfig.bash), bashDefault),
     };
 
     this.resolvedPermissionsCache.set(cacheKey, { stamp, value });
@@ -573,6 +585,59 @@ export class PermissionManager {
     return value;
   }
 
+  /**
+   * Get the tool-level permission state for a tool, without considering command-level rules.
+   * This is used for tool injection decisions where we need to know if a tool is allowed/denied
+   * at the tool level before checking specific command permissions.
+   *
+   * @param toolName - The name of the tool (e.g., "bash", "read", "write")
+   * @param agentName - Optional agent name to check agent-specific permissions
+   * @returns The permission state for the tool at the tool level
+   */
+  getToolPermission(toolName: string, agentName?: string): PermissionState {
+    const { merged } = this.resolvePermissions(agentName);
+    const normalizedToolName = toolName.trim();
+
+    // Handle special permission keys (doom_loop, external_directory)
+    if (SPECIAL_PERMISSION_KEYS.has(normalizedToolName)) {
+      return merged.defaultPolicy.special;
+    }
+
+    // Handle skill tool
+    if (normalizedToolName === "skill") {
+      return merged.defaultPolicy.skills;
+    }
+
+    // For bash tool, return the tool-level permission (not command-level)
+    if (normalizedToolName === "bash") {
+      return merged.tools?.bash || merged.defaultPolicy.bash;
+    }
+
+    // Handle mcp tool
+    if (normalizedToolName === "mcp") {
+      return merged.tools?.mcp || merged.defaultPolicy.mcp;
+    }
+
+    // Handle other tool permission names
+    if (TOOL_PERMISSION_NAMES.has(normalizedToolName)) {
+      return merged.tools?.[normalizedToolName] || merged.defaultPolicy.tools;
+    }
+
+    // For MCP tools (qualified names like "server_tool"), check mcp permissions
+    if (normalizedToolName.includes("_")) {
+      const mcpMatch = findCompiledPermissionMatch(
+        compilePermissionPatternsFromSources(this.loadGlobalConfig().mcp, this.loadAgentPermissions(agentName).mcp),
+        normalizedToolName
+      );
+      if (mcpMatch) {
+        return mcpMatch.state;
+      }
+    }
+
+    // Default to the tools default policy
+    return merged.defaultPolicy.tools;
+  }
+
   checkPermission(toolName: string, input: unknown, agentName?: string): PermissionCheckResult {
     const { agentConfig, merged, compiledSpecial, compiledSkills, compiledMcp, bashFilter } = this.resolvePermissions(agentName);
     const normalizedToolName = toolName.trim();
@@ -609,19 +674,6 @@ export class PermissionManager {
     if (normalizedToolName === "bash") {
       const record = toRecord(input);
       const command = typeof record.command === "string" ? record.command : "";
-
-      const agentBashToolOverride = agentConfig.tools?.bash;
-      const hasAgentBashPatterns = Object.keys(agentConfig.bash || {}).length > 0;
-
-      if (agentBashToolOverride && !hasAgentBashPatterns) {
-        return {
-          toolName,
-          state: agentBashToolOverride,
-          command,
-          source: "bash",
-        };
-      }
-
       const result = bashFilter.check(command);
 
       return {
@@ -638,15 +690,6 @@ export class PermissionManager {
       const fallbackTarget = mcpTargets[0] || "mcp";
       const toolLevelMcpState = merged.tools?.mcp;
 
-      if (toolLevelMcpState === "deny") {
-        return {
-          toolName,
-          state: "deny",
-          target: fallbackTarget,
-          source: "tool",
-        };
-      }
-
       const mcpMatch = findCompiledPermissionMatchForNames(compiledMcp, mcpTargets);
       if (mcpMatch) {
         return {

package/src/test.ts

@@ -47,13 +47,13 @@ function runTest(name: string, testFn: () => void): void {
   console.log(`[PASS] ${name}`);
 }
 
-runTest("BashFilter wildcard and specificity matching", () => {
+runTest("BashFilter uses opencode-style last-match hierarchy", () => {
   const filter = new BashFilter(
     {
-      "git status": "allow",
-      "git status *": "ask",
-      "git *": "deny",
       "*": "ask",
+      "git *": "deny",
+      "git status *": "ask",
+      "git status": "allow",
     },
     "deny",
   );
@@ -98,7 +98,7 @@ runTest("PermissionManager built-in permission checking", () => {
   }
 });
 
-runTest("Agent-specific bash override", () => {
+runTest("Bash patterns stay higher priority than tool-level bash fallback", () => {
   const { manager, cleanup } = createManager(
     {
       defaultPolicy: {
@@ -108,28 +108,31 @@ runTest("Agent-specific bash override", () => {
         skills: "ask",
         special: "ask",
       },
-      tools: {
-        bash: "allow",
-      },
       bash: {
-        "echo *": "allow",
+        "rm -rf *": "deny",
       },
     },
     {
       reviewer: `---
 name: reviewer
 permission:
-  bash: deny
+  tools:
+    bash: allow
 ---
 `,
     },
   );
 
   try {
-    const result = manager.checkPermission("bash", { command: "echo hello" }, "reviewer");
-    assert.equal(result.state, "deny");
-    assert.equal(result.source, "bash");
-    assert.equal(result.matchedPattern, undefined);
+    const denied = manager.checkPermission("bash", { command: "rm -rf build" }, "reviewer");
+    assert.equal(denied.state, "deny");
+    assert.equal(denied.source, "bash");
+    assert.equal(denied.matchedPattern, "rm -rf *");
+
+    const fallback = manager.checkPermission("bash", { command: "echo hello" }, "reviewer");
+    assert.equal(fallback.state, "allow");
+    assert.equal(fallback.source, "bash");
+    assert.equal(fallback.matchedPattern, undefined);
   } finally {
     cleanup();
   }
@@ -145,9 +148,9 @@ runTest("MCP wildcard matching", () => {
       special: "ask",
     },
     mcp: {
+      "*": "deny",
       "subagent_*": "ask",
       "subagent_query-*": "allow",
-      "*": "deny",
     },
   });
 
@@ -179,9 +182,9 @@ runTest("Skill permission matching", () => {
       special: "ask",
     },
     skills: {
-      "requesting-code-review": "allow",
-      "web-*": "deny",
       "*": "ask",
+      "web-*": "deny",
+      "requesting-code-review": "allow",
     },
   });
 
@@ -214,8 +217,8 @@ runTest("MCP proxy tool infers server-prefixed aliases from configured server na
         special: "ask",
       },
       mcp: {
-        exa_get_code_context_exa: "allow",
         "exa_*": "deny",
+        exa_get_code_context_exa: "allow",
       },
     },
     {},
@@ -246,8 +249,8 @@ runTest("MCP describe mode normalizes qualified tool names without duplicating s
         special: "ask",
       },
       mcp: {
-        exa_web_search_exa: "allow",
         "exa_*": "deny",
+        exa_web_search_exa: "allow",
       },
     },
     {},
@@ -365,6 +368,49 @@ permission:
   }
 });
 
+runTest("specific MCP rules still win when tools.mcp is deny", () => {
+  const { manager, cleanup } = createManager(
+    {
+      defaultPolicy: {
+        tools: "ask",
+        bash: "ask",
+        mcp: "ask",
+        skills: "ask",
+        special: "ask",
+      },
+    },
+    {
+      reviewer: `---
+name: reviewer
+permission:
+  tools:
+    mcp: deny
+  mcp:
+    exa_web_search_exa: allow
+---
+`,
+    },
+    {
+      mcpServerNames: ["exa"],
+    },
+  );
+
+  try {
+    const allowed = manager.checkPermission("mcp", { tool: "web_search_exa" }, "reviewer");
+    assert.equal(allowed.state, "allow");
+    assert.equal(allowed.source, "mcp");
+    assert.equal(allowed.matchedPattern, "exa_web_search_exa");
+    assert.equal(allowed.target, "exa_web_search_exa");
+
+    const fallback = manager.checkPermission("mcp", { tool: "other_exa" }, "reviewer");
+    assert.equal(fallback.state, "deny");
+    assert.equal(fallback.source, "tool");
+    assert.equal(fallback.target, "exa_other_exa");
+  } finally {
+    cleanup();
+  }
+});
+
 runTest("partial agent defaultPolicy overrides preserve global defaults", () => {
   const { manager, cleanup } = createManager(
     {
@@ -484,4 +530,70 @@ runTest("Tool registry blocks unregistered tools and handles aliases", () => {
   assert.equal(missingNameCheck.status, "missing-tool-name");
 });
 
+runTest("getToolPermission returns tool-level deny for agent with bash: deny", () => {
+  const { manager, cleanup } = createManager(
+    {
+      defaultPolicy: {
+        tools: "ask",
+        bash: "ask",
+        mcp: "ask",
+        skills: "ask",
+        special: "ask",
+      },
+    },
+    {
+      orchestrator: `---
+name: orchestrator
+permission:
+  tools:
+    bash: deny
+    read: deny
+    task: allow
+---
+`,
+    },
+  );
+
+  try {
+    // Tool-level check for bash should return deny for orchestrator
+    const bashPermission = manager.getToolPermission("bash", "orchestrator");
+    assert.equal(bashPermission, "deny");
+
+    // Tool-level check for task should return allow
+    const taskPermission = manager.getToolPermission("task", "orchestrator");
+    assert.equal(taskPermission, "allow");
+
+    // Tool-level check for read should return deny
+    const readPermission = manager.getToolPermission("read", "orchestrator");
+    assert.equal(readPermission, "deny");
+
+    // When no agent specified, should fall back to default policy
+    const defaultBashPermission = manager.getToolPermission("bash");
+    assert.equal(defaultBashPermission, "ask");
+
+    // Global config tools setting should work
+    const { manager: manager2, cleanup: cleanup2 } = createManager({
+      defaultPolicy: {
+        tools: "deny",
+        bash: "ask",
+        mcp: "ask",
+        skills: "ask",
+        special: "ask",
+      },
+      tools: {
+        bash: "allow",
+      },
+    });
+
+    try {
+      const globalBashPermission = manager2.getToolPermission("bash");
+      assert.equal(globalBashPermission, "allow");
+    } finally {
+      cleanup2();
+    }
+  } finally {
+    cleanup();
+  }
+});
+
 console.log("All permission system tests passed.");

package/src/wildcard-matcher.ts

@@ -2,8 +2,6 @@ export type CompiledWildcardPattern<TState> = {
   pattern: string;
   state: TState;
   regex: RegExp;
-  wildcardCount: number;
-  literalLength: number;
 };
 
 export type WildcardPatternMatch<TState> = {
@@ -26,39 +24,27 @@ export function compileWildcardPattern<TState>(pattern: string, state: TState):
     pattern,
     state,
     regex: new RegExp(`^${escaped}$`),
-    wildcardCount: (pattern.match(/\*/g) || []).length,
-    literalLength: pattern.replace(/\*/g, "").length,
   };
 }
 
-function compareCompiledPatterns<TState>(
-  left: CompiledWildcardPattern<TState>,
-  right: CompiledWildcardPattern<TState>,
-): number {
-  if (left.wildcardCount !== right.wildcardCount) {
-    return left.wildcardCount - right.wildcardCount;
-  }
-
-  if (left.literalLength !== right.literalLength) {
-    return right.literalLength - left.literalLength;
-  }
-
-  return right.pattern.length - left.pattern.length;
+export function compileWildcardPatternEntries<TState>(
+  entries: Iterable<readonly [string, TState]>,
+): CompiledWildcardPattern<TState>[] {
+  return Array.from(entries, ([pattern, state]) => compileWildcardPattern(pattern, state));
 }
 
 export function compileWildcardPatterns<TState>(
   patterns: Record<string, TState>,
 ): CompiledWildcardPattern<TState>[] {
-  return Object.entries(patterns)
-    .map(([pattern, state]) => compileWildcardPattern(pattern, state))
-    .sort(compareCompiledPatterns);
+  return compileWildcardPatternEntries(Object.entries(patterns));
 }
 
 export function findCompiledWildcardMatch<TState>(
   patterns: readonly CompiledWildcardPattern<TState>[],
   name: string,
 ): WildcardPatternMatch<TState> | null {
-  for (const pattern of patterns) {
+  for (let index = patterns.length - 1; index >= 0; index -= 1) {
+    const pattern = patterns[index];
     if (pattern.regex.test(name)) {
       return {
         state: pattern.state,