pi-permission-system 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -5,7 +5,42 @@ 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
+
+### Added
+- Sanitized the `Available tools:` system prompt section so denied tools are removed before the agent starts.
+
+### Changed
+- Updated README documentation to describe system-prompt tool sanitization and refreshed the displayed package version.
+
+### Fixed
+- Prevented hidden tools from remaining advertised in the startup system prompt after runtime tool filtering.
+
+## [0.1.5] - 2026-03-09
+
+### Changed
+- Added `repository`, `homepage`, and `bugs` package metadata so npm links back to the public GitHub repository and issue tracker.
 
 ## [0.1.4] - 2026-03-07
 

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 MasuRii
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 MasuRii
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # 🔐 pi-permission-system
 
-[![Version](https://img.shields.io/badge/version-0.1.4-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.
@@ -10,6 +10,7 @@ Permission enforcement extension for the Pi coding agent that provides centraliz
 ## Features
 
 - **Tool Filtering** — Hides disallowed tools from the agent before it starts (reduces "try another tool" behavior)
+- **System Prompt Sanitization** — Removes denied tool entries from the `Available tools:` system prompt section so the agent only sees tools it can actually call
 - **Runtime Enforcement** — Blocks/asks/allows at tool call time with UI confirmation dialogs
 - **Bash Command Control** — Wildcard pattern matching for granular bash command permissions
 - **MCP Access Control** — Server and tool-level permissions for MCP operations
@@ -67,14 +68,15 @@ All permissions use one of three states:
 
 The extension integrates via Pi's lifecycle hooks:
 
-| Hook                 | Behavior                                                              |
-|----------------------|-----------------------------------------------------------------------|
-| `before_agent_start` | Filters active tools and removes denied skills from system prompt     |
-| `tool_call`          | Enforces permissions for every tool invocation                        |
-| `input`              | Intercepts `/skill:<name>` requests and enforces skill policy         |
+| Hook                 | Behavior                                                                                  |
+|----------------------|-------------------------------------------------------------------------------------------|
+| `before_agent_start` | Filters active tools, removes denied tool entries from the system prompt, and hides denied skills |
+| `tool_call`          | Enforces permissions for every tool invocation                                            |
+| `input`              | Intercepts `/skill:<name>` requests and enforces skill policy                             |
 
 **Additional behaviors:**
 - Unknown/unregistered tools are blocked before permission checks (prevents bypass attempts)
+- The `Available tools:` system prompt section is rewritten to match the filtered active tool set
 - The `task` delegation tool is restricted to the `orchestrator` agent only
 - When a subagent hits an `ask` permission without direct UI access, the request can be forwarded to the main interactive session for confirmation
 - When a subagent triggers an `ask` permission without UI access, the request can be forwarded to the main session and answered there
@@ -109,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
 ---
@@ -119,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.
 
 ---
@@ -154,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`
 
@@ -188,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                                    |
 |-------------------|---------------------------------------------|
@@ -210,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:
@@ -322,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
@@ -333,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/config/config.example.json

@@ -1,27 +1,27 @@
-{
-  "defaultPolicy": {
-    "tools": "ask",
-    "bash": "ask",
-    "mcp": "ask",
-    "skills": "ask",
-    "special": "ask"
-  },
-  "tools": {
-    "read": "allow",
-    "write": "deny"
-  },
-  "bash": {
-    "git status": "allow",
-    "git *": "ask"
-  },
-  "mcp": {
-    "mcp_status": "allow"
-  },
-  "skills": {
-    "*": "ask"
-  },
-  "special": {
-    "doom_loop": "deny",
-    "external_directory": "ask"
-  }
-}
+{
+  "defaultPolicy": {
+    "tools": "ask",
+    "bash": "ask",
+    "mcp": "ask",
+    "skills": "ask",
+    "special": "ask"
+  },
+  "tools": {
+    "read": "allow",
+    "write": "deny"
+  },
+  "bash": {
+    "git status": "allow",
+    "git *": "ask"
+  },
+  "mcp": {
+    "mcp_status": "allow"
+  },
+  "skills": {
+    "*": "ask"
+  },
+  "special": {
+    "doom_loop": "deny",
+    "external_directory": "ask"
+  }
+}

package/index.ts

@@ -1,3 +1,3 @@
-import permissionSystemExtension from "./src/index.js";
-
-export default permissionSystemExtension;
+import permissionSystemExtension from "./src/index.js";
+
+export default permissionSystemExtension;

package/package.json

@@ -1,59 +1,59 @@
-{
-  "name": "pi-permission-system",
-  "version": "0.1.5",
-  "description": "Permission enforcement extension for the Pi coding agent.",
-  "type": "module",
-  "main": "./index.ts",
-  "exports": {
-    ".": "./index.ts"
-  },
-  "files": [
-    "index.ts",
-    "src",
-    "config/config.example.json",
-    "schemas/permissions.schema.json",
-    "asset",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
-    "lint": "npm run build",
-    "test": "bun ./src/test.ts",
-    "check": "npm run lint && npm run test"
-  },
-  "keywords": [
-    "pi-package",
-    "pi",
-    "pi-extension",
-    "permissions",
-    "policy",
-    "coding-agent"
-  ],
-  "author": "MasuRii",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/MasuRii/pi-permission-system.git"
-  },
-  "homepage": "https://github.com/MasuRii/pi-permission-system#readme",
-  "bugs": {
-    "url": "https://github.com/MasuRii/pi-permission-system/issues"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ]
-  },
-  "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "*",
-    "@sinclair/typebox": "*"
-  }
-}
+{
+  "name": "pi-permission-system",
+  "version": "0.1.7",
+  "description": "Permission enforcement extension for the Pi coding agent.",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "config/config.example.json",
+    "schemas/permissions.schema.json",
+    "asset",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
+    "lint": "npm run build",
+    "test": "bun ./src/test.ts",
+    "check": "npm run lint && npm run test"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "permissions",
+    "policy",
+    "coding-agent"
+  ],
+  "author": "MasuRii",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MasuRii/pi-permission-system.git"
+  },
+  "homepage": "https://github.com/MasuRii/pi-permission-system#readme",
+  "bugs": {
+    "url": "https://github.com/MasuRii/pi-permission-system/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@sinclair/typebox": "*"
+  }
+}

package/schemas/permissions.schema.json

@@ -1,86 +1,86 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://pi-coding-agent.local/schemas/permissions.schema.json",
-  "title": "PI Permission Configuration",
-  "type": "object",
-  "additionalProperties": false,
-  "properties": {
-    "$schema": {
-      "type": "string"
-    },
-    "defaultPolicy": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["tools", "bash", "mcp", "skills"],
-      "properties": {
-        "tools": {
-          "$ref": "#/$defs/permissionState"
-        },
-        "bash": {
-          "$ref": "#/$defs/permissionState"
-        },
-        "mcp": {
-          "$ref": "#/$defs/permissionState"
-        },
-        "skills": {
-          "$ref": "#/$defs/permissionState"
-        },
-        "special": {
-          "$ref": "#/$defs/permissionState"
-        }
-      }
-    },
-    "tools": {
-      "$ref": "#/$defs/permissionMap"
-    },
-    "bash": {
-      "$ref": "#/$defs/permissionMap"
-    },
-    "mcp": {
-      "$ref": "#/$defs/permissionMap"
-    },
-    "skills": {
-      "$ref": "#/$defs/permissionMap"
-    },
-    "special": {
-      "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "doom_loop": {
-          "$ref": "#/$defs/permissionState"
-        },
-        "external_directory": {
-          "$ref": "#/$defs/permissionState"
-        },
-        "tool_call_limit": {
-          "oneOf": [
-            {
-              "$ref": "#/$defs/permissionState"
-            },
-            {
-              "type": "integer",
-              "minimum": 0
-            }
-          ]
-        }
-      }
-    }
-  },
-  "required": ["defaultPolicy"],
-  "$defs": {
-    "permissionState": {
-      "type": "string",
-      "enum": ["allow", "deny", "ask"]
-    },
-    "permissionMap": {
-      "type": "object",
-      "propertyNames": {
-        "type": "string",
-        "minLength": 1
-      },
-      "additionalProperties": {
-        "$ref": "#/$defs/permissionState"
-      }
-    }
-  }
-}
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://pi-coding-agent.local/schemas/permissions.schema.json",
+  "title": "PI Permission Configuration",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "defaultPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tools", "bash", "mcp", "skills"],
+      "properties": {
+        "tools": {
+          "$ref": "#/$defs/permissionState"
+        },
+        "bash": {
+          "$ref": "#/$defs/permissionState"
+        },
+        "mcp": {
+          "$ref": "#/$defs/permissionState"
+        },
+        "skills": {
+          "$ref": "#/$defs/permissionState"
+        },
+        "special": {
+          "$ref": "#/$defs/permissionState"
+        }
+      }
+    },
+    "tools": {
+      "$ref": "#/$defs/permissionMap"
+    },
+    "bash": {
+      "$ref": "#/$defs/permissionMap"
+    },
+    "mcp": {
+      "$ref": "#/$defs/permissionMap"
+    },
+    "skills": {
+      "$ref": "#/$defs/permissionMap"
+    },
+    "special": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "doom_loop": {
+          "$ref": "#/$defs/permissionState"
+        },
+        "external_directory": {
+          "$ref": "#/$defs/permissionState"
+        },
+        "tool_call_limit": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/permissionState"
+            },
+            {
+              "type": "integer",
+              "minimum": 0
+            }
+          ]
+        }
+      }
+    }
+  },
+  "required": ["defaultPolicy"],
+  "$defs": {
+    "permissionState": {
+      "type": "string",
+      "enum": ["allow", "deny", "ask"]
+    },
+    "permissionMap": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string",
+        "minLength": 1
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/permissionState"
+      }
+    }
+  }
+}