pi-permission-system 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -5,7 +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).
 
-## [Unreleased]
+## [0.1.7] - 2026-03-10
+
+### Added
+- `src/common.ts` — Shared utility module with `toRecord()`, `getNonEmptyString()`, `isPermissionState()`, `parseSimpleYamlMap()`, `extractFrontmatter()`
+- `src/wildcard-matcher.ts` — Wildcard pattern compilation and matching with specificity sorting
+- File stamp caching in `PermissionManager` for improved performance
+- `tools.mcp` fallback permission for MCP operations
+- MCP tool permission targets now inferred from configured server names in `mcp.json`
+
+### Changed
+- Refactored `bash-filter.ts` to use shared `wildcard-matcher.ts` module
+- Refactored `index.ts` to use shared `common.ts` utilities
+- Refactored `permission-manager.ts` to use shared modules and caching
+- Pre-compiled wildcard patterns are now reused across permission checks
+- Updated README architecture documentation to reflect new module organization
+
+### Tests
+- Added tests for MCP proxy tool inferring server-prefixed aliases from configured server names
+- Added tests for `tools.mcp` fallback behavior
+- Added tests for `task` using tool permissions instead of MCP fallback
 
 ## [0.1.6] - 2026-03-09
 

package/README.md

@@ -1,6 +1,6 @@
 # 🔐 pi-permission-system
 
