pi-permission-system 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -5,6 +5,21 @@ 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.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
@@ -83,6 +85,26 @@ The extension integrates via Pi's lifecycle hooks:
 
 ## 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`
@@ -352,12 +374,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 +401,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

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.1",
+  "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/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}`;
+  }
+}

package/src/index.ts

@@ -4,6 +4,12 @@ import { homedir } from "node:os";
 import { dirname, join, normalize, resolve, sep } from "node:path";
 
 import { toRecord } from "./common.js";
+import {
+  DEFAULT_EXTENSION_CONFIG,
+  loadPermissionSystemConfig,
+  type PermissionSystemExtensionConfig,
+} from "./extension-config.js";
+import { createPermissionSystemLogger } from "./logging.js";
 import { PermissionManager } from "./permission-manager.js";
 import { sanitizeAvailableToolsSection } from "./system-prompt-sanitizer.js";
 import { checkRequestedToolRegistration, getToolNameFromValue } from "./tool-registry.js";
@@ -67,6 +73,66 @@ type PermissionForwardingLocation = {
   label: "primary" | "legacy";
 };
 
+type PermissionRequestSource = "tool_call" | "skill_input" | "skill_read";
+type PermissionRequestState = "waiting" | "approved" | "denied";
+
+type PermissionRequestEvent = {
+  requestId: string;
+  source: PermissionRequestSource;
+  state: PermissionRequestState;
+  message: string;
+  toolCallId?: string;
+  toolName?: string;
+  skillName?: string;
+  path?: string;
+  command?: string;
+  target?: string;
+  agentName?: string | null;
+};
+
+const PERMISSION_REQUEST_EVENT_CHANNEL = "pi-permission-system:permission-request";
+
+let extensionConfig: PermissionSystemExtensionConfig = { ...DEFAULT_EXTENSION_CONFIG };
+const extensionLogger = createPermissionSystemLogger({
+  getConfig: () => extensionConfig,
+});
+const reportedLoggingWarnings = new Set<string>();
+let loggingWarningReporter: ((message: string) => void) | null = null;
+
+function setExtensionConfig(config: PermissionSystemExtensionConfig): void {
+  extensionConfig = {
+    debugLog: config.debugLog,
+    permissionReviewLog: config.permissionReviewLog,
+  };
+}
+
+function setLoggingWarningReporter(reporter: ((message: string) => void) | null): void {
+  loggingWarningReporter = reporter;
+}
+
+function reportLoggingWarning(message: string): void {
+  if (!loggingWarningReporter || reportedLoggingWarnings.has(message)) {
+    return;
+  }
+
+  reportedLoggingWarnings.add(message);
+  loggingWarningReporter(message);
+}
+
+function writeDebugLog(event: string, details: Record<string, unknown> = {}): void {
+  const warning = extensionLogger.debug(event, details);
+  if (warning) {
+    reportLoggingWarning(warning);
+  }
+}
+
+function writeReviewLog(event: string, details: Record<string, unknown> = {}): void {
+  const warning = extensionLogger.review(event, details);
+  if (warning) {
+    reportLoggingWarning(warning);
+  }
+}
+
 function decodeXml(value: string): string {
   return value
     .replace(/&lt;/g, "<")
@@ -410,6 +476,13 @@ function formatSkillPathDenyReason(skill: SkillPromptEntry, readPath: string, ag
   return `${subject} is not permitted to access skill '${skill.name}' via '${readPath}'.`;
 }
 
+function getPermissionLogContext(result: PermissionCheckResult): { command?: string; target?: string } {
+  return {
+    command: result.command,
+    target: result.target,
+  };
+}
+
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => {
     setTimeout(resolve, ms);
@@ -467,21 +540,21 @@ function isErrnoCode(error: unknown, code: string): boolean {
 }
 
 function logPermissionForwardingWarning(message: string, error?: unknown): void {
-  if (typeof error === "undefined") {
-    console.warn(`[pi-permission-system] ${message}`);
-    return;
-  }
+  const details = typeof error === "undefined"
+    ? { message }
+    : { message, error: formatUnknownErrorMessage(error) };
 
-  console.warn(`[pi-permission-system] ${message}: ${formatUnknownErrorMessage(error)}`);
+  writeReviewLog("permission_forwarding.warning", details);
+  writeDebugLog("permission_forwarding.warning", details);
 }
 
 function logPermissionForwardingError(message: string, error?: unknown): void {
-  if (typeof error === "undefined") {
-    console.error(`[pi-permission-system] ${message}`);
-    return;
-  }
+  const details = typeof error === "undefined"
+    ? { message }
+    : { message, error: formatUnknownErrorMessage(error) };
 
-  console.error(`[pi-permission-system] ${message}: ${formatUnknownErrorMessage(error)}`);
+  writeReviewLog("permission_forwarding.error", details);
+  writeDebugLog("permission_forwarding.error", details);
 }
 
 function ensureDirectoryExists(path: string, description: string): boolean {
@@ -685,6 +758,14 @@ async function waitForForwardedPermissionApproval(ctx: ExtensionContext, message
   const requestPath = join(PERMISSION_FORWARDING_REQUESTS_DIR, `${requestId}.json`);
   const responsePath = join(PERMISSION_FORWARDING_RESPONSES_DIR, `${requestId}.json`);
 
+  writeReviewLog("forwarded_permission.request_created", {
+    requestId,
+    requesterAgentName,
+    requesterSessionId: request.requesterSessionId,
+    requestPath,
+    responsePath,
+  });
+
   try {
     writeJsonFileAtomic(requestPath, request);
   } catch (error) {
@@ -696,6 +777,12 @@ async function waitForForwardedPermissionApproval(ctx: ExtensionContext, message
   while (Date.now() < deadline) {
     if (existsSync(responsePath)) {
       const response = readForwardedPermissionResponse(responsePath);
+      writeReviewLog("forwarded_permission.response_received", {
+        requestId,
+        approved: response?.approved ?? null,
+        responderSessionId: response?.responderSessionId ?? null,
+        responsePath,
+      });
       safeDeleteFile(responsePath, "forwarded permission response");
       safeDeleteFile(requestPath, "forwarded permission request");
       return Boolean(response?.approved);
@@ -705,6 +792,11 @@ async function waitForForwardedPermissionApproval(ctx: ExtensionContext, message
   }
 
   logPermissionForwardingWarning(`Timed out waiting for forwarded permission response '${responsePath}'`);
+  writeReviewLog("forwarded_permission.response_timed_out", {
+    requestId,
+    requesterAgentName,
+    responsePath,
+  });
   safeDeleteFile(requestPath, "forwarded permission request");
   return false;
 }
@@ -738,6 +830,14 @@ async function processForwardedPermissionRequests(ctx: ExtensionContext): Promis
         continue;
       }
 
+      writeReviewLog("forwarded_permission.prompted", {
+        requestId: request.id,
+        source: location.label,
+        requesterAgentName: request.requesterAgentName,
+        requesterSessionId: request.requesterSessionId,
+        requestPath,
+      });
+
       let approved = false;
       try {
         approved = await ctx.ui.confirm("Permission Required (Subagent)", formatForwardedPermissionPrompt(request));
@@ -751,6 +851,13 @@ async function processForwardedPermissionRequests(ctx: ExtensionContext): Promis
       }
 
       const responsePath = join(location.responsesDir, `${request.id}.json`);
+      writeReviewLog(approved ? "forwarded_permission.approved" : "forwarded_permission.denied", {
+        requestId: request.id,
+        source: location.label,
+        requesterAgentName: request.requesterAgentName,
+        requesterSessionId: request.requesterSessionId,
+        responsePath,
+      });
       try {
         writeJsonFileAtomic(responsePath, {
           approved,
@@ -788,6 +895,139 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   let permissionForwardingContext: ExtensionContext | null = null;
   let permissionForwardingTimer: NodeJS.Timeout | null = null;
   let isProcessingForwardedRequests = false;
+  let runtimeContext: ExtensionContext | null = null;
+  let lastConfigWarning: string | null = null;
+
+  const notifyWarning = (message: string): void => {
+    if (!runtimeContext?.hasUI) {
+      return;
+    }
+
+    runtimeContext.ui.notify(message, "warning");
+  };
+
+  const refreshExtensionConfig = (ctx?: ExtensionContext): void => {
+    if (ctx) {
+      runtimeContext = ctx;
+    }
+
+    const result = loadPermissionSystemConfig();
+    setExtensionConfig(result.config);
+
+    if (result.warning && result.warning !== lastConfigWarning) {
+      lastConfigWarning = result.warning;
+      notifyWarning(result.warning);
+    } else if (!result.warning) {
+      lastConfigWarning = null;
+    }
+
+    writeDebugLog("config.loaded", {
+      created: result.created,
+      warning: result.warning ?? null,
+      debugLog: result.config.debugLog,
+      permissionReviewLog: result.config.permissionReviewLog,
+    });
+  };
+
+  setLoggingWarningReporter(notifyWarning);
+  refreshExtensionConfig();
+
+  const createPermissionRequestId = (prefix: string): string => {
+    return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}-${process.pid}`;
+  };
+
+  const emitPermissionRequestEvent = (event: PermissionRequestEvent): void => {
+    try {
+      pi.events.emit(PERMISSION_REQUEST_EVENT_CHANNEL, event);
+    } catch (error) {
+      writeDebugLog("permission_request.event_emit_failed", {
+        requestId: event.requestId,
+        source: event.source,
+        state: event.state,
+        error: formatUnknownErrorMessage(error),
+      });
+    }
+  };
+
+  const reviewPermissionDecision = (
+    event: string,
+    details: {
+      requestId: string;
+      source: PermissionRequestSource;
+      agentName: string | null;
+      message: string;
+      toolCallId?: string;
+      toolName?: string;
+      skillName?: string;
+      path?: string;
+      command?: string;
+      target?: string;
+      resolution?: string;
+    },
+  ): void => {
+    writeReviewLog(event, {
+      requestId: details.requestId,
+      source: details.source,
+      agentName: details.agentName,
+      message: details.message,
+      toolCallId: details.toolCallId ?? null,
+      toolName: details.toolName ?? null,
+      skillName: details.skillName ?? null,
+      path: details.path ?? null,
+      command: details.command ?? null,
+      target: details.target ?? null,
+      resolution: details.resolution ?? null,
+    });
+  };
+
+  const promptPermission = async (
+    ctx: ExtensionContext,
+    details: {
+      requestId: string;
+      source: PermissionRequestSource;
+      agentName: string | null;
+      message: string;
+      toolCallId?: string;
+      toolName?: string;
+      skillName?: string;
+      path?: string;
+      command?: string;
+      target?: string;
+    },
+  ): Promise<boolean> => {
+    reviewPermissionDecision("permission_request.waiting", details);
+    emitPermissionRequestEvent({
+      requestId: details.requestId,
+      source: details.source,
+      state: "waiting",
+      message: details.message,
+      toolCallId: details.toolCallId,
+      toolName: details.toolName,
+      skillName: details.skillName,
+      path: details.path,
+      command: details.command,
+      target: details.target,
+      agentName: details.agentName,
+    });
+
+    const approved = await confirmPermission(ctx, details.message);
+    reviewPermissionDecision(approved ? "permission_request.approved" : "permission_request.denied", details);
+    emitPermissionRequestEvent({
+      requestId: details.requestId,
+      source: details.source,
+      state: approved ? "approved" : "denied",
+      message: details.message,
+      toolCallId: details.toolCallId,
+      toolName: details.toolName,
+      skillName: details.skillName,
+      path: details.path,
+      command: details.command,
+      target: details.target,
+      agentName: details.agentName,
+    });
+
+    return approved;
+  };
 
   const stopForwardedPermissionPolling = (): void => {
     if (permissionForwardingTimer) {
@@ -852,6 +1092,8 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   };
 
   pi.on("session_start", async (_event, ctx) => {
+    runtimeContext = ctx;
+    refreshExtensionConfig(ctx);
     permissionManager = new PermissionManager();
     activeSkillEntries = [];
     lastKnownActiveAgentName = getActiveAgentName(ctx);
@@ -859,16 +1101,21 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   });
 
   pi.on("session_switch", async (_event, ctx) => {
+    runtimeContext = ctx;
+    refreshExtensionConfig(ctx);
     activeSkillEntries = [];
     lastKnownActiveAgentName = getActiveAgentName(ctx);
     startForwardedPermissionPolling(ctx);
   });
 
   pi.on("session_shutdown", async () => {
+    runtimeContext = null;
     stopForwardedPermissionPolling();
   });
 
   pi.on("before_agent_start", async (event, ctx) => {
+    runtimeContext = ctx;
+    refreshExtensionConfig(ctx);
     startForwardedPermissionPolling(ctx);
     const agentName = resolveAgentName(ctx, event.systemPrompt);
     const allTools = pi.getAllTools();
@@ -899,6 +1146,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   });
 
   pi.on("input", async (event, ctx) => {
+    runtimeContext = ctx;
     startForwardedPermissionPolling(ctx);
     const skillName = extractSkillNameFromInput(event.text);
     if (!skillName) {
@@ -911,6 +1159,12 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       if (ctx.hasUI) {
         ctx.ui.notify(`Skill '${skillName}' is blocked because active agent context is unavailable.`, "warning");
       }
+      writeReviewLog("permission_request.blocked", {
+        source: "skill_input",
+        skillName,
+        agentName: null,
+        resolution: "missing_agent_context",
+      });
       return { action: "handled" };
     }
 
@@ -921,15 +1175,35 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
         const resolvedAgent = agentName ?? "none";
         ctx.ui.notify(`Skill '${skillName}' is not permitted for agent '${resolvedAgent}'.`, "warning");
       }
+      writeReviewLog("permission_request.blocked", {
+        source: "skill_input",
+        skillName,
+        agentName,
+        resolution: "policy_denied",
+      });
       return { action: "handled" };
     }
 
     if (check.state === "ask") {
+      const message = formatSkillAskPrompt(skillName, agentName ?? undefined);
       if (!canRequestPermissionConfirmation(ctx)) {
+        writeReviewLog("permission_request.blocked", {
+          source: "skill_input",
+          skillName,
+          agentName,
+          message,
+          resolution: "confirmation_unavailable",
+        });
         return { action: "handled" };
       }
 
-      const approved = await confirmPermission(ctx, formatSkillAskPrompt(skillName, agentName ?? undefined));
+      const approved = await promptPermission(ctx, {
+        requestId: createPermissionRequestId("skill-input"),
+        source: "skill_input",
+        agentName,
+        message,
+        skillName,
+      });
       if (!approved) {
         return { action: "handled" };
       }
@@ -939,6 +1213,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   });
 
   pi.on("tool_call", async (event, ctx) => {
+    runtimeContext = ctx;
     startForwardedPermissionPolling(ctx);
     const agentName = resolveAgentName(ctx);
     const toolName = getEventToolName(event);
@@ -969,6 +1244,13 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
 
       if (matchedSkill) {
         if (matchedSkill.state === "deny") {
+          writeReviewLog("permission_request.blocked", {
+            source: "skill_read",
+            skillName: matchedSkill.name,
+            agentName,
+            path: event.input.path,
+            resolution: "policy_denied",
+          });
           return {
             block: true,
             reason: formatSkillPathDenyReason(matchedSkill, event.input.path, agentName ?? undefined),
@@ -976,17 +1258,32 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
         }
 
         if (matchedSkill.state === "ask") {
+          const message = formatSkillPathAskPrompt(matchedSkill, event.input.path, agentName ?? undefined);
           if (!canRequestPermissionConfirmation(ctx)) {
+            writeReviewLog("permission_request.blocked", {
+              source: "skill_read",
+              skillName: matchedSkill.name,
+              agentName,
+              path: event.input.path,
+              message,
+              resolution: "confirmation_unavailable",
+            });
             return {
               block: true,
               reason: `Accessing skill '${matchedSkill.name}' requires approval, but no interactive UI is available.`,
             };
           }
 
-          const approved = await confirmPermission(
-            ctx,
-            formatSkillPathAskPrompt(matchedSkill, event.input.path, agentName ?? undefined),
-          );
+          const approved = await promptPermission(ctx, {
+            requestId: event.toolCallId,
+            source: "skill_read",
+            agentName,
+            message,
+            toolCallId: event.toolCallId,
+            toolName: toolName,
+            skillName: matchedSkill.name,
+            path: event.input.path,
+          });
           if (!approved) {
             return { block: true, reason: `User denied access to skill '${matchedSkill.name}'.` };
           }
@@ -996,8 +1293,17 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
 
     const input = getEventInput(event);
     const check = permissionManager.checkPermission(toolName, input, agentName ?? undefined);
+    const permissionLogContext = getPermissionLogContext(check);
 
     if (check.state === "deny") {
+      writeReviewLog("permission_request.blocked", {
+        source: "tool_call",
+        toolCallId: event.toolCallId,
+        toolName,
+        agentName,
+        ...permissionLogContext,
+        resolution: "policy_denied",
+      });
       return { block: true, reason: formatDenyReason(check, agentName ?? undefined) };
     }
 
@@ -1008,14 +1314,32 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
           ? "Using tool 'mcp' requires approval, but no interactive UI is available."
           : `Using tool '${toolName}' requires approval, but no interactive UI is available.`;
 
+      const message = formatAskPrompt(check, agentName ?? undefined);
       if (!canRequestPermissionConfirmation(ctx)) {
+        writeReviewLog("permission_request.blocked", {
+          source: "tool_call",
+          toolCallId: event.toolCallId,
+          toolName,
+          agentName,
+          message,
+          ...permissionLogContext,
+          resolution: "confirmation_unavailable",
+        });
         return {
           block: true,
           reason: unavailableReason,
         };
       }
 
-      const approved = await confirmPermission(ctx, formatAskPrompt(check, agentName ?? undefined));
+      const approved = await promptPermission(ctx, {
+        requestId: event.toolCallId,
+        source: "tool_call",
+        agentName,
+        message,
+        toolCallId: event.toolCallId,
+        toolName,
+        ...permissionLogContext,
+      });
       if (!approved) {
         return { block: true, reason: formatUserDeniedReason(check) };
       }

package/src/logging.ts

@@ -0,0 +1,94 @@
+import { appendFileSync } from "node:fs";
+
+import {
+  DEBUG_LOG_PATH,
+  EXTENSION_ID,
+  LOGS_DIR,
+  PERMISSION_REVIEW_LOG_PATH,
+  ensurePermissionSystemLogsDirectory,
+  type PermissionSystemExtensionConfig,
+} from "./extension-config.js";
+
+function safeJsonStringify(value: unknown): string {
+  const seen = new WeakSet<object>();
+  return JSON.stringify(value, (_key, currentValue) => {
+    if (currentValue instanceof Error) {
+      return {
+        name: currentValue.name,
+        message: currentValue.message,
+        stack: currentValue.stack,
+      };
+    }
+
+    if (typeof currentValue === "bigint") {
+      return currentValue.toString();
+    }
+
+    if (typeof currentValue === "object" && currentValue !== null) {
+      if (seen.has(currentValue)) {
+        return "[Circular]";
+      }
+      seen.add(currentValue);
+    }
+
+    return currentValue;
+  });
+}
+
+export interface PermissionSystemLogger {
+  debug: (event: string, details?: Record<string, unknown>) => string | undefined;
+  review: (event: string, details?: Record<string, unknown>) => string | undefined;
+}
+
+interface PermissionSystemLoggerOptions {
+  getConfig: () => PermissionSystemExtensionConfig;
+  debugLogPath?: string;
+  reviewLogPath?: string;
+  ensureLogsDirectory?: () => string | undefined;
+}
+
+export function createPermissionSystemLogger(options: PermissionSystemLoggerOptions): PermissionSystemLogger {
+  const debugLogPath = options.debugLogPath ?? DEBUG_LOG_PATH;
+  const reviewLogPath = options.reviewLogPath ?? PERMISSION_REVIEW_LOG_PATH;
+  const ensureLogsDirectory = options.ensureLogsDirectory ?? (() => ensurePermissionSystemLogsDirectory(LOGS_DIR));
+
+  const writeLine = (stream: "debug" | "review", path: string, event: string, details: Record<string, unknown>): string | undefined => {
+    const directoryError = ensureLogsDirectory();
+    if (directoryError) {
+      return directoryError;
+    }
+
+    try {
+      const line = safeJsonStringify({
+        timestamp: new Date().toISOString(),
+        extension: EXTENSION_ID,
+        stream,
+        event,
+        ...details,
+      });
+      appendFileSync(path, `${line}\n`, "utf-8");
+      return undefined;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return `Failed to write permission-system ${stream} log '${path}': ${message}`;
+    }
+  };
+
+  const debug = (event: string, details: Record<string, unknown> = {}): string | undefined => {
+    if (!options.getConfig().debugLog) {
+      return undefined;
+    }
+
+    return writeLine("debug", debugLogPath, event, details);
+  };
+
+  const review = (event: string, details: Record<string, unknown> = {}): string | undefined => {
+    if (!options.getConfig().permissionReviewLog) {
+      return undefined;
+    }
+
+    return writeLine("review", reviewLogPath, event, details);
+  };
+
+  return { debug, review };
+}

package/src/test.ts

@@ -1,9 +1,11 @@
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import { BashFilter } from "./bash-filter.js";
+import { DEFAULT_EXTENSION_CONFIG, loadPermissionSystemConfig } from "./extension-config.js";
+import { createPermissionSystemLogger } from "./logging.js";
 import { PermissionManager } from "./permission-manager.js";
 import { checkRequestedToolRegistration, getToolNameFromValue } from "./tool-registry.js";
 import type { GlobalPermissionConfig } from "./types.js";
@@ -47,6 +49,61 @@ function runTest(name: string, testFn: () => void): void {
   console.log(`[PASS] ${name}`);
 }
 
+runTest("Permission-system extension config defaults debug off and review log on", () => {
+  const baseDir = mkdtempSync(join(tmpdir(), "pi-permission-system-config-"));
+  const configPath = join(baseDir, "config.json");
+
+  try {
+    const result = loadPermissionSystemConfig(configPath);
+    assert.equal(result.created, true);
+    assert.equal(result.warning, undefined);
+    assert.deepEqual(result.config, DEFAULT_EXTENSION_CONFIG);
+    assert.equal(existsSync(configPath), true);
+
+    const raw = JSON.parse(readFileSync(configPath, "utf8")) as Record<string, unknown>;
+    assert.equal(raw.debugLog, false);
+    assert.equal(raw.permissionReviewLog, true);
+  } finally {
+    rmSync(baseDir, { recursive: true, force: true });
+  }
+});
+
+runTest("Permission-system logger respects debug toggle and keeps review log enabled by default", () => {
+  const baseDir = mkdtempSync(join(tmpdir(), "pi-permission-system-logs-"));
+  const logsDir = join(baseDir, "logs");
+  const debugLogPath = join(logsDir, "debug.jsonl");
+  const reviewLogPath = join(logsDir, "review.jsonl");
+  const config = { ...DEFAULT_EXTENSION_CONFIG };
+  const logger = createPermissionSystemLogger({
+    getConfig: () => config,
+    debugLogPath,
+    reviewLogPath,
+    ensureLogsDirectory: () => {
+      mkdirSync(logsDir, { recursive: true });
+      return undefined;
+    },
+  });
+
+  try {
+    const initialDebugWarning = logger.debug("debug.disabled", { sample: true });
+    const reviewWarning = logger.review("permission_request.waiting", { toolName: "write" });
+
+    assert.equal(initialDebugWarning, undefined);
+    assert.equal(reviewWarning, undefined);
+    assert.equal(existsSync(debugLogPath), false);
+    assert.equal(existsSync(reviewLogPath), true);
+    assert.match(readFileSync(reviewLogPath, "utf8"), /permission_request\.waiting/);
+
+    config.debugLog = true;
+    const enabledDebugWarning = logger.debug("debug.enabled", { sample: true });
+    assert.equal(enabledDebugWarning, undefined);
+    assert.equal(existsSync(debugLogPath), true);
+    assert.match(readFileSync(debugLogPath, "utf8"), /debug\.enabled/);
+  } finally {
+    rmSync(baseDir, { recursive: true, force: true });
+  }
+});
+
 runTest("BashFilter uses opencode-style last-match hierarchy", () => {
   const filter = new BashFilter(
     {