pi-permission-system 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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.2.2] - 2026-03-13
+
+### Changed
+- Removed delegation task restriction logic — the `task` tool is no longer restricted to orchestrator agent only
+- Simplified tool permission lookup to use explicit `tools` entries for arbitrary registered tools instead of MCP fallback
+- Renamed `TOOL_PERMISSION_NAMES` to `BUILT_IN_TOOL_PERMISSION_NAMES` to clarify it covers only canonical Pi tools
+- Updated schema descriptions for `tools` and `mcp` fields to guide configuration usage
+
+### Removed
+- Removed delegation-specific permission checks (`isDelegationAllowedAgent`, `getDelegationBlockReason`) from permission evaluation
+
+### Tests
+- Added comprehensive test coverage for tool permission lookup behavior
+
+## [0.2.1] - 2026-03-13
+
+### Added
+- Extension configuration system (`config.json`) with `debugLog` and `permissionReviewLog` options
+- JSONL debug logging to `logs/pi-permission-system-debug.jsonl` when `debugLog` is enabled
+- JSONL permission review logging to `logs/pi-permission-system-permission-review.jsonl` for auditing
+- Permission request event emission on `pi-permission-system:permission-request` channel for external consumers
+- New `extension-config.ts` module for config file management and path resolution
+- New `logging.ts` module with `createPermissionSystemLogger` for structured log output
+
+### Changed
+- Replaced `console.warn`/`console.error` calls with structured logging to file
+- Permission forwarding now logs request creation, response received, timeout, and user prompts
+- Updated README documentation to cover extension config, logging, and event emission
+
 ## [0.2.0] - 2026-03-12
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # 🔐 pi-permission-system
 