-[![Version](https://img.shields.io/badge/version-0.1.6-blue.svg)](package.json)
+[![Version](https://img.shields.io/badge/version-0.1.7-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.
@@ -111,9 +111,13 @@ permission:
   tools:
     read: allow
     write: deny
+    mcp: allow
   bash:
     git status: allow
     git *: ask
+  mcp:
+    chrome_devtools_*: deny
+    exa_*: allow
   skills:
     "*": ask
 ---
@@ -121,6 +125,8 @@ permission:
 
 **Precedence:** Agent frontmatter overrides global config (shallow-merged per section).
 
+**MCP behavior:** `permission.tools.mcp` is the coarse entry/fallback permission for the built-in `mcp` tool. More specific `permission.mcp` target rules override that fallback when they match.
+
 **Limitations:** The frontmatter parser is intentionally minimal. Use only `key: value` scalars and nested maps. Avoid arrays, multi-line scalars, and YAML anchors.
 
 ---
@@ -156,18 +162,22 @@ Controls built-in tools by exact name (no wildcards):
 | `grep`  | Pattern searching              |
 | `find`  | File discovery                 |
 | `ls`    | Directory listing              |
+| `mcp`   | MCP proxy tool entry/fallback  |
 
 ```jsonc
 {
   "tools": {
     "read": "allow",
     "write": "deny",
-    "edit": "deny"
+    "edit": "deny",
+    "mcp": "allow"
   }
 }
 ```
 
 > **Note:** Setting `tools.bash` affects the *default* for bash commands, but `bash` patterns can provide command-level overrides.
+>
+> **Note:** Setting `tools.mcp` controls coarse access to the built-in `mcp` tool. Specific `mcp` rules still override it when a target pattern matches.
 
 ### `bash`
 
@@ -190,7 +200,7 @@ Command patterns use `*` wildcards and match against the full command string. Pa
 
 ### `mcp`
 
-MCP permissions match against derived targets from tool input:
+MCP permissions match against derived targets from tool input. These rules are more specific than `tools.mcp` and override that fallback when a pattern matches:
 
 | Target Type       | Examples                                    |
 |-------------------|---------------------------------------------|
@@ -212,6 +222,35 @@ MCP permissions match against derived targets from tool input:
 
 > **Note:** Baseline discovery targets may auto-allow when you permit any MCP rule.
 
+#### MCP Tool Fallback via `tools.mcp`
+
+The `mcp` built-in tool can use `tools.mcp` as an entry permission point. This provides a fallback when no specific MCP pattern matches:
+
+```jsonc
+{
+  "tools": {
+    "mcp": "allow"
+  }
+}
+```
+
+This is useful for per-agent configurations where you want to grant MCP access broadly:
+
+```yaml
+# In ~/.pi/agent/agents/researcher.md
+---
+name: researcher
+permission:
+  tools:
+    mcp: allow
+---
+```
+
+The permission resolution order for MCP operations:
+1. Specific `mcp` patterns (e.g., `myServer:toolName`, `myServer_*`)
+2. `tools.mcp` fallback (if set)
+3. `defaultPolicy.mcp`
+
 ### `skills`
 
 Skill name patterns use `*` wildcards:
@@ -324,8 +363,10 @@ This keeps `ask` policies usable even when the original permission check happens
 index.ts                    → Root Pi entrypoint shim
 src/
 ├── index.ts                → Extension bootstrap, permission checks, and subagent forwarding
-├── permission-manager.ts   → Policy loading, merging, and resolution
-├── bash-filter.ts          → Wildcard pattern matching with specificity sorting
+├── permission-manager.ts   → Policy loading, merging, and resolution with caching
+├── bash-filter.ts          → Bash command wildcard pattern matching
+├── wildcard-matcher.ts     → Shared wildcard pattern compilation and matching
+├── common.ts               → Shared utilities (YAML parsing, type guards, etc.)
 ├── tool-registry.ts        → Registered tool name resolution
 ├── types.ts                → TypeScript type definitions
 └── test.ts                 → Test runner
@@ -335,6 +376,23 @@ config/
 └── config.example.json     → Starter configuration template
 ```
 
+#### Module Organization
+
+The extension uses a modular architecture with shared utilities:
+
+| Module | Purpose |
+|--------|---------|
+| `common.ts` | Shared utilities: `toRecord()`, `getNonEmptyString()`, `isPermissionState()`, `parseSimpleYamlMap()`, `extractFrontmatter()` |
+| `wildcard-matcher.ts` | Compile-once wildcard patterns with specificity sorting: `compileWildcardPatterns()`, `findCompiledWildcardMatch()` |
+| `permission-manager.ts` | Policy resolution with file stamp caching for performance |
+| `bash-filter.ts` | Uses shared wildcard matcher for bash command patterns |
+
+#### Performance Optimizations
+
+- **File stamp caching**: Configurations are cached with file modification timestamps to avoid redundant reads
+- **Pre-compiled patterns**: Wildcard patterns are compiled to regex once and reused across permission checks
+- **Resolved permissions caching**: Merged agent+global permissions are cached per-agent with invalidation on file changes
+
 ### Threat Model
 
 **Goal:** Enforce policy at the host level, not the model level.

package/package.json

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

package/src/bash-filter.ts

@@ -1,12 +1,11 @@
 import type { BashPermissions, PermissionState } from "./types.js";
+import {
+  compileWildcardPatterns,
+  findCompiledWildcardMatch,
+  type CompiledWildcardPattern,
+} from "./wildcard-matcher.js";
 
-type CompiledPattern = {
-  pattern: string;
-  state: PermissionState;
-  regex: RegExp;
-  wildcardCount: number;
-  literalLength: number;
-};
+type CompiledPattern = CompiledWildcardPattern<PermissionState>;
 
 export interface BashPermissionCheck {
   state: PermissionState;
@@ -14,38 +13,6 @@ export interface BashPermissionCheck {
   command: string;
 }
 
-function escapeRegExp(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-function compilePattern(pattern: string, state: PermissionState): CompiledPattern {
-  const escaped = pattern
-    .split("*")
-    .map((part) => escapeRegExp(part))
-    .join(".*");
-
-  const wildcardCount = (pattern.match(/\*/g) || []).length;
-  const literalLength = pattern.replace(/\*/g, "").length;
-
-  return {
-    pattern,
-    state,
-    regex: new RegExp(`^${escaped}$`),
-    wildcardCount,
-    literalLength,
-  };
-}
-
-function bySpecificity(a: CompiledPattern, b: CompiledPattern): number {
-  if (a.wildcardCount !== b.wildcardCount) {
-    return a.wildcardCount - b.wildcardCount;
-  }
-  if (a.literalLength !== b.literalLength) {
-    return b.literalLength - a.literalLength;
-  }
-  return b.pattern.length - a.pattern.length;
-}
-
 export class BashFilter {
   private readonly compiledPatterns: CompiledPattern[];
 
@@ -53,20 +20,17 @@ export class BashFilter {
     private readonly permissions: BashPermissions,
     private readonly defaultState: PermissionState,
   ) {
-    this.compiledPatterns = Object.entries(permissions)
-      .map(([pattern, state]) => compilePattern(pattern, state))
-      .sort(bySpecificity);
+    this.compiledPatterns = compileWildcardPatterns(permissions);
   }
 
   check(command: string): BashPermissionCheck {
-    for (const pattern of this.compiledPatterns) {
-      if (pattern.regex.test(command)) {
-        return {
-          state: pattern.state,
-          matchedPattern: pattern.pattern,
-          command,
-        };
-      }
+    const match = findCompiledWildcardMatch(this.compiledPatterns, command);
+    if (match) {
+      return {
+        state: match.state,
+        matchedPattern: match.matchedPattern,
+        command,
+      };
     }
 
     return {

package/src/common.ts

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