@gotgenes/pi-permission-system 2.0.0 → 3.0.1

package/CHANGELOG.md

@@ -5,6 +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).
 
+## [3.0.1](https://github.com/gotgenes/pi-permission-system/compare/v3.0.0...v3.0.1) (2026-05-03)
+
+
+### Documentation
+
+* add descriptions to all JSON schema entities ([cb3a7ce](https://github.com/gotgenes/pi-permission-system/commit/cb3a7ce5257111159312ebb95a9f75dd4e4a9527))
+* enrich JSON schema with examples, defaults, and markdown descriptions ([6f38d7e](https://github.com/gotgenes/pi-permission-system/commit/6f38d7edf01b950f20e2fab8604a398bf725a6c4))
+* plan index.ts split into focused modules ([#21](https://github.com/gotgenes/pi-permission-system/issues/21)) ([ccd736a](https://github.com/gotgenes/pi-permission-system/commit/ccd736a83a4af208044eec925c80555ee645e344))
+* **retro:** add retro notes for issue [#10](https://github.com/gotgenes/pi-permission-system/issues/10) ([31e59d6](https://github.com/gotgenes/pi-permission-system/commit/31e59d6172da7b0e9f02894afd2ba66a292de168))
+* **retro:** correct formatting friction attribution ([#10](https://github.com/gotgenes/pi-permission-system/issues/10)) ([2e96b7b](https://github.com/gotgenes/pi-permission-system/commit/2e96b7bc1007a2ef55f95b29c40b8417c2c6c52f))
+* update plan with Phase 2 unit tests using DI and vitest mocks ([#21](https://github.com/gotgenes/pi-permission-system/issues/21)) ([ad7f5fe](https://github.com/gotgenes/pi-permission-system/commit/ad7f5feeb856c84142a2a4258a9e173c8006532d))
+
+## [3.0.0](https://github.com/gotgenes/pi-permission-system/compare/v2.0.0...v3.0.0) (2026-05-03)
+
+
+### ⚠ BREAKING CHANGES
+
+* Config is now loaded from ~/.pi/agent/extensions/pi-permission-system/config.json (global) and <cwd>/.pi/extensions/pi-permission-system/config.json (project). Legacy paths are detected and merged with migration warnings.
+* Config and log file paths move from the extension install directory and ~/.pi/agent/ to the extensions/<id>/ convention.
+
+### Features
+
+* add config-paths module with new layout paths ([#10](https://github.com/gotgenes/pi-permission-system/issues/10)) ([532d2a1](https://github.com/gotgenes/pi-permission-system/commit/532d2a1f1d816c1cfba5419f7d0041382c848b31))
+* add unified config loader ([#10](https://github.com/gotgenes/pi-permission-system/issues/10)) ([20143e0](https://github.com/gotgenes/pi-permission-system/commit/20143e0f7b608965d889433a6b9bbd6f9ab8b4cc))
+* detect and merge legacy config paths ([#10](https://github.com/gotgenes/pi-permission-system/issues/10)) ([95046de](https://github.com/gotgenes/pi-permission-system/commit/95046de6a57d604c5f0d9fa8c13a64478ba15c89))
+* implement config merge in unified loader ([#10](https://github.com/gotgenes/pi-permission-system/issues/10)) ([30b9afe](https://github.com/gotgenes/pi-permission-system/commit/30b9afe3d83940aa3ad708c9d6783bb2d4337743))
+* update config-reporter for consolidated layout ([#10](https://github.com/gotgenes/pi-permission-system/issues/10)) ([96c9ef4](https://github.com/gotgenes/pi-permission-system/commit/96c9ef4964f9551b0fa89bbbc506f7660c055d74))
+* wire index.ts to consolidated config layout ([#10](https://github.com/gotgenes/pi-permission-system/issues/10)) ([e7f8e5f](https://github.com/gotgenes/pi-permission-system/commit/e7f8e5f2fb094f0d291561258190d1892a1e6856))
+
+
+### Documentation
+
+* plan config layout consolidation ([#10](https://github.com/gotgenes/pi-permission-system/issues/10)) ([eb2924d](https://github.com/gotgenes/pi-permission-system/commit/eb2924d57655d06f67891574839aebfa0586a43d))
+* **retro:** add retro notes for issue [#20](https://github.com/gotgenes/pi-permission-system/issues/20) ([4735f0c](https://github.com/gotgenes/pi-permission-system/commit/4735f0c646a0ede11c9a76083822969eb6ca4a8f))
+* update schema, example, and docs for consolidated config ([#10](https://github.com/gotgenes/pi-permission-system/issues/10)) ([39b5c01](https://github.com/gotgenes/pi-permission-system/commit/39b5c01de1c8c721e998b244e9c825a6eb05f858))
+
 ## [2.0.0](https://github.com/gotgenes/pi-permission-system/compare/v1.2.1...v2.0.0) (2026-05-03)
 
 

package/README.md

@@ -48,7 +48,7 @@ Pi auto-discovers extensions in these paths.
 
 ### Quick Start
 
-1. Create the global policy file at the Pi agent runtime root (default: `~/.pi/agent/pi-permissions.jsonc`, respects `PI_CODING_AGENT_DIR`):
+1. Create the global config file (default: `~/.pi/agent/extensions/pi-permission-system/config.json`, respects `PI_CODING_AGENT_DIR`):
 
 ```jsonc
 {
@@ -57,12 +57,12 @@ Pi auto-discovers extensions in these paths.
     "bash": "ask",
     "mcp": "ask",
     "skills": "ask",
-    "special": "ask",
+    "special": "ask"
   },
   "tools": {
     "read": "allow",
-    "write": "deny",
-  },
+    "write": "deny"
+  }
 }
 ```
 
@@ -100,36 +100,60 @@ The extension integrates via Pi's lifecycle hooks:
 
 ## Configuration
 
-### Extension Config File
+### Config File
+
+**Location:** one unified config file per scope, following the `pi-autoformat` convention:
 
-**Location:** global Pi extension config (default: `~/.pi/agent/extensions/pi-permission-system/config.json`, respects `PI_CODING_AGENT_DIR`)
+| Scope   | Path                                                                                              |
+| ------- | ------------------------------------------------------------------------------------------------- |
+| Global  | `~/.pi/agent/extensions/pi-permission-system/config.json` (respects `PI_CODING_AGENT_DIR`)        |
+| Project | `<cwd>/.pi/extensions/pi-permission-system/config.json`                                           |
 
-The extension creates this file automatically when it is missing. It controls only extension-local logging behavior:
+Project config overrides global config; per-agent frontmatter overrides both.
+Object-shaped fields (`defaultPolicy`, `tools`, `bash`, `mcp`, `skills`, `special`) use shallow-merge (later source wins per-key).
+Scalar fields (`debugLog`, `permissionReviewLog`, `yoloMode`) use simple replacement.
 
-```json
+The config file combines runtime knobs and permission policy in one object:
+
+```jsonc
 {
+  "$schema": "https://raw.githubusercontent.com/gotgenes/pi-permission-system/main/schemas/permissions.schema.json",
+
+  // Runtime knobs
   "debugLog": false,
   "permissionReviewLog": true,
-  "yoloMode": false
+  "yoloMode": false,
+
+  // Policy
+  "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" }
 }
 ```
 
+#### Runtime knobs
+
 | Key                   | Default | Description                                                                                             |
 | --------------------- | ------- | ------------------------------------------------------------------------------------------------------- |
 | `debugLog`            | `false` | Enables verbose diagnostic logging to `logs/pi-permission-system-debug.jsonl`                           |
 | `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 `~/.pi/agent/extensions/pi-permission-system/logs/`.
+No debug output is printed to the terminal.
 
-> **Note:** Permission-rule keys (`defaultPolicy`, `tools`, `bash`, `mcp`, `skills`, `special`, `external_directory`, `doom_loop`) placed in `config.json` are silently ignored — they belong in the policy file below.
-> The extension warns at startup when it detects misplaced keys.
+#### Policy sections
 
-### Global Policy File
-
-**Location:** global Pi policy file (default: `~/.pi/agent/pi-permissions.jsonc`, respects `PI_CODING_AGENT_DIR`)
-
-The policy file is a JSON object with these sections:
+The config file is a JSON object with these policy sections:
 
 | Section         | Description                                                                  |
 | --------------- | ---------------------------------------------------------------------------- |
@@ -169,21 +193,22 @@ permission:
 
 **Limitations:** The frontmatter parser is intentionally minimal. Use only `key: value` scalars and nested maps. Avoid arrays, multi-line scalars, and YAML anchors.
 
-### Project-Level Policy Files
+### Project-Level Config and Overrides
 
-The extension can also layer project-local permission files relative to the active session working directory:
+Project-local config uses the same format as the global config file.
+Per-agent overrides use YAML frontmatter in the project agents directory:
 
-| Scope                  | Path                                   |
-| ---------------------- | -------------------------------------- |
-| Project policy         | `<cwd>/.pi/agent/pi-permissions.jsonc` |
-| Project agent override | `<cwd>/.pi/agent/agents/<agent>.md`    |
+| Scope                  | Path                                                          |
+| ---------------------- | ------------------------------------------------------------- |
+| Project config         | `<cwd>/.pi/extensions/pi-permission-system/config.json`       |
+| Project agent override | `<cwd>/.pi/agent/agents/<agent>.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`.
+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`.
 
 **Precedence order:**
 
-1. Global policy file
-2. Project policy file
+1. Global config file
+2. Project config file
 3. Global agent frontmatter
 4. Project agent frontmatter
 
@@ -454,7 +479,7 @@ 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
+Actual global logs directory: $PI_CODING_AGENT_DIR/extensions/pi-permission-system/logs/ when PI_CODING_AGENT_DIR is 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
@@ -466,16 +491,17 @@ This makes it easy to verify which files the extension actually loaded:
 ```jsonc
 {
   "event": "config.resolved",
-  "extensionConfigPath": "/…/pi-permission-system/config.json",
-  "extensionConfigExists": true,
-  "globalConfigPath": "/…/.pi/agent/pi-permissions.jsonc",
-  "globalConfigExists": false,
-  "projectConfigPath": "/…/my-project/.pi/agent/pi-permissions.jsonc",
-  "projectConfigExists": true,
+  "globalConfigPath": "/…/.pi/agent/extensions/pi-permission-system/config.json",
+  "globalConfigExists": true,
+  "projectConfigPath": "/…/my-project/.pi/extensions/pi-permission-system/config.json",
+  "projectConfigExists": false,
   "agentsDir": "/…/.pi/agent/agents",
   "agentsDirExists": true,
   "projectAgentsDir": "/…/my-project/.pi/agent/agents",
   "projectAgentsDirExists": false,
+  "legacyGlobalPolicyDetected": false,
+  "legacyProjectPolicyDetected": false,
+  "legacyExtensionConfigDetected": false
 }
 ```
 
@@ -485,8 +511,10 @@ This makes it easy to verify which files the extension actually loaded:
 index.ts                    → Root Pi entrypoint shim
 src/
 ├── index.ts                → Extension bootstrap, permission checks, readable prompts, review logging, reload handling, and subagent forwarding
+├── config-loader.ts        → Unified config loader, merger, and legacy-path detection
+├── config-paths.ts         → Path derivation for global, project, and legacy config locations
 ├── config-reporter.ts      → Resolved config path reporting for diagnostic logs
-├── extension-config.ts     → Extension-local config loading and default creation
+├── extension-config.ts     → Runtime config normalization and defaults
 ├── 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
@@ -553,11 +581,40 @@ npx --yes ajv-cli@5 validate \
 
 ---
 
+## Migration from pre-v2 layout
+
+Before v2, config was split across two files:
+
+- Policy: `~/.pi/agent/pi-permissions.jsonc`
+- Runtime knobs: `<extension-install-dir>/config.json`
+
+These are now consolidated into one file.
+The extension detects legacy files and merges them with a warning for one release.
+To migrate manually:
+
+```bash
+# Move the global policy file
+mkdir -p ~/.pi/agent/extensions/pi-permission-system
+mv ~/.pi/agent/pi-permissions.jsonc ~/.pi/agent/extensions/pi-permission-system/config.json
+
+# If you had project-level policy:
+mkdir -p .pi/extensions/pi-permission-system
+mv .pi/agent/pi-permissions.jsonc .pi/extensions/pi-permission-system/config.json
+```
+
+Then add any runtime knobs (`debugLog`, `permissionReviewLog`, `yoloMode`) to the same file.
+The old extension-root `config.json` is no longer read from the install directory.
+
+> **Note:** Logs also moved from `<extension-install-dir>/logs/` to `~/.pi/agent/extensions/pi-permission-system/logs/`.
+> Old log files are not deleted or migrated — they remain readable but no new entries are appended.
+
+---
+
 ## Troubleshooting
 
 | Problem                              | Cause                                                      | Solution                                                                                                                                                             |
 | ------------------------------------ | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Config not applied (everything asks) | File not found or parse error                              | Verify the global Pi policy file (default: `~/.pi/agent/pi-permissions.jsonc`, respects `PI_CODING_AGENT_DIR`); check for trailing commas                            |
+| Config not applied (everything asks) | File not found or parse error                              | Verify the global config at `~/.pi/agent/extensions/pi-permission-system/config.json` (respects `PI_CODING_AGENT_DIR`); check for trailing commas                    |
 | Per-agent override not applied       | Frontmatter parsing issue                                  | Ensure `---` delimiters at file top; keep YAML simple; restart session                                                                                               |
 | Tool blocked as unregistered         | Unknown tool name                                          | Use a registered `mcp` tool for server tools: `{ "tool": "server:tool" }`                                                                                            |
 | `/skill:<name>` blocked              | Deny policy or confirmation unavailable                    | Check merged `skills` policy (global/project/agent layers). Active agent context is optional in the main session; `ask` still requires UI or forwarded confirmation. |

package/config/config.example.json

@@ -1,4 +1,10 @@
 {
+  "$schema": "https://raw.githubusercontent.com/gotgenes/pi-permission-system/main/schemas/permissions.schema.json",
+
+  "debugLog": false,
+  "permissionReviewLog": true,
+  "yoloMode": false,
+
   "defaultPolicy": {
     "tools": "ask",
     "bash": "ask",

package/package.json

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

package/schemas/permissions.schema.json

@@ -1,71 +1,169 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://pi-coding-agent.local/schemas/permissions.schema.json",
-  "title": "PI Permission Configuration",
+  "$id": "https://raw.githubusercontent.com/gotgenes/pi-permission-system/main/schemas/permissions.schema.json",
+  "title": "PI Permission System Configuration",
+  "description": "Unified config file combining runtime knobs and permission policy for pi-permission-system.",
+  "markdownDescription": "Unified config file combining runtime knobs and permission policy for [pi-permission-system](https://github.com/gotgenes/pi-permission-system).\n\nPlace at `~/.pi/agent/extensions/pi-permission-system/config.json` (global) or `<project>/.pi/extensions/pi-permission-system/config.json` (project).",
   "type": "object",
   "additionalProperties": false,
   "properties": {
     "$schema": {
+      "description": "JSON Schema URI for editor autocomplete and validation.",
       "type": "string"
     },
+    "debugLog": {
+      "description": "Write verbose permission-system diagnostics to the extension logs directory.",
+      "markdownDescription": "Write verbose permission-system diagnostics to `logs/pi-permission-system-debug.jsonl` under the extension config directory.",
+      "type": "boolean",
+      "default": false
+    },
+    "permissionReviewLog": {
+      "description": "Write permission request and decision audit events to the extension logs directory.",
+      "markdownDescription": "Write permission request and decision audit events to `logs/pi-permission-system-permission-review.jsonl` under the extension config directory.",
+      "type": "boolean",
+      "default": true
+    },
+    "yoloMode": {
+      "description": "Auto-approve ask-state permission checks, including subagent approval forwarding.",
+      "markdownDescription": "Auto-approve `ask`-state permission checks, including subagent approval forwarding.\n\n⚠️ **Use with caution** — this disables all interactive confirmation prompts.",
+      "type": "boolean",
+      "default": false
+    },
     "defaultPolicy": {
+      "description": "Fallback permission state per category when no specific rule matches.",
+      "markdownDescription": "Fallback permission state per category when no specific rule matches.\n\nAll fields default to `\"ask\"` when omitted.",
       "type": "object",
       "additionalProperties": false,
-      "required": ["tools", "bash", "mcp", "skills"],
       "properties": {
         "tools": {
-          "$ref": "#/$defs/permissionState"
+          "description": "Default permission for registered tools when no exact-name rule matches in the tools map.",
+          "markdownDescription": "Default permission for registered tools when no exact-name rule matches in the `tools` map.",
+          "$ref": "#/$defs/permissionState",
+          "default": "ask"
         },
         "bash": {
-          "$ref": "#/$defs/permissionState"
+          "description": "Default permission for bash commands when no pattern in the bash map matches.",
+          "markdownDescription": "Default permission for bash commands when no pattern in the `bash` map matches.",
+          "$ref": "#/$defs/permissionState",
+          "default": "ask"
         },
         "mcp": {
-          "$ref": "#/$defs/permissionState"
+          "description": "Default permission for MCP operations when no target pattern in the mcp map matches.",
+          "markdownDescription": "Default permission for MCP operations when no target pattern in the `mcp` map matches.",
+          "$ref": "#/$defs/permissionState",
+          "default": "ask"
         },
         "skills": {
-          "$ref": "#/$defs/permissionState"
+          "description": "Default permission for skill loading when no pattern in the skills map matches.",
+          "markdownDescription": "Default permission for skill loading when no pattern in the `skills` map matches.",
+          "$ref": "#/$defs/permissionState",
+          "default": "ask"
         },
         "special": {
-          "$ref": "#/$defs/permissionState"
+          "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.",
+          "$ref": "#/$defs/permissionState",
+          "default": "ask"
         }
       }
     },
     "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.",
-      "$ref": "#/$defs/permissionMap"
+      "markdownDescription": "Exact-name permissions for registered tools. Use this map for the canonical Pi built-ins (`read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`) and any extension-provided or third-party tools.\n\nNo wildcards — keys must match the registered tool name exactly.",
+      "$ref": "#/$defs/permissionMap",
+      "examples": [
+        {
+          "read": "allow",
+          "write": "deny",
+          "edit": "ask",
+          "mcp": "allow"
+        }
+      ]
     },
     "bash": {
-      "$ref": "#/$defs/permissionMap"
+      "description": "Wildcard pattern permissions for bash commands. Patterns use * globs matched against the full command string. Last matching rule wins.",
+      "markdownDescription": "Wildcard pattern permissions for bash commands. Patterns use `*` globs matched against the full command string.\n\n**Last matching rule wins** — put broad catch-all rules first and specific overrides after them.",
+      "$ref": "#/$defs/permissionMap",
+      "examples": [
+        {
+          "git status": "allow",
+          "git diff": "allow",
+          "git *": "ask",
+          "rm -rf *": "deny"
+        }
+      ]
     },
     "mcp": {
-      "description": "Pattern-based permissions for targets invoked through a registered `mcp` tool when available.",
-      "$ref": "#/$defs/permissionMap"
+      "description": "Pattern-based permissions for targets invoked through a registered mcp tool when available.",
+      "markdownDescription": "Pattern-based permissions for targets invoked through a registered `mcp` tool when available.\n\nTargets include server names (`myServer`), qualified tool names (`myServer:search`, `myServer_search`), and baseline operations (`mcp_status`, `mcp_list`, `mcp_connect`, `mcp_describe`, `mcp_search`).",
+      "$ref": "#/$defs/permissionMap",
+      "examples": [
+        {
+          "mcp_status": "allow",
+          "mcp_list": "allow",
+          "myServer:*": "ask",
+          "dangerousServer": "deny"
+        }
+      ]
     },
     "skills": {
-      "$ref": "#/$defs/permissionMap"
+      "description": "Wildcard pattern permissions for skill names. Controls which skills can be loaded or read from disk.",
+      "markdownDescription": "Wildcard pattern permissions for skill names. Controls which skills can be loaded or read from disk.\n\nUse `\"*\": \"ask\"` to require confirmation for all skills, or `\"dangerous-*\": \"deny\"` to block a family of skills.",
+      "$ref": "#/$defs/permissionMap",
+      "examples": [
+        {
+          "*": "ask",
+          "dangerous-*": "deny"
+        }
+      ]
     },
     "special": {
+      "description": "Reserved permission checks for special runtime behaviors.",
       "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`.",
+          "$ref": "#/$defs/permissionState"
+        },
+        "tool_call_limit": {
+          "description": "Deprecated and ignored. This key has no effect and should be removed from your config.",
+          "markdownDescription": "⚠️ **Deprecated and ignored.** This key has no effect and should be removed from your config.",
+          "deprecated": true,
           "$ref": "#/$defs/permissionState"
         }
       }
     }
   },
-  "required": ["defaultPolicy"],
   "$defs": {
     "permissionState": {
-      "type": "string",
-      "enum": ["allow", "deny", "ask"]
+      "description": "A permission decision: allow (permit silently), deny (block with error), or ask (prompt the user for confirmation).",
+      "oneOf": [
+        {
+          "const": "allow",
+          "description": "Permit the action silently with no user interaction."
+        },
+        {
+          "const": "deny",
+          "description": "Block the action with an error message. The agent is told not to retry."
+        },
+        {
+          "const": "ask",
+          "description": "Prompt the user for confirmation via the interactive UI before proceeding."
+        }
+      ]
     },
     "permissionMap": {
+      "description": "A map of name or wildcard patterns to permission states. Keys are matched against the relevant target (tool name, bash command, MCP target, or skill name).",
+      "markdownDescription": "A map of name or wildcard patterns to permission states.\n\nKeys are matched against the relevant target. Use `*` for wildcard matching. When multiple patterns match, the **last matching rule wins**.",
       "type": "object",
       "propertyNames": {
+        "description": "A non-empty pattern string. Use * for wildcard matching.",
         "type": "string",
         "minLength": 1
       },

package/src/active-agent.ts

@@ -0,0 +1,58 @@
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+/**
+ * Matches the `<active_agent name="...">` tag injected by pi-agent-router
+ * into the system prompt to identify which agent definition is active.
+ */
+export const ACTIVE_AGENT_TAG_REGEX =
+  /<active_agent\s+name=["']([^"']+)["'][^>]*>/i;
+
+export function normalizeAgentName(value: unknown): string | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+}
+
+export function getActiveAgentName(ctx: ExtensionContext): string | null {
+  const entries = ctx.sessionManager.getEntries();
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i] as {
+      type: string;
+      customType?: string;
+      data?: unknown;
+    };
+    if (entry.type !== "custom" || entry.customType !== "active_agent") {
+      continue;
+    }
+
+    const data = entry.data as { name?: unknown } | undefined;
+    const normalizedName = normalizeAgentName(data?.name);
+    if (normalizedName) {
+      return normalizedName;
+    }
+
+    if (data?.name === null) {
+      return null;
+    }
+  }
+
+  return null;
+}
+
+export function getActiveAgentNameFromSystemPrompt(
+  systemPrompt: string | undefined,
+): string | null {
+  if (!systemPrompt) {
+    return null;
+  }
+
+  const match = systemPrompt.match(ACTIVE_AGENT_TAG_REGEX);
+  if (!match?.[1]) {
+    return null;
+  }
+
+  return normalizeAgentName(match[1]);
+}