pi-permission-system 0.4.6 → 0.4.8

package/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.8] - 2026-05-04
+
+### Added
+- Added runtime yolo-mode control through the `/permission-system` settings modal and `globalThis.__piPermissionSystem` for other extensions.
+- Added wildcard support for `permission.tools` so direct tools from any extension can be controlled without adapter-specific hardcoding.
+- Added `PI_PERMISSION_SYSTEM_POLICY_AGENT_DIR` so global policy and global agent override lookup can be pointed at a different agent root when needed.
+
+### Changed
+- Simplified `/permission-system` to only open the settings modal, removing the previous `show`, `path`, `reset`, `help`, and `yolo ...` subcommands.
+- Expanded the README with an OpenCode-to-Pi migration guide covering agent file placement, frontmatter structure, permission mapping, Pi-specific `tools` vs `mcp` behavior, and policy-root overrides.
+
+### Fixed
+- Removed artifact validation that forced local runtime `config.json` values to match release defaults.
+- Restored requested bash command text in permission review log entries while keeping prompts and generic tool payload previews redacted.
+- Clarified last-declared-match wildcard precedence in the README and fixed wildcard-order examples/recipes so documented `tools` and `mcp` examples now match runtime behavior (thanks to @Nateowami for issue #17 and @gotgenes for the rule-order diagnosis).
+- Replaced the removed `session_switch` lifecycle subscription with a single supported `session_start` refresh path so session changes rebuild runtime permission state without duplicate handlers (thanks to @gotgenes for PR #11).
+- Removed stale README wording around exact-name tool matching and refreshed the documented architecture/module list to match the current extension layout.
+
+## [0.4.7] - 2026-05-04
+
+### Added
+- Documented `PI_PERMISSION_SYSTEM_CONFIG_PATH` and `PI_PERMISSION_SYSTEM_LOGS_DIR` overrides for custom config and log locations.
+- Added artifact validation to release checks for config defaults, schema support, README references, and package script safety.
+
+### Changed
+- Enforced trusted global/system `deny` floors so project-local policy layers can tighten permissions without relaxing higher-trust denies.
+- Switched permission review audit entries to metadata hashes and lengths for prompts, commands, denial reasons, and tool input previews instead of raw sensitive content.
+
+### Fixed
+- Stopped publishing `config.json` in the package so fresh installs use the runtime default with yolo mode off by default (thanks to @Nateowami for PR #18).
+
 ## [0.4.6] - 2026-04-28
 
 ### Added

package/README.md

@@ -6,6 +6,87 @@ Permission enforcement extension for the Pi coding agent that provides centraliz
 
 <img width="1360" height="752" alt="image" src="https://github.com/user-attachments/assets/3e85190a-17fa-4d94-ac8e-efa54337df5d" />
 
+## Coming from OpenCode?
+
+Yes — this extension was designed so OpenCode-style agent permission policies can be ported into Pi with minimal friction.
+
+### Start here
+
+| If you have this in OpenCode | In Pi, use this |
+|---|---|
+| Agent markdown file | `~/.pi/agent/agents/<agent-name>.md` (respects `PI_CODING_AGENT_DIR`) |
+| YAML frontmatter | Same place: top of the markdown file |
+| Agent instructions / system prompt body | Same file, below frontmatter |
+| Agent permission rules | `permission:` inside that same frontmatter |
+
+### Important compatibility notes
+
+- **Agents are still markdown files with YAML frontmatter.**
+- **Wildcard permissions still use last-match-wins ordering.**
+- **Keep frontmatter simple when porting.** This extension intentionally supports `key: value` scalars and nested maps, not full YAML features like arrays, anchors, or multiline scalars.
+
+### Minimal Pi agent example
+
+```md
+---
+name: my-agent
+mode: primary
+description: My ported agent
+permission:
+  tools:
+    read: allow
+    grep: allow
+  bash:
+    "*": ask
+  mcp:
+    "*": ask
+---
+
+Your agent instructions go here.
+```
+
+### Compatibility matrix
+
+| OpenCode concept | Pi equivalent with this extension | Compatibility | Porting notes |
+|---|---|---:|---|
+| Agent markdown files with YAML frontmatter | `~/.pi/agent/agents/<agent-name>.md` | High | Your agent-local `permission:` frontmatter pattern carries over cleanly. |
+| Wildcard precedence | Same last-declared-match-wins behavior | High | Broad rules first, specific overrides later. |
+| `bash` permission rules | `permission.bash` | High | Command-pattern gating ports cleanly. |
+| Per-tool permission rules like `read`, `grep`, `list`, `task`, or arbitrary extension tool names | `permission.tools` | Medium-High | Pi groups registered tool names under `tools`, including built-ins and extension tools. |
+| `external_directory` | `permission.special.external_directory` | Medium | Same idea, different location. |
+| `doom_loop` | `permission.special.doom_loop` | Medium | Same idea, different location. |
+| `skill` permission rules | `permission.skills` | Medium | Same purpose, but Pi uses a dedicated plural `skills` section. |
+| MCP-related access | `permission.mcp` for proxy targets, `permission.tools` for direct registered tools | Medium | This is the biggest Pi-specific difference: proxy MCP targets and direct tool names are intentionally split. |
+| OpenCode-specific permissions like `webfetch`, `websearch`, `question`, `lsp`, `todowrite` | Usually extension-specific Pi tool names under `permission.tools` | Low-Medium | These do not have universal built-in one-to-one Pi names; map them to the actual registered tools available in your Pi setup. |
+
+### Most important difference
+
+In OpenCode, many permission names live in one broad permission namespace. In Pi with this extension, there is a deliberate split:
+
+| Use this when... | Put the rule here |
+|---|---|
+| You are targeting the registered **`mcp` proxy tool** and its internal server/tool targets | `permission.mcp` |
+| You are targeting an actual registered tool name, including direct extension tools like `context7_*`, `github_*`, or `exa_*` | `permission.tools` |
+
+### Fast porting guide
+
+| If your OpenCode agent has... | In Pi, do this |
+|---|---|
+| `permission.bash` rules | Move them into `permission.bash` |
+| `permission.external_directory` | Move it to `permission.special.external_directory` |
+| `permission.doom_loop` | Move it to `permission.special.doom_loop` |
+| `permission.skill` rules | Move them to `permission.skills` |
+| Tool-ish permissions like `read`, `grep`, `list`, `task`, or third-party tool names | Put them in `permission.tools` |
+| MCP server/tool target logic | Put proxy-target rules in `permission.mcp` |
+
+### Practical takeaway
+
+If you are coming from OpenCode, you usually do **not** need to rewrite your whole agent. In most cases, porting is just:
+
+1. Keep the agent markdown/frontmatter structure.
+2. Move OpenCode-style tool permissions into Pi's `tools` section.
+3. Move `external_directory` and `doom_loop` into `special`.
+4. Split MCP proxy target rules into `mcp` and direct registered tool rules into `tools`.
 
 ## Features
 
@@ -17,6 +98,7 @@ Permission enforcement extension for the Pi coding agent that provides centraliz
 - **Skill Protection** — Controls which skills can be loaded or read from disk, including multi-block prompt sanitization
 - **Per-Agent Overrides** — Agent-specific permission policies via YAML frontmatter
 - **Subagent Permission Forwarding** — Forwards `ask` confirmations from non-UI subagents back to the main interactive session
+- **Runtime YOLO Control** — Lets users toggle yolo mode from the settings modal and lets other extensions toggle it through the runtime API
 - **File-Based Review Logging** — Writes permission request/denial review entries to a file by default for later auditing
 - **Optional Debug Logging** — Keeps verbose extension diagnostics in a separate file when enabled in `config.json`
 - **JSON Schema Validation** — Full schema for editor autocomplete and config validation
@@ -41,7 +123,7 @@ Place this folder in one of the following locations:
 
 Pi auto-discovers extensions in these paths.
 
-> **Tip:** All `~/.pi/agent` paths shown in this document are defaults. If the `PI_CODING_AGENT_DIR` environment variable is set, pi uses that directory instead. The extension automatically follows pi's `getAgentDir()` helper, so global policy files, per-agent overrides, session directories, and extension installation paths all resolve under the configured agent directory.
+> **Tip:** All `~/.pi/agent` paths shown in this document are defaults. If the `PI_CODING_AGENT_DIR` environment variable is set, pi uses that directory instead. The extension automatically follows pi's `getAgentDir()` helper for extension installation, session directories, and extension-local config paths. If you need policy lookup to come from a different global agent root, set `PI_PERMISSION_SYSTEM_POLICY_AGENT_DIR`.
 
 ## Usage
 
@@ -90,10 +172,10 @@ The extension integrates via Pi's lifecycle hooks:
 **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
-- Extension-provided tools like `task`, `mcp`, and third-party tools are handled by exact registered name instead of private built-in hardcodes
+- Extension-provided tools like `task`, `mcp`, and third-party tools are handled through the same registered-tool permission layer instead of private built-in hardcodes
 - When a subagent hits an `ask` permission without direct UI access, the request can be forwarded to the main interactive session for confirmation
 - Generic extension-tool approval prompts include a bounded input preview; built-in file tools use concise human-readable summaries instead of raw multiline JSON
-- Permission review logs include bounded `toolInputPreview` values for non-bash/non-MCP tool calls so approvals can be audited without writing raw full payloads
+- Permission review logs include requested bash command text plus redacted prompt/input metadata for auditing without writing raw prompts or generic tool payload previews
 - Path-bearing file tools (`read`, `write`, `edit`, `find`, `grep`, `ls`) evaluate `special.external_directory` before their normal tool permission when an explicit path points outside `ctx.cwd`
 
 ## Configuration
@@ -102,7 +184,9 @@ The extension integrates via Pi's lifecycle hooks:
 
 **Location:** global Pi extension config (default: `~/.pi/agent/extensions/pi-permission-system/config.json`, respects `PI_CODING_AGENT_DIR`)
 
-The extension creates this file automatically when it is missing. It controls only extension-local logging behavior:
+Set `PI_PERMISSION_SYSTEM_CONFIG_PATH` to point this extension at a specific config file when the default global path is not appropriate.
+
+The extension creates this file automatically when it is missing. It controls extension-local logging behavior and yolo mode defaults:
 
 ```json
 {
@@ -118,18 +202,45 @@ The extension creates this file automatically when it is missing. It controls on
 | `permissionReviewLog` | `true` | Enables the permission request/denial review log at `logs/pi-permission-system-permission-review.jsonl` |
 | `yoloMode` | `false` | Auto-approves `ask` results instead of prompting when yolo mode is enabled |
 
-Both logs write to files only under the extension directory. No debug output is printed to the terminal.
+Both logs write to files only under the extension directory by default. Set `PI_PERMISSION_SYSTEM_LOGS_DIR` to redirect review/debug logs to a specific directory. No debug output is printed to the terminal.
+
+### Runtime YOLO Control
+
+Use `/permission-system` to open the settings modal and inspect or change yolo mode interactively.
+
+Other extensions can toggle yolo mode immediately through the shared runtime API:
+
+```ts
+type PermissionSystemGlobal = typeof globalThis & {
+  __piPermissionSystem?: {
+    toggleYoloMode(options?: { persist?: boolean; source?: string }): { error?: string };
+  };
+};
+
+pi.registerShortcut("f8", {
+  description: "Toggle pi-permission-system YOLO mode",
+  handler: () => {
+    const permissionSystem = (globalThis as PermissionSystemGlobal).__piPermissionSystem;
+    const result = permissionSystem?.toggleYoloMode({ source: "my-extension" });
+    if (result?.error) {
+      // Notify or log the error in your extension.
+    }
+  },
+});
+```
+
+The runtime API exposes `getYoloMode()`, `setYoloMode(enabled, options?)`, and `toggleYoloMode(options?)`. Runtime updates persist to `config.json` by default; pass `{ persist: false }` for a current-session-only toggle.
 
 ### Global Policy File
 
-**Location:** global Pi policy file (default: `~/.pi/agent/pi-permissions.jsonc`, respects `PI_CODING_AGENT_DIR`)
+**Location:** global Pi policy file (default: `~/.pi/agent/pi-permissions.jsonc`, respects `PI_PERMISSION_SYSTEM_POLICY_AGENT_DIR` when set and otherwise follows `PI_CODING_AGENT_DIR`)
 
 The policy file is a JSON object with these sections:
 
 | Section         | Description                                         |
 |-----------------|-----------------------------------------------------|
 | `defaultPolicy` | Fallback permissions per category                   |
-| `tools`         | Exact-name tool permissions for registered tools    |
+| `tools`         | Pattern-based tool permissions for registered tools |
 | `bash`          | Command pattern permissions                         |
 | `mcp`           | MCP server/tool permissions for calls routed through a registered `mcp` tool |
 | `skills`        | Skill name pattern permissions                      |
@@ -139,7 +250,7 @@ The policy file is a JSON object with these sections:
 
 ### Global Per-Agent Overrides
 
-Override global permissions for specific agents via YAML frontmatter in the global Pi agents directory (default: `~/.pi/agent/agents/<agent>.md`, respects `PI_CODING_AGENT_DIR`):
+Override global permissions for specific agents via YAML frontmatter in the global Pi agents directory (default: `~/.pi/agent/agents/<agent-name>.md`, respects `PI_PERMISSION_SYSTEM_POLICY_AGENT_DIR` when set and otherwise follows `PI_CODING_AGENT_DIR`):
 
 ```yaml
 ---
@@ -162,7 +273,7 @@ permission:
 
 **MCP behavior:** `permission.tools.mcp` is the coarse entry/fallback permission for a registered `mcp` tool when one is available. 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.
+**Limitations:** The frontmatter parser is intentionally minimal. Use only `key: value` scalars and nested maps. Avoid arrays, multi-line scalars, and YAML anchors. If you are porting from OpenCode, simplify richer YAML frontmatter before expecting a clean migration.
 
 ### Project-Level Policy Files
 
@@ -171,7 +282,7 @@ The extension can also layer project-local permission files relative to the acti
 | Scope | Path |
 |-------|------|
 | Project policy | `<cwd>/.pi/agent/pi-permissions.jsonc` |
-| Project agent override | `<cwd>/.pi/agent/agents/<agent>.md` |
+| Project agent override | `<cwd>/.pi/agent/agents/<agent-name>.md` |
 
 Project-local files use the same formats as the global policy file and global agent frontmatter. These project files are resolved from Pi's current session `cwd`, so they are workspace-specific and do **not** move under `PI_CODING_AGENT_DIR`.
 
@@ -181,7 +292,7 @@ Project-local files use the same formats as the global policy file and global ag
 3. Global agent frontmatter
 4. Project agent frontmatter
 
-Later layers override earlier layers within the same permission category. For wildcard-based sections like `bash`, `mcp`, `skills`, and `special`, matching still follows the extension's existing **last matching rule wins** behavior after the layers are combined.
+Later trusted layers override earlier layers within the same permission category, and project-local layers can tighten policy by adding `deny` rules. Project-local policy cannot relax a `deny` from the global policy file or global agent frontmatter: an `allow` or `ask` in a project policy is ignored when the latest matching trusted layer is `deny`. For wildcard-based sections like `tools`, `bash`, `mcp`, `skills`, and `special`, matching still follows **last matching rule wins** within the applicable trust boundary, with global/system `deny` rules acting as floors for project-local overrides.
 
 ---
 
@@ -205,7 +316,7 @@ Sets fallback permissions when no specific rule matches:
 
 ### `tools`
 
-Controls tools by exact registered name (no wildcards). This is the recommended standalone format for **all** tool entries, including Pi built-ins and arbitrary third-party extension tools.
+Controls tools by registered name pattern. This is the recommended standalone format for **all** tool entries, including Pi built-ins and arbitrary third-party extension tools. Patterns use `*` wildcards and follow last-declared-match semantics, so put broad fallbacks first and specific overrides later.
 
 | Tool name example     | Description |
 |-----------------------|-------------|
@@ -214,29 +325,33 @@ Controls tools by exact registered name (no wildcards). This is the recommended
 | `mcp`                 | Registered MCP proxy tool entry/fallback when available |
 | `task`                | Delegation tool handled like any other registered extension tool |
 | `third_party_tool`    | Arbitrary registered extension tool |
+| `context7_*`          | Wildcard for direct tools registered by another extension |
+| `*`                   | Fallback for every registered tool not matched by a later rule |
 
 ```jsonc
 {
   "tools": {
-    "read": "allow",
-    "write": "deny",
+    "*": "ask",
+    "context7_*": "ask",
+    "third_party_tool": "ask",
     "mcp": "allow",
-    "third_party_tool": "ask"
+    "read": "allow",
+    "write": "deny"
   }
 }
 ```
 
-Unknown or absent tools are not required in the config. If another extension is not installed, its tool simply will not be registered at runtime, and this extension will block attempts to call that missing tool before permission checks run.
+Unknown or absent tools are not required in the config. If another extension is not installed, its tool simply will not be registered at runtime, and this extension will block attempts to call that missing tool before permission checks run. Wildcard `tools` rules apply to direct tools from any extension; no adapter-specific naming is required.
 
 > **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 a registered `mcp` tool when one is available. Specific `mcp` rules still override it when a target pattern matches.
+> **Note:** Setting `tools.mcp` controls coarse access to a registered `mcp` proxy tool when one is available. Specific `mcp` rules still override it when a proxy target pattern matches. Direct MCP tools registered by extensions are regular registered tools and should be controlled with `tools` patterns such as `context7_*` or `github_*`.
 >
 > **Note:** Top-level shorthand is only supported for the canonical Pi built-ins (`bash`, `read`, `write`, `edit`, `grep`, `find`, `ls`) in agent frontmatter. Use `permission.tools.<name>` for `mcp`, `task`, and any third-party tool.
 
 ### `bash`
 
-Command patterns use `*` wildcards and match against the full command string. If multiple patterns match, the **last matching rule wins**.
+Command patterns use `*` wildcards and match against the full command string. If multiple patterns match, the **last declared matching rule wins**. Put broad fallback rules first and more specific overrides later.
 
 ```jsonc
 {
@@ -262,9 +377,10 @@ MCP permissions match against derived targets from tool input. These rules are m
 ```jsonc
 {
   "mcp": {
+    "*": "ask",
+    "myServer:*": "ask",
     "mcp_status": "allow",
     "mcp_list": "allow",
-    "myServer:*": "ask",
     "dangerousServer": "deny"
   }
 }
@@ -322,7 +438,6 @@ Reserved permission checks:
 |----------------------|------------------------------------------|
 | `doom_loop`          | Controls doom loop detection behavior    |
 | `external_directory` | Enforces ask/allow/deny decisions for path-bearing built-in tools (`read`, `write`, `edit`, `find`, `grep`, `ls`) when they target paths outside the active working directory |
-| `tool_call_limit`    | *(schema only, not enforced yet)*        |
 
 ```jsonc
 {
@@ -361,10 +476,10 @@ Reserved permission checks:
 {
   "defaultPolicy": { "tools": "ask", "bash": "deny", "mcp": "ask", "skills": "ask", "special": "ask" },
   "bash": {
+    "git *": "ask",
     "git status": "allow",
     "git diff": "allow",
-    "git log *": "allow",
-    "git *": "ask"
+    "git log *": "allow"
   }
 }
 ```
@@ -375,11 +490,11 @@ Reserved permission checks:
 {
   "defaultPolicy": { "tools": "ask", "bash": "ask", "mcp": "ask", "skills": "ask", "special": "ask" },
   "mcp": {
+    "*": "ask",
     "mcp_status": "allow",
     "mcp_list": "allow",
     "mcp_search": "allow",
-    "mcp_describe": "allow",
-    "*": "ask"
+    "mcp_describe": "allow"
   }
 }
 ```
@@ -431,34 +546,45 @@ When the extension prompts, denies, or forwards permission requests, it can appe
 ```text
 Default global logs directory: ~/.pi/agent/extensions/pi-permission-system/logs/
 Actual global logs directory: $PI_CODING_AGENT_DIR/extensions/pi-permission-system/logs when PI_CODING_AGENT_DIR is set
+Override logs directory: $PI_PERMISSION_SYSTEM_LOGS_DIR when set
 ```
 
-- `pi-permission-system-permission-review.jsonl` — enabled by default for permission review/audit history, including bounded `toolInputPreview` values for non-bash/non-MCP tool calls
+- `pi-permission-system-permission-review.jsonl` — enabled by default for permission review/audit history, including metadata hashes and lengths for prompts, commands, denial reasons, and tool input previews instead of raw sensitive content
 - `pi-permission-system-debug.jsonl` — disabled by default and intended for troubleshooting
 
 ### Architecture
 
 ```
-index.ts                    → Root Pi entrypoint shim
+index.ts                         → Root Pi entrypoint shim
 src/
-├── index.ts                → Extension bootstrap, permission checks, readable prompts, review logging, reload handling, and subagent forwarding
-├── extension-config.ts     → Extension-local config loading and default creation
-├── logging.ts              → File-only debug/review logging helpers
-├── permission-manager.ts   → Global/project policy loading, merging, and resolution with caching
-├── skill-prompt-sanitizer.ts → Skill prompt parsing, multi-block sanitization, and skill-read path matching
-├── 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
+├── index.ts                     → Extension bootstrap, permission checks, readable prompts, review logging, reload handling, and subagent forwarding
+├── before-agent-start-cache.ts  → Caches prompt/tool filtering state between before_agent_start runs
+├── bash-filter.ts               → Bash command wildcard pattern matching
+├── common.ts                    → Shared utilities (YAML parsing, type guards, etc.)
+├── config-modal.ts              → `/permission-system` modal registration and settings UI wiring
+├── extension-config.ts          → Extension-local config loading and default creation
+├── logging.ts                   → File-only debug/review logging helpers
+├── model-option-compatibility.ts → Guards unsupported provider/model options
+├── permission-dialog.ts         → Interactive permission approval UI helpers
+├── permission-forwarding.ts     → Subagent-to-parent permission forwarding utilities
+├── permission-manager.ts        → Global/project policy loading, merging, and resolution with caching
+├── skill-prompt-sanitizer.ts    → Skill prompt parsing, multi-block sanitization, and skill-read path matching
+├── status.ts                    → Status line integration for runtime yolo state
+├── system-prompt-sanitizer.ts   → Available-tools prompt filtering helpers
+├── tool-registry.ts             → Registered tool name resolution
+├── types.ts                     → TypeScript type definitions
+├── wildcard-matcher.ts          → Shared wildcard pattern compilation and matching
+├── yolo-mode.ts                 → Runtime yolo approval helpers
+├── yolo-mode-api.ts             → Shared global runtime API for yolo toggling
+└── zellij-modal.ts              → Reusable modal/settings UI components
 tests/
-├── permission-system.test.ts → Core permission, layering, forwarding, and policy tests
-├── config-modal.test.ts      → Config command and modal behavior tests
-└── test-harness.ts           → Shared lightweight test helpers
+├── permission-system.test.ts    → Core permission, layering, forwarding, and policy tests
+├── config-modal.test.ts         → Modal command behavior tests
+└── test-harness.ts              → Shared lightweight test helpers
 schemas/
-└── permissions.schema.json → JSON Schema for policy validation
+└── permissions.schema.json      → JSON Schema for policy validation
 config/
-└── config.example.json     → Starter global policy template
+└── config.example.json          → Starter global policy template
 ```
 
 #### Module Organization
@@ -522,11 +648,14 @@ npx --yes ajv-cli@5 validate \
 
 ## Development
 
+Runtime checks require Node.js 20+; the test suite requires Bun 1.1+.
+
 ```bash
-npm run build    # Compile TypeScript
-npm run lint     # Run linter (uses build)
-npm run test     # Run tests from ./tests
-npm run check    # Run lint + test
+npm run build              # Run TypeScript type checks
+npm run lint               # Run local static checks
+npm run validate:artifacts # Validate JSON/schema/example artifacts
+npm run test               # Run Bun tests from ./tests
+npm run check              # Run static, artifact, and test checks
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-permission-system",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "main": "./index.ts",
@@ -11,7 +11,6 @@
     "index.ts",
     "src",
     "tests",
-    "config.json",
     "config/config.example.json",
     "schemas/permissions.schema.json",
     "README.md",
@@ -19,10 +18,12 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
-    "lint": "npm run build",
+    "typecheck": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noEmit",
+    "build": "npm run typecheck",
+    "lint": "npm run typecheck",
+    "validate:artifacts": "node ./scripts/validate-artifacts.mjs",
     "test": "bun ./tests/permission-system.test.ts && bun ./tests/config-modal.test.ts",
-    "check": "npm run lint && npm run test"
+    "check": "npm run lint && npm run validate:artifacts && npm run test"
   },
   "keywords": [
     "pi-package",
@@ -47,7 +48,8 @@
     "url": "https://github.com/MasuRii/pi-permission-system/issues"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=20",
+    "bun": ">=1.1.0"
   },
   "publishConfig": {
     "access": "public"
@@ -58,9 +60,9 @@
     ]
   },
   "peerDependencies": {
-    "@mariozechner/pi-ai": "^0.70.5",
-    "@mariozechner/pi-coding-agent": "^0.70.5",
-    "@mariozechner/pi-tui": "^0.70.5",
+    "@mariozechner/pi-ai": "^0.72.0",
+    "@mariozechner/pi-coding-agent": "^0.72.0",
+    "@mariozechner/pi-tui": "^0.72.0",
     "@sinclair/typebox": "^0.34.49"
   }
 }

