pi-permission-system 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-05-26
+
+### Added
+- Added `hasAllowedSkills()` method to `PermissionManager` that checks whether the resolved permission config has any explicitly allowed skills, returning true when the default skills policy is not "deny" or at least one individual skill entry has state "allow".
+- Added skill-scoped `read` tool exception so the `read` tool remains exposed to agents with explicitly allowed skills even when the `read` tool-level permission is "deny", enabling skill file access without granting unrestricted read access.
+
+### Changed
+- Widened Pi peer dependency ranges to `^0.74.0 || ^0.75.0` and bumped dev dependencies to `^0.75.5`.
+
 ## [0.5.0] - 2026-05-22
 
 ### Added

package/README.md

@@ -99,8 +99,7 @@ If you are coming from OpenCode, you usually do **not** need to rewrite your who
 - **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, with raw bash command text redacted unless `logPlaintextBashCommands` is enabled
-- **Optional Debug Logging** — Keeps verbose extension diagnostics in a separate file when enabled in `config.json`
+- **File-Based Debug Logging** — Writes verbose diagnostics and permission request/denial review entries to one debug file when enabled in `config.json`, including the responsible agent and raw tool-call input
 - **JSON Schema Validation** — Full schema for editor autocomplete and config validation
 - **External Directory Guard** — Enforces `special.external_directory` for path-bearing file tools that target paths outside the active working directory
 
@@ -159,6 +158,8 @@ All permissions use one of three states:
 | `deny`  | Blocks the action with an error message     |
 | `ask`   | Prompts the user for confirmation via UI    |
 
+When an `ask` permission prompts, the confirmation UI offers `Allow Once`, `Allow Always`, `Reject`, and `Reject with Reason`. `Allow Once` records an in-memory approval for the current runtime, `Allow Always` persists a matching approval rule for future sessions, and rejected decisions can include an optional reason shown back to the agent.
+
 ### Pi Integration Hooks
 
 The extension integrates via Pi's lifecycle hooks:
@@ -175,7 +176,7 @@ The extension integrates via Pi's lifecycle hooks:
 - 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 redacted prompt/input metadata for auditing; raw bash command text is omitted unless `logPlaintextBashCommands` is enabled.
+- Debug review entries include the responsible agent, raw prompt, raw tool-call input, command, target, and decision metadata for auditing.
 - 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`
 - `read` calls under global and project Pi skill directories are checked against `skills` policy even when the skill entry is inferred from the path rather than an active prompt block.
 - Structured edit payloads are summarized by operation and line count in prompts so permission decisions do not require raw multiline JSON.
@@ -188,25 +189,21 @@ The extension integrates via Pi's lifecycle hooks:
 
 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:
+The extension creates this file automatically when it is missing. It controls extension-local debug logging behavior and yolo mode defaults:
 
 ```json
 {
-  "debugLog": false,
-  "permissionReviewLog": true,
-  "logPlaintextBashCommands": false,
+  "debug": false,
   "yoloMode": false
 }
 ```
 
 | 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` |
-| `logPlaintextBashCommands` | `false` | Opts in to storing raw bash command strings in review logs; when disabled, bash commands are redacted and only safe metadata is retained |
+| `debug` | `false` | Enables verbose diagnostics and permission review entries in `logs/pi-permission-system-debug.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 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.
+Debug output writes only under the extension directory by default. Set `PI_PERMISSION_SYSTEM_LOGS_DIR` to redirect the debug file to a specific directory. No debug output is printed to the terminal.
 
 ### Runtime YOLO Control
 
@@ -554,21 +551,20 @@ Actual global logs directory: $PI_CODING_AGENT_DIR/extensions/pi-permission-syst
 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 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
+- `pi-permission-system-debug.jsonl` — disabled by default; includes troubleshooting diagnostics and permission review/audit entries with responsible agent metadata, raw prompts, raw tool-call inputs, commands, targets, and decisions
 
 ### Architecture
 
 ```
 index.ts                         → Root Pi entrypoint shim
 src/
-├── index.ts                     → Extension bootstrap, permission checks, readable prompts, review logging, reload handling, and subagent forwarding
+├── index.ts                     → Extension bootstrap, permission checks, readable prompts, debug review entries, 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
+├── logging.ts                   → File-only debug 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
@@ -653,13 +649,13 @@ npx --yes ajv-cli@5 validate \
 
 ## Development
 
-Runtime checks require Node.js 20+; the test suite requires Bun 1.1+.
+Runtime checks require Node.js 20+; the test suite runs through Node.js with tsx and Node's experimental test module mocks (validated on Node.js 24).
 
 ```bash
 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 test               # Run Node/tsx tests from ./tests
 npm run check              # Run static, artifact, and test checks
 ```
 

