pi-permission-system 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -5,6 +5,45 @@ 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).
 
+## [0.4.2] - 2026-04-20
+
+### Added
+- Added project-level permission layering from the active session workspace via `<cwd>/.pi/agent/pi-permissions.jsonc`
+- Added project-level per-agent overrides via `<cwd>/.pi/agent/agents/<agent>.md` (thanks to @Talia-12 for PR #7)
+- Added reload-aware permission manager refresh paths so policy caches are rebuilt when Pi reload events occur
+- Added a dedicated `tests/` directory with modular test entrypoints and a shared test harness
+- Added before-agent-start caching module to dedupe unchanged active-tool exposure and prompt state across `before_agent_start` lifecycle invocations
+- Added `PermissionPromptDecision` type with `state` and `denialReason` fields for richer permission prompt resolution
+- Added `getPolicyCacheStamp()` method to `PermissionManager` for cache invalidation tracking
+
+### Changed
+- Global path resolution now follows Pi's `getAgentDir()` helper, so global config, agents, sessions, and logs respect `PI_CODING_AGENT_DIR` (thanks to @jvortmann for PR #6)
+- Updated `@mariozechner/pi-coding-agent` and `@mariozechner/pi-tui` peer dependencies to `^0.67.68`
+- Updated TypeScript project configuration and npm scripts to run tests from `tests/` instead of `src/`
+- Updated README documentation for project-level policy files, yolo mode config, test layout, and `PI_CODING_AGENT_DIR`
+- Permission prompts and forwarding now return `PermissionPromptDecision` instead of boolean for richer resolution tracking
+- Permission denial messages now include user-provided denial reasons when available
+
+### Removed
+- Removed the legacy packaged `asset/` directory because the README now uses externally hosted images instead of repository-bundled screenshots
+
+### Fixed
+- `/skill:<name>` permission handling now falls back to the current merged skill policy when no active agent context is available in the main session (thanks to @NSBeidou and @hidromagnetismo for reporting the issue)
+- Skill denial messaging now reflects whether the block came from an agent-specific rule or the merged policy without agent context
+
+### Tests
+- Added coverage for project-level precedence across global, project, system-agent, and project-agent layers
+- Added coverage for resolving config from `PI_CODING_AGENT_DIR`
+- Added coverage for before-agent-start cache key generation and state deduplication
+- Added coverage for cache invalidation on permission policy changes
+
+## [0.4.1] - 2026-04-01
+
+### Changed
+- Updated npm keywords for improved discoverability (`pi-coding-agent`, `coding-agent`, `access-control`, `authorization`, `security`)
+- Updated README permission prompt example image
+- Added Related Pi Extensions cross-linking section to README
+
 ## [0.4.0] - 2026-04-01
 
 ### Added

package/README.md

@@ -1,11 +1,12 @@
 # 🔐 pi-permission-system
 
-[![Version](https://img.shields.io/badge/version-0.3.1-blue.svg)](package.json)
+[![Version](https://img.shields.io/badge/version-0.4.2-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.
 
-![Permission Prompt Example](https://raw.githubusercontent.com/MasuRii/pi-permission-system/main/asset/pi-permission-system.png)
+<img width="1360" height="752" alt="image" src="https://github.com/user-attachments/assets/3e85190a-17fa-4d94-ac8e-efa54337df5d" />
+
 
 ## Features
 
@@ -25,18 +26,20 @@ Permission enforcement extension for the Pi coding agent that provides centraliz
 
 Place this folder in one of the following locations:
 
-| Scope   | Path                                          |
-|---------|-----------------------------------------------|
-| Global  | `~/.pi/agent/extensions/pi-permission-system` |
-| Project | `.pi/extensions/pi-permission-system`         |
+| Scope   | Path |
+|---------|------|
+| Global default | `~/.pi/agent/extensions/pi-permission-system` (respects `PI_CODING_AGENT_DIR`) |
+| Project | `.pi/extensions/pi-permission-system` |
 
 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.
+
 ## Usage
 
 ### Quick Start
 
-1. Create the global policy file at `~/.pi/agent/pi-permissions.jsonc`:
+1. Create the global policy file at the Pi agent runtime root (default: `~/.pi/agent/pi-permissions.jsonc`, respects `PI_CODING_AGENT_DIR`):
 
 ```jsonc
 {
@@ -81,20 +84,20 @@ The extension integrates via Pi's lifecycle hooks:
 - 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
 - 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
 
 ## Configuration
 
 ### Extension Config File
 
-**Location:** `~/.pi/agent/extensions/pi-permission-system/config.json`
+**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:
 
 ```json
 {
   "debugLog": false,
-  "permissionReviewLog": true
+  "permissionReviewLog": true,
+  "yoloMode": false
 }
 ```
 
@@ -102,12 +105,13 @@ The extension creates this file automatically when it is missing. It controls on
 |-----|---------|-------------|
 | `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.
 
 ### Global Policy File
 
-**Location:** `~/.pi/agent/pi-permissions.jsonc`
+**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:
 
@@ -122,9 +126,9 @@ The policy file is a JSON object with these sections:
 
 > **Note:** Trailing commas are **not** supported. If parsing fails, the extension falls back to `ask` for all categories.
 
-### Per-Agent Overrides
+### Global Per-Agent Overrides
 
-Override global permissions for specific agents via YAML frontmatter in `~/.pi/agent/agents/<agent>.md`:
+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`):
 
 ```yaml
 ---
@@ -145,12 +149,29 @@ permission:
 ---
 ```
 
-**Precedence:** Agent frontmatter overrides global config (shallow-merged per section).
-
 **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.
 
+### Project-Level Policy Files
+
+The extension can also layer project-local permission files relative to the active session working directory:
+
+| Scope | Path |
+|-------|------|
+| Project policy | `<cwd>/.pi/agent/pi-permissions.jsonc` |
+| 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`.
+
+**Precedence order:**
+1. Global policy file
+2. Project policy file
+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.
+
 ---
 
 ## Policy Reference
@@ -255,7 +276,7 @@ A registered `mcp` tool can use `tools.mcp` as an entry permission point. This p
 This is useful for per-agent configurations where you want to grant MCP access broadly:
 
 ```yaml
-# In ~/.pi/agent/agents/researcher.md
+# In the global Pi agents directory (default: ~/.pi/agent/agents/researcher.md; respects PI_CODING_AGENT_DIR)
 ---
 name: researcher
 permission:
@@ -352,7 +373,7 @@ Reserved permission checks:
 
 ### Per-Agent Lockdown
 
-In `~/.pi/agent/agents/reviewer.md`:
+In the global Pi agents directory (default: `~/.pi/agent/agents/reviewer.md`, respects `PI_CODING_AGENT_DIR`):
 
 ```yaml
 ---
@@ -380,7 +401,8 @@ This keeps `ask` policies usable even when the original permission check happens
 When the extension prompts, denies, or forwards permission requests, it can append structured JSONL entries under:
 
 ```text
-~/.pi/agent/extensions/pi-permission-system/logs/
+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
 ```
 
 - `pi-permission-system-permission-review.jsonl` — enabled by default for permission review/audit history
@@ -391,16 +413,19 @@ When the extension prompts, denies, or forwards permission requests, it can appe
 ```
 index.ts                    → Root Pi entrypoint shim
 src/
-├── index.ts                → Extension bootstrap, permission checks, review logging, and subagent forwarding
+├── index.ts                → Extension bootstrap, permission checks, 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   → Policy loading, merging, and resolution with caching
+├── permission-manager.ts   → Global/project 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
+└── types.ts                → TypeScript type definitions
+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
 schemas/
 └── permissions.schema.json → JSON Schema for policy validation
 config/
@@ -455,10 +480,10 @@ npx --yes ajv-cli@5 validate \
 
 | Problem | Cause | Solution |
 |---------|-------|----------|
-| Config not applied (everything asks) | File not found or parse error | Verify file at `~/.pi/agent/pi-permissions.jsonc`; check for trailing commas |
+| 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 |
 | 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 | Missing context or deny policy | Requires active agent context; `ask` behaves as block in headless mode |
+| `/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. |
 
 ---
 
@@ -467,12 +492,19 @@ npx --yes ajv-cli@5 validate \
 ```bash
 npm run build    # Compile TypeScript
 npm run lint     # Run linter (uses build)
-npm run test     # Run tests
+npm run test     # Run tests from ./tests
 npm run check    # Run lint + test
 ```
 
 ---
 
+## Related Pi Extensions
+
+- [pi-multi-auth](https://github.com/MasuRii/pi-multi-auth) — Multi-provider credential management and quota-aware rotation
+- [pi-tool-display](https://github.com/MasuRii/pi-tool-display) — Compact tool rendering and diff visualization
+- [pi-rtk-optimizer](https://github.com/MasuRii/pi-rtk-optimizer) — RTK command rewriting and output compaction
+- [pi-MUST-have-extension](https://github.com/MasuRii/pi-MUST-have-extension) — RFC 2119 keyword normalization for prompts
+
 ## License
 
 [MIT](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-permission-system",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "main": "./index.ts",
@@ -10,10 +10,10 @@
   "files": [
     "index.ts",
     "src",
+    "tests",
     "config.json",
     "config/config.example.json",
     "schemas/permissions.schema.json",
-    "asset",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -21,16 +21,20 @@
   "scripts": {
     "build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
     "lint": "npm run build",
-    "test": "bun ./src/test.ts && bun ./src/config-modal-test.ts",
+    "test": "bun ./tests/permission-system.test.ts && bun ./tests/config-modal.test.ts",
     "check": "npm run lint && npm run test"
   },
   "keywords": [
     "pi-package",
     "pi",
     "pi-extension",
+    "pi-coding-agent",
+    "coding-agent",
     "permissions",
     "policy",
-    "coding-agent"
+    "access-control",
+    "authorization",
+    "security"
   ],
   "author": "MasuRii",
   "license": "MIT",
@@ -54,8 +58,8 @@
     ]
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "^0.64.0",
-    "@mariozechner/pi-tui": "^0.64.0",
+    "@mariozechner/pi-coding-agent": "^0.67.68",
+    "@mariozechner/pi-tui": "^0.67.68",
     "@sinclair/typebox": "^0.34.49"
   }
 }

package/src/before-agent-start-cache.ts

@@ -0,0 +1,37 @@
+export interface BeforeAgentStartPromptStateInput {
+  agentName: string | null;
+  cwd: string;
+  permissionStamp: string;
+  systemPrompt: string;
+  allowedToolNames: readonly string[];
+}
+
+function normalizeAgentName(agentName: string | null): string {
+  return agentName ?? "";
+}
+
+function normalizePrompt(prompt: string): string {
+  return prompt.replace(/\r\n/g, "\n");
+}
+
+function createCacheKey(parts: readonly unknown[]): string {
+  return JSON.stringify(parts);
+}
+
+export function createActiveToolsCacheKey(allowedToolNames: readonly string[]): string {
+  return createCacheKey(allowedToolNames);
+}
+
+export function createBeforeAgentStartPromptStateKey(input: BeforeAgentStartPromptStateInput): string {
+  return createCacheKey([
+    normalizeAgentName(input.agentName),
+    input.cwd,
+    input.permissionStamp,
+    createActiveToolsCacheKey(input.allowedToolNames),
+    normalizePrompt(input.systemPrompt),
+  ]);
+}
+
+export function shouldApplyCachedAgentStartState(previousKey: string | null, nextKey: string): boolean {
+  return previousKey !== nextKey;
+}