-[![Version](https://img.shields.io/badge/version-0.2.0-blue.svg)](package.json)
+[![Version](https://img.shields.io/badge/version-0.2.1-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.
@@ -17,6 +17,8 @@ Permission enforcement extension for the Pi coding agent that provides centraliz
 - **Skill Protection** — Controls which skills can be loaded or read from disk
 - **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
+- **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
 
 ## Installation
@@ -77,26 +79,46 @@ 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
-- The `task` delegation tool is restricted to the `orchestrator` agent only
+- 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`
+
+The extension creates this file automatically when it is missing. It controls only extension-local logging behavior:
+
+```json
+{
+  "debugLog": false,
+  "permissionReviewLog": true
+}
+```
+
+| 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` |
+
+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`
 
 The policy file is a JSON object with these sections:
 
-| Section         | Description                              |
-|-----------------|------------------------------------------|
-| `defaultPolicy` | Fallback permissions per category        |
-| `tools`         | Built-in tool permissions                |
-| `bash`          | Command pattern permissions              |
-| `mcp`           | MCP server/tool permissions              |
-| `skills`        | Skill name pattern permissions           |
-| `special`       | Reserved permission checks               |
+| Section         | Description                                         |
+|-----------------|-----------------------------------------------------|
+| `defaultPolicy` | Fallback permissions per category                   |
+| `tools`         | Exact-name 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                      |
+| `special`       | Reserved permission checks                          |
 
 > **Note:** Trailing commas are **not** supported. If parsing fails, the extension falls back to `ask` for all categories.
 
@@ -125,7 +147,7 @@ permission:
 
 **Precedence:** Agent frontmatter overrides global config (shallow-merged per section).
 
-**MCP behavior:** `permission.tools.mcp` is the coarse entry/fallback permission for the built-in `mcp` tool. More specific `permission.mcp` target rules override that fallback when they match.
+**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.
 
@@ -151,33 +173,34 @@ Sets fallback permissions when no specific rule matches:
 
 ### `tools`
 
-Controls built-in tools by exact name (no wildcards):
+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.
 
-| Tool    | Description                    |
-|---------|--------------------------------|
-| `bash`  | Shell command execution        |
-| `read`  | File reading                   |
-| `write` | File creation/overwriting      |
-| `edit`  | Surgical file edits            |
-| `grep`  | Pattern searching              |
-| `find`  | File discovery                 |
-| `ls`    | Directory listing              |
-| `mcp`   | MCP proxy tool entry/fallback  |
+| Tool name example     | Description |
+|-----------------------|-------------|
+| `bash`                | Shell command execution (tool-level fallback before `bash` pattern rules) |
+| `read` / `write`      | Canonical Pi built-in file tools |
+| `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 |
 
 ```jsonc
 {
   "tools": {
     "read": "allow",
     "write": "deny",
-    "edit": "deny",
-    "mcp": "allow"
+    "mcp": "allow",
+    "third_party_tool": "ask"
   }
 }
 ```
 
+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.
+
 > **Note:** Setting `tools.bash` affects the *default* for bash commands, but `bash` patterns can provide command-level overrides.
 >
-> **Note:** Setting `tools.mcp` controls coarse access to the built-in `mcp` tool. Specific `mcp` rules still override it when a target pattern matches.
+> **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:** 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`
 
@@ -219,7 +242,7 @@ MCP permissions match against derived targets from tool input. These rules are m
 
 #### MCP Tool Fallback via `tools.mcp`
 
-The `mcp` built-in tool can use `tools.mcp` as an entry permission point. This provides a fallback when no specific MCP pattern matches:
+A registered `mcp` tool can use `tools.mcp` as an entry permission point. This provides a fallback when no specific MCP pattern matches:
 
 ```jsonc
 {
@@ -352,12 +375,25 @@ When a delegated or routed subagent runs without direct UI access, `ask` permiss
 
 This keeps `ask` policies usable even when the original permission check happens inside a non-UI execution context.
 
+### Logging
+
+When the extension prompts, denies, or forwards permission requests, it can append structured JSONL entries under:
+
+```text
+~/.pi/agent/extensions/pi-permission-system/logs/
+```
+
+- `pi-permission-system-permission-review.jsonl` — enabled by default for permission review/audit history
+- `pi-permission-system-debug.jsonl` — disabled by default and intended for troubleshooting
+
 ### Architecture
 
 ```
 index.ts                    → Root Pi entrypoint shim
 src/
-├── index.ts                → Extension bootstrap, permission checks, and subagent forwarding
+├── index.ts                → Extension bootstrap, permission checks, review logging, 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
 ├── bash-filter.ts          → Bash command wildcard pattern matching
 ├── wildcard-matcher.ts     → Shared wildcard pattern compilation and matching
@@ -366,9 +402,9 @@ src/
 ├── types.ts                → TypeScript type definitions
 └── test.ts                 → Test runner
 schemas/
-└── permissions.schema.json → JSON Schema for config validation
+└── permissions.schema.json → JSON Schema for policy validation
 config/
-└── config.example.json     → Starter configuration template
+└── config.example.json     → Starter global policy template
 ```
 
 #### Module Organization
@@ -421,7 +457,7 @@ npx --yes ajv-cli@5 validate \
 |---------|-------|----------|
 | Config not applied (everything asks) | File not found or parse error | Verify file at `~/.pi/agent/pi-permissions.jsonc`; 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 built-in `mcp` tool for server tools: `{ "tool": "server:tool" }` |
+| 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 |
 
 ---

package/config.json

@@ -0,0 +1,4 @@
+{
+  "debugLog": false,
+  "permissionReviewLog": true
+}

package/package.json

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

package/schemas/permissions.schema.json

@@ -31,12 +31,14 @@
       }
     },
     "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"
     },
     "bash": {
       "$ref": "#/$defs/permissionMap"
     },
     "mcp": {
+      "description": "Pattern-based permissions for targets invoked through a registered `mcp` tool when available.",
       "$ref": "#/$defs/permissionMap"
     },
     "skills": {

package/src/extension-config.ts

@@ -0,0 +1,106 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { toRecord } from "./common.js";
+
+export const EXTENSION_ID = "pi-permission-system";
+
+export interface PermissionSystemExtensionConfig {
+  debugLog: boolean;
+  permissionReviewLog: boolean;
+}
+
+export interface PermissionSystemConfigLoadResult {
+  config: PermissionSystemExtensionConfig;
+  created: boolean;
+  warning?: string;
+}
+
+export const DEFAULT_EXTENSION_CONFIG: PermissionSystemExtensionConfig = {
+  debugLog: false,
+  permissionReviewLog: true,
+};
+
+export function resolveExtensionRoot(moduleUrl = import.meta.url): string {
+  return join(dirname(fileURLToPath(moduleUrl)), "..");
+}
+
+export const EXTENSION_ROOT = resolveExtensionRoot();
+export const CONFIG_PATH = join(EXTENSION_ROOT, "config.json");
+export const LOGS_DIR = join(EXTENSION_ROOT, "logs");
+export const DEBUG_LOG_PATH = join(LOGS_DIR, `${EXTENSION_ID}-debug.jsonl`);
+export const PERMISSION_REVIEW_LOG_PATH = join(LOGS_DIR, `${EXTENSION_ID}-permission-review.jsonl`);
+
+function cloneDefaultConfig(): PermissionSystemExtensionConfig {
+  return {
+    debugLog: DEFAULT_EXTENSION_CONFIG.debugLog,
+    permissionReviewLog: DEFAULT_EXTENSION_CONFIG.permissionReviewLog,
+  };
+}
+
+function createDefaultConfigContent(): string {
+  return `${JSON.stringify(DEFAULT_EXTENSION_CONFIG, null, 2)}\n`;
+}
+
+function normalizeConfig(raw: unknown): PermissionSystemExtensionConfig {
+  const record = toRecord(raw);
+  return {
+    debugLog: record.debugLog === true,
+    permissionReviewLog: record.permissionReviewLog !== false,
+  };
+}
+
+function ensureConfigDirectory(configPath: string): void {
+  mkdirSync(dirname(configPath), { recursive: true });
+}
+
+export function ensurePermissionSystemConfig(configPath = CONFIG_PATH): { created: boolean; warning?: string } {
+  if (existsSync(configPath)) {
+    return { created: false };
+  }
+
+  try {
+    ensureConfigDirectory(configPath);
+    writeFileSync(configPath, createDefaultConfigContent(), "utf-8");
+    return { created: true };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      created: false,
+      warning: `Failed to initialize permission-system config at '${configPath}': ${message}`,
+    };
+  }
+}
+
+export function loadPermissionSystemConfig(configPath = CONFIG_PATH): PermissionSystemConfigLoadResult {
+  const ensureResult = ensurePermissionSystemConfig(configPath);
+
+  try {
+    const raw = readFileSync(configPath, "utf-8");
+    const parsed = JSON.parse(raw) as unknown;
+    const config = normalizeConfig(parsed);
+    return {
+      config,
+      created: ensureResult.created,
+      warning: ensureResult.warning,
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      config: cloneDefaultConfig(),
+      created: ensureResult.created,
+      warning: ensureResult.warning ?? `Failed to read permission-system config at '${configPath}': ${message}`,
+    };
+  }
+}
+
+export function ensurePermissionSystemLogsDirectory(logsDir = LOGS_DIR): string | undefined {
+  try {
+    mkdirSync(logsDir, { recursive: true });
+    return undefined;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return `Failed to create permission-system log directory '${logsDir}': ${message}`;
+  }
+}