@gotgenes/pi-permission-system 1.2.1 → 3.0.0

package/CHANGELOG.md

@@ -5,6 +5,50 @@ 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.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)
+
+
+### ⚠ BREAKING CHANGES
+
+* the pi-permission-system:permission-request event channel is no longer emitted. No known consumers exist; the type was never exported. Re-adding with a proper public contract is tracked
+
+### Features
+
+* add /build-plan prompt template for non-TDD plans ([e98f13c](https://github.com/gotgenes/pi-permission-system/commit/e98f13c2ef32f51edda58ea065635bef31365baa))
+* delete permission-request event channel ([#20](https://github.com/gotgenes/pi-permission-system/issues/20)) ([6a41cfa](https://github.com/gotgenes/pi-permission-system/commit/6a41cfadc56e709d255538f63ff63d587e1b64f3))
+
+
+### Documentation
+
+* plan delete permission-request event channel ([#20](https://github.com/gotgenes/pi-permission-system/issues/20)) ([e202350](https://github.com/gotgenes/pi-permission-system/commit/e2023509f9ab849f5a1d8bc28a5705b2898b912b))
+* remove event channel from preserved-identity list ([#20](https://github.com/gotgenes/pi-permission-system/issues/20)) ([52299a2](https://github.com/gotgenes/pi-permission-system/commit/52299a27aeaed6e35849878fa224d8a78dcf0f6d))
+* **retro:** add retro notes for issue [#22](https://github.com/gotgenes/pi-permission-system/issues/22) ([55629fe](https://github.com/gotgenes/pi-permission-system/commit/55629fed16b6d73b6d7b02698227e2adab7acd3e))
+* update copyright in license ([b27994e](https://github.com/gotgenes/pi-permission-system/commit/b27994e7d67863ce8b28aa6bd680b60bc700d66d))
+
 ## [1.2.1](https://github.com/gotgenes/pi-permission-system/compare/v1.2.0...v1.2.1) (2026-05-03)
 
 

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 MasuRii
+Copyright (c) 2026 MasuRii and Christopher D. Lasher
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -6,7 +6,7 @@ Permission enforcement extension for the Pi coding agent that provides centraliz
 
 > **Fork notice:** This package is a friendly fork of [MasuRii/pi-permission-system](https://github.com/MasuRii/pi-permission-system), published to npm as `@gotgenes/pi-permission-system`.
 > This fork diverges from upstream in config layout (#10).
-> The `/permission-system` slash command and `pi-permission-system:permission-request` event channel names are preserved; the config and log paths are not.
+> The `/permission-system` slash command name is preserved; the config and log paths are not.
 
 ## Features
 
@@ -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": "1.2.1",
+  "version": "3.0.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "main": "./index.ts",

package/schemas/permissions.schema.json

@@ -1,17 +1,32 @@
 {
   "$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.",
   "type": "object",
   "additionalProperties": false,
   "properties": {
     "$schema": {
       "type": "string"
     },
+    "debugLog": {
+      "description": "Write verbose permission-system diagnostics to the extension logs directory.",
+      "type": "boolean",
+      "default": false
+    },
+    "permissionReviewLog": {
+      "description": "Write permission request and decision audit events to the extension logs directory.",
+      "type": "boolean",
+      "default": true
+    },
+    "yoloMode": {
+      "description": "Auto-approve ask-state permission checks, including subagent approval forwarding.",
+      "type": "boolean",
+      "default": false
+    },
     "defaultPolicy": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["tools", "bash", "mcp", "skills"],
       "properties": {
         "tools": {
           "$ref": "#/$defs/permissionState"
@@ -57,7 +72,6 @@
       }
     }
   },
-  "required": ["defaultPolicy"],
   "$defs": {
     "permissionState": {
       "type": "string",