pi-permission-system 0.4.8 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-05-22
+
+### Added
+- Added `logPlaintextBashCommands` as an opt-in extension setting and settings-modal control; review logs redact raw bash command strings by default while retaining safe metadata.
+- Added structured edit summaries for `replace`, `append`, `prepend`, `replace_text`, and `delete` payloads in permission prompts.
+- Added skill-read enforcement for direct `read` calls under global and project Pi skill directories by inferring the skill name from the requested path when prompt entries are absent.
+
+### Changed
+- Hardened subagent permission forwarding with watched request directories, async request/response reads, and nonce-bound responses.
+- Updated package metadata and lockfile version to `0.5.0` and migrated Pi peer dependency metadata to the `@earendil-works` scope.
+
+## [0.4.9] - 2026-05-05
+
+### Changed
+- Permission-system config parsing now accepts JSONC comments and trailing commas across both policy files and the extension config, and invalid config warnings are emitted once per session as a compact single-line message with explicit fallback behavior.
+
+### Fixed
+- Stopped repeating identical invalid-config warnings in the TUI when the same broken permission policy is re-evaluated during the same session or reload cycle (thanks to @jviel-beta for issue #20).
+
 ## [0.4.8] - 2026-05-04
 
 ### Added

package/README.md

@@ -95,11 +95,11 @@ If you are coming from OpenCode, you usually do **not** need to rewrite your who
 - **Runtime Enforcement** — Blocks/asks/allows at tool call time with UI confirmation dialogs and readable approval summaries
 - **Bash Command Control** — Wildcard pattern matching for granular bash command permissions
 - **MCP Access Control** — Server and tool-level permissions for MCP operations
-- **Skill Protection** — Controls which skills can be loaded or read from disk, including multi-block prompt sanitization
+- **Skill Protection** — Controls which skills can be loaded or read from disk, including multi-block prompt sanitization and path-inferred reads under Pi skill directories
 - **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 for later auditing
+- **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`
 - **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
@@ -167,7 +167,7 @@ The extension integrates via Pi's lifecycle hooks:
 |----------------------|-------------------------------------------------------------------------------------------|
 | `before_agent_start` | Filters active tools, removes denied tool entries from the system prompt, and hides denied skills |
 | `tool_call`          | Enforces permissions for every tool invocation                                            |
-| `input`              | Intercepts `/skill:<name>` requests and enforces skill policy                             |
+| `input`              | Tracks explicit `/skill:<name>` requests so user-invoked skill loads can proceed while agent-initiated reads remain policy-gated |
 
 **Additional behaviors:**
 - Unknown/unregistered tools are blocked before permission checks (prevents bypass attempts)
@@ -175,8 +175,10 @@ 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 requested bash command text plus redacted prompt/input metadata for auditing without writing raw prompts or generic tool payload previews
+- Permission review logs include redacted prompt/input metadata for auditing; raw bash command text is omitted unless `logPlaintextBashCommands` is enabled.
 - 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.
 
 ## Configuration
 
@@ -192,6 +194,7 @@ The extension creates this file automatically when it is missing. It controls ex
 {
   "debugLog": false,
   "permissionReviewLog": true,
+  "logPlaintextBashCommands": false,
   "yoloMode": false
 }
 ```
@@ -200,6 +203,7 @@ The extension creates this file automatically when it is missing. It controls ex
 |-----|---------|-------------|
 | `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 |
 | `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.
@@ -246,7 +250,7 @@ The policy file is a JSON object with these sections:
 | `skills`        | Skill name pattern permissions                      |
 | `special`       | Reserved permission checks such as external directory access |
 
-> **Note:** Trailing commas are **not** supported. If parsing fails, the extension falls back to `ask` for all categories.
+> **Note:** JSONC comments and trailing commas are supported. If parsing still fails, the extension falls back to `ask` for all categories and shows a warning in the TUI when available.
 
 ### Global Per-Agent Overrides
 
@@ -430,6 +434,7 @@ Skill name patterns use `*` wildcards:
 }
 ```
 
+Skill-read enforcement also applies when a `read` path is under the global Pi skills directory (`~/.pi/agent/skills` or `PI_CODING_AGENT_DIR/skills`) or the active project's `.pi/agent/skills` directory. In that case the skill name is inferred from the path and checked against `skills` policy even if no active prompt block listed the skill; direct user `/skill:<name>` requests are allowed to proceed for that requested skill.
 ### `special`
 
 Reserved permission checks:
@@ -637,7 +642,7 @@ npx --yes ajv-cli@5 validate \
 
 | Problem | Cause | Solution |
 |---------|-------|----------|
-| Config not applied (everything asks) | File not found or parse error | Verify the global Pi policy file (default: `~/.pi/agent/pi-permissions.jsonc`, respects `PI_CODING_AGENT_DIR`); check for trailing commas |
+| Config not applied (everything asks) | File not found or parse error | Verify the global Pi policy file (default: `~/.pi/agent/pi-permissions.jsonc`, respects `PI_CODING_AGENT_DIR`); check the TUI warning for the parse location/message |
 | Per-agent override not applied | Frontmatter parsing issue | Ensure `---` delimiters at file top; keep YAML simple; restart session |
 | Tool blocked as unregistered | Unknown tool name | Use a registered `mcp` tool for server tools: `{ "tool": "server:tool" }` |
 | `/skill:<name>` blocked | Deny policy or confirmation unavailable | Check merged `skills` policy (global/project/agent layers). Active agent context is optional in the main session; `ask` still requires UI or forwarded confirmation. |

package/package.json

@@ -1,68 +1,71 @@
-{
-  "name": "pi-permission-system",
-  "version": "0.4.8",
-  "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": {
-    "@mariozechner/pi-ai": "^0.72.0",
-    "@mariozechner/pi-coding-agent": "^0.72.0",
-    "@mariozechner/pi-tui": "^0.72.0",
-    "@sinclair/typebox": "^0.34.49"
-  }
-}
+{
+  "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"
+  }
+}

package/src/config-modal.ts

@@ -1,5 +1,5 @@
-import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
-import type { SettingItem } from "@mariozechner/pi-tui";
+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";
@@ -36,6 +36,13 @@ function buildSettingItems(config: PermissionSystemExtensionConfig): SettingItem
       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",
@@ -56,6 +63,8 @@ function applySetting(
       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:
@@ -66,6 +75,7 @@ function applySetting(
 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));
 }
 

package/src/extension-config.ts

@@ -1,164 +1,170 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, 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;
-  yoloMode: boolean;
-}
-
-export interface PermissionSystemConfigLoadResult {
-  config: PermissionSystemExtensionConfig;
-  created: boolean;
-  warning?: string;
-}
-
-export interface PermissionSystemConfigSaveResult {
-  success: boolean;
-  error?: string;
-}
-
-export const DEFAULT_EXTENSION_CONFIG: PermissionSystemExtensionConfig = {
-  debugLog: false,
-  permissionReviewLog: true,
-  yoloMode: false,
-};
-
-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`);
-export const CONFIG_PATH_ENV_KEY = "PI_PERMISSION_SYSTEM_CONFIG_PATH";
-export const LOGS_DIR_ENV_KEY = "PI_PERMISSION_SYSTEM_LOGS_DIR";
-
-export function getPermissionSystemConfigPath(configPath?: string): string {
-  const overridePath = process.env[CONFIG_PATH_ENV_KEY]?.trim();
-  return configPath || overridePath || CONFIG_PATH;
-}
-
-export function getPermissionSystemLogsDir(logsDir?: string): string {
-  const overrideDir = process.env[LOGS_DIR_ENV_KEY]?.trim();
-  return logsDir || overrideDir || LOGS_DIR;
-}
-
-export function getPermissionSystemDebugLogPath(logsDir = getPermissionSystemLogsDir()): string {
-  return join(logsDir, `${EXTENSION_ID}-debug.jsonl`);
-}
-
-export function getPermissionSystemReviewLogPath(logsDir = getPermissionSystemLogsDir()): string {
-  return join(logsDir, `${EXTENSION_ID}-permission-review.jsonl`);
-}
-
-export function cloneDefaultConfig(): PermissionSystemExtensionConfig {
-  return {
-    debugLog: DEFAULT_EXTENSION_CONFIG.debugLog,
-    permissionReviewLog: DEFAULT_EXTENSION_CONFIG.permissionReviewLog,
-    yoloMode: DEFAULT_EXTENSION_CONFIG.yoloMode,
-  };
-}
-
-function createDefaultConfigContent(): string {
-  return `${JSON.stringify(DEFAULT_EXTENSION_CONFIG, null, 2)}\n`;
-}
-
-export function normalizePermissionSystemConfig(raw: unknown): PermissionSystemExtensionConfig {
-  const record = toRecord(raw);
-  return {
-    debugLog: record.debugLog === true,
-    permissionReviewLog: record.permissionReviewLog !== false,
-    yoloMode: record.yoloMode === true,
-  };
-}
-
-function ensureConfigDirectory(configPath: string): void {
-  mkdirSync(dirname(configPath), { recursive: true });
-}
-
-export function ensurePermissionSystemConfig(configPath = getPermissionSystemConfigPath()): { 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 = getPermissionSystemConfigPath()): PermissionSystemConfigLoadResult {
-  const ensureResult = ensurePermissionSystemConfig(configPath);
-
-  try {
-    const raw = readFileSync(configPath, "utf-8");
-    const parsed = JSON.parse(raw) as unknown;
-    const config = normalizePermissionSystemConfig(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 savePermissionSystemConfig(
-  config: PermissionSystemExtensionConfig,
-  configPath = getPermissionSystemConfigPath(),
-): PermissionSystemConfigSaveResult {
-  const normalized = normalizePermissionSystemConfig(config);
-  const tmpPath = `${configPath}.tmp`;
-
-  try {
-    ensureConfigDirectory(configPath);
-    writeFileSync(tmpPath, `${JSON.stringify(normalized, null, 2)}\n`, "utf-8");
-    renameSync(tmpPath, configPath);
-    return { success: true };
-  } catch (error) {
-    try {
-      if (existsSync(tmpPath)) {
-        unlinkSync(tmpPath);
-      }
-    } catch {
-      // Ignore cleanup failures.
-    }
-
-    const message = error instanceof Error ? error.message : String(error);
-    return {
-      success: false,
-      error: `Failed to save permission-system config at '${configPath}': ${message}`,
-    };
-  }
-}
-
-export function ensurePermissionSystemLogsDirectory(logsDir = getPermissionSystemLogsDir()): 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}`;
-  }
-}
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { toRecord } from "./common.js";
+import { formatJsoncConfigLoadWarning, parseJsoncConfig } from "./jsonc-config.js";
+
+export const EXTENSION_ID = "pi-permission-system";
+
+export interface PermissionSystemExtensionConfig {
+  debugLog: boolean;
+  permissionReviewLog: boolean;
+  logPlaintextBashCommands: boolean;
+  yoloMode: boolean;
+}
+
+export interface PermissionSystemConfigLoadResult {
+  config: PermissionSystemExtensionConfig;
+  created: boolean;
+  warning?: string;
+}
+
+export interface PermissionSystemConfigSaveResult {
+  success: boolean;
+  error?: string;
+}
+
+export const DEFAULT_EXTENSION_CONFIG: PermissionSystemExtensionConfig = {
+  debugLog: false,
+  permissionReviewLog: true,
+  logPlaintextBashCommands: false,
+  yoloMode: false,
+};
+
+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`);
+export const CONFIG_PATH_ENV_KEY = "PI_PERMISSION_SYSTEM_CONFIG_PATH";
+export const LOGS_DIR_ENV_KEY = "PI_PERMISSION_SYSTEM_LOGS_DIR";
+
+export function getPermissionSystemConfigPath(configPath?: string): string {
+  const overridePath = process.env[CONFIG_PATH_ENV_KEY]?.trim();
+  return configPath || overridePath || CONFIG_PATH;
+}
+
+export function getPermissionSystemLogsDir(logsDir?: string): string {
+  const overrideDir = process.env[LOGS_DIR_ENV_KEY]?.trim();
+  return logsDir || overrideDir || LOGS_DIR;
+}
+
+export function getPermissionSystemDebugLogPath(logsDir = getPermissionSystemLogsDir()): string {
+  return join(logsDir, `${EXTENSION_ID}-debug.jsonl`);
+}
+
+export function getPermissionSystemReviewLogPath(logsDir = getPermissionSystemLogsDir()): string {
+  return join(logsDir, `${EXTENSION_ID}-permission-review.jsonl`);
+}
+
+export function cloneDefaultConfig(): PermissionSystemExtensionConfig {
+  return {
+    debugLog: DEFAULT_EXTENSION_CONFIG.debugLog,
+    permissionReviewLog: DEFAULT_EXTENSION_CONFIG.permissionReviewLog,
+    logPlaintextBashCommands: DEFAULT_EXTENSION_CONFIG.logPlaintextBashCommands,
+    yoloMode: DEFAULT_EXTENSION_CONFIG.yoloMode,
+  };
+}
+
+function createDefaultConfigContent(): string {
+  return `${JSON.stringify(DEFAULT_EXTENSION_CONFIG, null, 2)}\n`;
+}
+
+export function normalizePermissionSystemConfig(raw: unknown): PermissionSystemExtensionConfig {
+  const record = toRecord(raw);
+  return {
+    debugLog: record.debugLog === true,
+    permissionReviewLog: record.permissionReviewLog !== false,
+    logPlaintextBashCommands: record.logPlaintextBashCommands === true,
+    yoloMode: record.yoloMode === true,
+  };
+}
+
+function ensureConfigDirectory(configPath: string): void {
+  mkdirSync(dirname(configPath), { recursive: true });
+}
+
+export function ensurePermissionSystemConfig(configPath = getPermissionSystemConfigPath()): { 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 = getPermissionSystemConfigPath()): PermissionSystemConfigLoadResult {
+  const ensureResult = ensurePermissionSystemConfig(configPath);
+
+  try {
+    const raw = readFileSync(configPath, "utf-8");
+    const parsed = parseJsoncConfig(raw, configPath, "permission-system config");
+    const config = normalizePermissionSystemConfig(parsed);
+    return {
+      config,
+      created: ensureResult.created,
+      warning: ensureResult.warning,
+    };
+  } catch (error) {
+    return {
+      config: cloneDefaultConfig(),
+      created: ensureResult.created,
+      warning: ensureResult.warning
+        ?? formatJsoncConfigLoadWarning(configPath, error, "permission-system config", "using default extension config")
+        ?? undefined,
+    };
+  }
+}
+
+export function savePermissionSystemConfig(
+  config: PermissionSystemExtensionConfig,
+  configPath = getPermissionSystemConfigPath(),
+): PermissionSystemConfigSaveResult {
+  const normalized = normalizePermissionSystemConfig(config);
+  const tmpPath = `${configPath}.tmp`;
+
+  try {
+    ensureConfigDirectory(configPath);
+    writeFileSync(tmpPath, `${JSON.stringify(normalized, null, 2)}\n`, "utf-8");
+    renameSync(tmpPath, configPath);
+    return { success: true };
+  } catch (error) {
+    try {
+      if (existsSync(tmpPath)) {
+        unlinkSync(tmpPath);
+      }
+    } catch {
+      // Ignore cleanup failures.
+    }
+
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      success: false,
+      error: `Failed to save permission-system config at '${configPath}': ${message}`,
+    };
+  }
+}
+
+export function ensurePermissionSystemLogsDirectory(logsDir = getPermissionSystemLogsDir()): 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}`;
+  }
+}