package/schemas/permissions.schema.json

@@ -31,7 +31,7 @@
       }
     },
     "tools": {
-      "description": "Exact-name permissions for registered tools. Use this map for the canonical Pi built-ins and any extension-provided or third-party tools.",
+      "description": "Pattern-based permissions for registered tools. Use exact names or `*` wildcards for canonical Pi built-ins and any extension-provided or third-party tools.",
       "$ref": "#/$defs/permissionMap"
     },
     "bash": {
@@ -53,17 +53,6 @@
         },
         "external_directory": {
           "$ref": "#/$defs/permissionState"
-        },
-        "tool_call_limit": {
-          "oneOf": [
-            {
-              "$ref": "#/$defs/permissionState"
-            },
-            {
-              "type": "integer",
-              "minimum": 0
-            }
-          ]
         }
       }
     }

package/src/common.ts

@@ -1,3 +1,6 @@
+import { homedir } from "node:os";
+import { join, normalize, resolve, sep } from "node:path";
+
 import type { PermissionState } from "./types.js";
 
 export function toRecord(value: unknown): Record<string, unknown> {
@@ -21,6 +24,38 @@ export function isPermissionState(value: unknown): value is PermissionState {
   return value === "allow" || value === "deny" || value === "ask";
 }
 
+export function normalizePathForComparison(pathValue: string, cwd: string): string {
+  const trimmed = pathValue.trim().replace(/^["']|["']$/g, "");
+  if (!trimmed) {
+    return "";
+  }
+
+  let normalizedPath = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed;
+
+  if (normalizedPath === "~") {
+    normalizedPath = homedir();
+  } else if (normalizedPath.startsWith("~/") || normalizedPath.startsWith("~\\")) {
+    normalizedPath = join(homedir(), normalizedPath.slice(2));
+  }
+
+  const absolutePath = resolve(cwd, normalizedPath);
+  const normalizedAbsolutePath = normalize(absolutePath);
+  return process.platform === "win32" ? normalizedAbsolutePath.toLowerCase() : normalizedAbsolutePath;
+}
+
+export function isPathWithinDirectory(pathValue: string, directory: string): boolean {
+  if (!pathValue || !directory) {
+    return false;
+  }
+
+  if (pathValue === directory) {
+    return true;
+  }
+
+  const prefix = directory.endsWith(sep) ? directory : `${directory}${sep}`;
+  return pathValue.startsWith(prefix);
+}
+
 type StackNode = { indent: number; target: Record<string, unknown> };
 
 export function parseSimpleYamlMap(input: string): Record<string, unknown> {