package/package.json

@@ -1,71 +1,71 @@
-{
-  "name": "pi-permission-system",
-  "version": "0.5.0",
-  "description": "Permission enforcement extension for the Pi coding agent.",
-  "type": "module",
-  "main": "./index.ts",
-  "exports": {
-    ".": "./index.ts"
-  },
-  "files": [
-    "index.ts",
-    "src",
-    "tests",
-    "config/config.example.json",
-    "schemas/permissions.schema.json",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "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 validate:artifacts && npm run test"
-  },
-  "keywords": [
-    "pi-package",
-    "pi",
-    "pi-extension",
-    "pi-coding-agent",
-    "coding-agent",
-    "permissions",
-    "policy",
-    "access-control",
-    "authorization",
-    "security"
-  ],
-  "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",
-    "bun": ">=1.1.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ]
-  },
-  "peerDependencies": {
-    "@sinclair/typebox": "^0.34.49",
-    "@earendil-works/pi-ai": "^0.75.4",
-    "@earendil-works/pi-coding-agent": "^0.75.4",
-    "@earendil-works/pi-tui": "^0.75.4"
-  },
-  "dependencies": {
-    "jsonc-parser": "^3.3.1"
-  }
-}
+{
+  "name": "pi-permission-system",
+  "version": "0.7.0",
+  "description": "Permission enforcement extension for the Pi coding agent.",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "tests",
+    "config/config.example.json",
+    "schemas/permissions.schema.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "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 validate:artifacts && npm run test"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "pi-coding-agent",
+    "coding-agent",
+    "permissions",
+    "policy",
+    "access-control",
+    "authorization",
+    "security"
+  ],
+  "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",
+    "bun": ">=1.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@sinclair/typebox": "^0.34.49",
+    "@earendil-works/pi-ai": "^0.74.0 || ^0.75.0",
+    "@earendil-works/pi-coding-agent": "^0.74.0 || ^0.75.0",
+    "@earendil-works/pi-tui": "^0.74.0 || ^0.75.0"
+  },
+  "dependencies": {
+    "jsonc-parser": "^3.3.1"
+  }
+}

package/src/config-modal.ts

