pi-permission-system 0.6.0 → 0.7.0

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.6.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"
-  }
-}
+{
+  "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" };
+}