@@ -1,156 +1,136 @@
-import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import type { SettingItem } from "@earendil-works/pi-tui";
-
-import type { PermissionSystemExtensionConfig } from "./extension-config.js";
-import { ZellijModal, ZellijSettingsModal } from "./zellij-modal.js";
-
-interface PermissionSystemConfigController {
-  getConfig(): PermissionSystemExtensionConfig;
-  setConfig(next: PermissionSystemExtensionConfig, ctx: ExtensionCommandContext): void;
-  getConfigPath(): string;
-}
-
-interface SettingValueSyncTarget {
-  updateValue(id: string, value: string): void;
-}
-
-const ON_OFF = ["on", "off"];
-
-function toOnOff(value: boolean): string {
-  return value ? "on" : "off";
-}
-
-function buildSettingItems(config: PermissionSystemExtensionConfig): SettingItem[] {
-  return [
-    {
-      id: "yoloMode",
-      label: "YOLO mode",
-      description: "Auto-approve ask-state permission checks, including subagent approval forwarding",
-      currentValue: toOnOff(config.yoloMode),
-      values: ON_OFF,
-    },
-    {
-      id: "permissionReviewLog",
-      label: "Permission review log",
-      description: "Write permission request and decision audit events to the extension logs directory",
-      currentValue: toOnOff(config.permissionReviewLog),
-      values: ON_OFF,
-    },
-    {
-      id: "logPlaintextBashCommands",
-      label: "Plaintext bash commands in review log",
-      description: "Opt in to storing raw bash command strings; disabled stores only safe command metadata",
-      currentValue: toOnOff(config.logPlaintextBashCommands),
-      values: ON_OFF,
-    },
-    {
-      id: "debugLog",
-      label: "Debug logging",
-      description: "Write verbose permission-system diagnostics to the extension logs directory",
-      currentValue: toOnOff(config.debugLog),
-      values: ON_OFF,
-    },
-  ];
-}
-
-function applySetting(
-  config: PermissionSystemExtensionConfig,
-  id: string,
-  value: string,
-): PermissionSystemExtensionConfig {
-  switch (id) {
-    case "yoloMode":
-      return { ...config, yoloMode: value === "on" };
-    case "permissionReviewLog":
-      return { ...config, permissionReviewLog: value === "on" };
-    case "logPlaintextBashCommands":
-      return { ...config, logPlaintextBashCommands: value === "on" };
-    case "debugLog":
-      return { ...config, debugLog: value === "on" };
-    default:
-      return config;
-  }
-}
-
-function syncSettingValues(settingsList: SettingValueSyncTarget, config: PermissionSystemExtensionConfig): void {
-  settingsList.updateValue("yoloMode", toOnOff(config.yoloMode));
-  settingsList.updateValue("permissionReviewLog", toOnOff(config.permissionReviewLog));
-  settingsList.updateValue("logPlaintextBashCommands", toOnOff(config.logPlaintextBashCommands));
-  settingsList.updateValue("debugLog", toOnOff(config.debugLog));
-}
-
-async function openSettingsModal(ctx: ExtensionCommandContext, controller: PermissionSystemConfigController): Promise<void> {
-  const overlayOptions = { anchor: "center" as const, width: 82, maxHeight: "85%" as const, margin: 1 };
-
-  await ctx.ui.custom<void>(
-    (tui, theme, _keybindings, done) => {
-      let current = controller.getConfig();
-      let settingsModal: ZellijSettingsModal | null = null;
-
-      settingsModal = new ZellijSettingsModal(
-        {
-          title: "Permission System Settings",
-          description: "Local extension options for permission logging and auto-approval behavior",
-          settings: buildSettingItems(current),
-          onChange: (id, newValue) => {
-            current = applySetting(current, id, newValue);
-            controller.setConfig(current, ctx);
-            current = controller.getConfig();
-            if (settingsModal) {
-              syncSettingValues(settingsModal, current);
-            }
-          },
-          onClose: () => done(),
-          helpText: `Config file: ${controller.getConfigPath()}`,
-          enableSearch: true,
-        },
-        theme,
-      );
-
-      const modal = new ZellijModal(
-        settingsModal,
-        {
-          borderStyle: "rounded",
-          titleBar: {
-            left: "Permission System Settings",
-            right: "pi-permission-system",
-          },
-          helpUndertitle: {
-            text: "Esc: close | ↑↓: navigate | Space: toggle",
-            color: "dim",
-          },
-          overlay: overlayOptions,
-        },
-        theme,
-      );
-
-      return {
-        render(width: number) {
-          return modal.renderModal(width).lines;
-        },
-        invalidate() {
-          modal.invalidate();
-        },
-        handleInput(data: string) {
-          modal.handleInput(data);
-          tui.requestRender();
-        },
-      };
-    },
-    { overlay: true, overlayOptions },
-  );
-}
-
-export function registerPermissionSystemCommand(pi: ExtensionAPI, controller: PermissionSystemConfigController): void {
-  pi.registerCommand("permission-system", {
-    description: "Configure pi-permission-system logging and yolo-mode behavior",
-    handler: async (_args, ctx) => {
-      if (!ctx.hasUI) {
-        ctx.ui.notify("/permission-system requires interactive TUI mode.", "warning");
-        return;
-      }
-
-      await openSettingsModal(ctx, controller);
-    },
-  });
-}
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { SettingItem } from "@earendil-works/pi-tui";
+
+import type { PermissionSystemExtensionConfig } from "./extension-config.js";
+import { ZellijModal, ZellijSettingsModal } from "./zellij-modal.js";
+
+interface PermissionSystemConfigController {
+  getConfig(): PermissionSystemExtensionConfig;
+  setConfig(next: PermissionSystemExtensionConfig, ctx: ExtensionCommandContext): void;
+  getConfigPath(): string;
+}
+
+interface SettingValueSyncTarget {
+  updateValue(id: string, value: string): void;
+}
+
+const ON_OFF = ["on", "off"];
+
+function toOnOff(value: boolean): string {
+  return value ? "on" : "off";
+}
+
+function buildSettingItems(config: PermissionSystemExtensionConfig): SettingItem[] {
+  return [
+    {
+      id: "debug",
+      label: "Debug logging",
+      description: "Write diagnostics and permission review entries to the extension debug file",
+      currentValue: toOnOff(config.debug),
+      values: ON_OFF,
+    },
+    {
+      id: "yoloMode",
+      label: "YOLO mode",
+      description: "Auto-approve ask-state permission checks, including subagent approval forwarding",
+      currentValue: toOnOff(config.yoloMode),
+      values: ON_OFF,
+    },
+  ];
+}
+
+function applySetting(
+  config: PermissionSystemExtensionConfig,
+  id: string,
+  value: string,
+): PermissionSystemExtensionConfig {
+  switch (id) {
+    case "debug":
+      return { ...config, debug: value === "on" };
+    case "yoloMode":
+      return { ...config, yoloMode: value === "on" };
+    default:
+      return config;
+  }
+}
+
+function syncSettingValues(settingsList: SettingValueSyncTarget, config: PermissionSystemExtensionConfig): void {
+  settingsList.updateValue("debug", toOnOff(config.debug));
+  settingsList.updateValue("yoloMode", toOnOff(config.yoloMode));
+}
+
+export async function openPermissionSystemSettingsModal(ctx: ExtensionCommandContext, controller: PermissionSystemConfigController): Promise<void> {
+  const overlayOptions = { anchor: "center" as const, width: 82, maxHeight: "85%" as const, margin: 1 };
+
+  await ctx.ui.custom<void>(
+    (tui, theme, _keybindings, done) => {
+      let current = controller.getConfig();
+      let settingsModal: ZellijSettingsModal | null = null;
+
+      settingsModal = new ZellijSettingsModal(
+        {
+          title: "Permission System Settings",
+          description: "Local extension options for debug logging and auto-approval behavior",
+          settings: buildSettingItems(current),
+          onChange: (id, newValue) => {
+            current = applySetting(current, id, newValue);
+            controller.setConfig(current, ctx);
+            current = controller.getConfig();
+            if (settingsModal) {
+              syncSettingValues(settingsModal, current);
+            }
+          },
+          onClose: () => done(),
+          helpText: `Config file: ${controller.getConfigPath()}`,
+          enableSearch: true,
+        },
+        theme,
+      );
+
+      const modal = new ZellijModal(
+        settingsModal,
+        {
+          borderStyle: "rounded",
+          titleBar: {
+            left: "Permission System Settings",
+            right: "pi-permission-system",
+          },
+          helpUndertitle: {
+            text: "Esc: close | ↑↓: navigate | Space: toggle",
+            color: "dim",
+          },
+          overlay: overlayOptions,
+        },
+        theme,
+      );
+
+      return {
+        render(width: number) {
+          return modal.renderModal(width).lines;
+        },
+        invalidate() {
+          modal.invalidate();
+        },
+        handleInput(data: string) {
+          modal.handleInput(data);
+          tui.requestRender();
+        },
+      };
+    },
+    { overlay: true, overlayOptions },
+  );
+}
+
+export function registerPermissionSystemCommand(pi: ExtensionAPI, controller: PermissionSystemConfigController): void {
+  pi.registerCommand("permission-system", {
+    description: "Configure pi-permission-system debug logging and yolo-mode behavior",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) {
+        ctx.ui.notify("/permission-system requires interactive TUI mode.", "warning");
+        return;
+      }
+
+      await openPermissionSystemSettingsModal(ctx, controller);
+    },
+  });
+}

package/src/evaluate-permission.ts

@@ -0,0 +1,58 @@
+import type { PermissionState } from "./types.js";
+import { compileWildcardPattern } from "./wildcard-matcher.js";
+
+export type PatternPermissionRule = {
+  tool: string;
+  pattern: string;
+  action: PermissionState;
+};
+
+export type PatternPermissionEvaluation = {
+  action: PermissionState;
+  matchedPattern?: string;
+  matchedTool?: string;
+};
+
+function isPatternPermissionRule(value: unknown): value is PatternPermissionRule {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+
+  const candidate = value as Partial<PatternPermissionRule>;
+  return typeof candidate.tool === "string"
+    && typeof candidate.pattern === "string"
+    && (candidate.action === "allow" || candidate.action === "deny" || candidate.action === "ask");
+}
+
+function normalizeRuleset(value: unknown): PatternPermissionRule[] {
+  return Array.isArray(value) ? value.filter(isPatternPermissionRule) : [];
+}
+
+export function evaluatePermission(
+  tool: string,
+  command: string,
+  ...rulesets: unknown[]
+): PatternPermissionEvaluation {
+  const rules = rulesets.flatMap(normalizeRuleset);
+
+  for (let index = rules.length - 1; index >= 0; index -= 1) {
+    const rule = rules[index];
+    const toolPattern = compileWildcardPattern(rule.tool, rule.action);
+    if (!toolPattern.regex.test(tool)) {
+      continue;
+    }
+
+    const commandPattern = compileWildcardPattern(rule.pattern, rule.action);
+    if (!commandPattern.regex.test(command)) {
+      continue;
+    }
+
+    return {
+      action: rule.action,
+      matchedPattern: rule.pattern,
+      matchedTool: rule.tool,
+    };
+  }
+
+  return { action: "ask" };
+}