pi-permission-system 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,39 @@ 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.3.0] - 2026-03-23
+
+### Added
+- Yolo mode for auto-approval when enabled — bypasses permission prompts for streamlined workflows
+- Permission forwarding system for subagent-to-primary IPC communication
+- Configuration modal UI with Zellij integration (`config-modal.ts`, `zellij-modal.ts`)
+- `permission-forwarding.ts` module for subagent permission request routing
+- `yolo-mode.ts` module for automatic permission approval when yolo mode is active
+
+### Changed
+- Updated `@mariozechner/pi-coding-agent` and `@mariozechner/pi-tui` peer dependencies to ^0.62.0
+- Refactored `index.ts` to export new permission resolution utilities
+- Expanded `extension-config.ts` with config normalization for new features
+- Added `types-shims.d.ts` for Zellij modal type definitions
+
+### Tests
+- Added comprehensive tests for config modal functionality
+- Added tests for permission forwarding behavior
+
+## [0.2.2] - 2026-03-13
+
+### Changed
+- Removed delegation task restriction logic — the `task` tool is no longer restricted to orchestrator agent only
+- Simplified tool permission lookup to use explicit `tools` entries for arbitrary registered tools instead of MCP fallback
+- Renamed `TOOL_PERMISSION_NAMES` to `BUILT_IN_TOOL_PERMISSION_NAMES` to clarify it covers only canonical Pi tools
+- Updated schema descriptions for `tools` and `mcp` fields to guide configuration usage
+
+### Removed
+- Removed delegation-specific permission checks (`isDelegationAllowedAgent`, `getDelegationBlockReason`) from permission evaluation
+
+### Tests
+- Added comprehensive test coverage for tool permission lookup behavior
+
 ## [0.2.1] - 2026-03-13
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # 🔐 pi-permission-system
 
-[![Version](https://img.shields.io/badge/version-0.2.1-blue.svg)](package.json)
+[![Version](https://img.shields.io/badge/version-0.3.0-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.
@@ -79,7 +79,7 @@ The extension integrates via Pi's lifecycle hooks:
 **Additional behaviors:**
 - Unknown/unregistered tools are blocked before permission checks (prevents bypass attempts)
 - The `Available tools:` system prompt section is rewritten to match the filtered active tool set
-- The `task` delegation tool is restricted to the `orchestrator` agent only
+- Extension-provided tools like `task`, `mcp`, and third-party tools are handled by exact registered name instead of private built-in hardcodes
 - When a subagent hits an `ask` permission without direct UI access, the request can be forwarded to the main interactive session for confirmation
 - When a subagent triggers an `ask` permission without UI access, the request can be forwarded to the main session and answered there
 
@@ -111,14 +111,14 @@ Both logs write to files only under the extension directory. No debug output is
 
 The policy file is a JSON object with these sections:
 
-| Section         | Description                              |
-|-----------------|------------------------------------------|
-| `defaultPolicy` | Fallback permissions per category        |
-| `tools`         | Built-in tool permissions                |
-| `bash`          | Command pattern permissions              |
-| `mcp`           | MCP server/tool permissions              |
-| `skills`        | Skill name pattern permissions           |
-| `special`       | Reserved permission checks               |
+| Section         | Description                                         |
+|-----------------|-----------------------------------------------------|
+| `defaultPolicy` | Fallback permissions per category                   |
+| `tools`         | Exact-name tool permissions for registered tools    |
+| `bash`          | Command pattern permissions                         |
+| `mcp`           | MCP server/tool permissions for calls routed through a registered `mcp` tool |
+| `skills`        | Skill name pattern permissions                      |
+| `special`       | Reserved permission checks                          |
 
 > **Note:** Trailing commas are **not** supported. If parsing fails, the extension falls back to `ask` for all categories.
 
@@ -147,7 +147,7 @@ permission:
 
 **Precedence:** Agent frontmatter overrides global config (shallow-merged per section).
 
-**MCP behavior:** `permission.tools.mcp` is the coarse entry/fallback permission for the built-in `mcp` tool. More specific `permission.mcp` target rules override that fallback when they match.
+**MCP behavior:** `permission.tools.mcp` is the coarse entry/fallback permission for a registered `mcp` tool when one is available. More specific `permission.mcp` target rules override that fallback when they match.
 
 **Limitations:** The frontmatter parser is intentionally minimal. Use only `key: value` scalars and nested maps. Avoid arrays, multi-line scalars, and YAML anchors.
 
@@ -173,33 +173,34 @@ Sets fallback permissions when no specific rule matches:
 
 ### `tools`
 
-Controls built-in tools by exact name (no wildcards):
+Controls tools by exact registered name (no wildcards). This is the recommended standalone format for **all** tool entries, including Pi built-ins and arbitrary third-party extension tools.
 
-| Tool    | Description                    |
-|---------|--------------------------------|
-| `bash`  | Shell command execution        |
-| `read`  | File reading                   |
-| `write` | File creation/overwriting      |
-| `edit`  | Surgical file edits            |
-| `grep`  | Pattern searching              |
-| `find`  | File discovery                 |
-| `ls`    | Directory listing              |
-| `mcp`   | MCP proxy tool entry/fallback  |
+| Tool name example     | Description |
+|-----------------------|-------------|
+| `bash`                | Shell command execution (tool-level fallback before `bash` pattern rules) |
+| `read` / `write`      | Canonical Pi built-in file tools |
+| `mcp`                 | Registered MCP proxy tool entry/fallback when available |
+| `task`                | Delegation tool handled like any other registered extension tool |
+| `third_party_tool`    | Arbitrary registered extension tool |
 
 ```jsonc
 {
   "tools": {
     "read": "allow",
     "write": "deny",
-    "edit": "deny",
-    "mcp": "allow"
+    "mcp": "allow",
+    "third_party_tool": "ask"
   }
 }
 ```
 
+Unknown or absent tools are not required in the config. If another extension is not installed, its tool simply will not be registered at runtime, and this extension will block attempts to call that missing tool before permission checks run.
+
 > **Note:** Setting `tools.bash` affects the *default* for bash commands, but `bash` patterns can provide command-level overrides.
 >
-> **Note:** Setting `tools.mcp` controls coarse access to the built-in `mcp` tool. Specific `mcp` rules still override it when a target pattern matches.
+> **Note:** Setting `tools.mcp` controls coarse access to a registered `mcp` tool when one is available. Specific `mcp` rules still override it when a target pattern matches.
+>
+> **Note:** Top-level shorthand is only supported for the canonical Pi built-ins (`bash`, `read`, `write`, `edit`, `grep`, `find`, `ls`) in agent frontmatter. Use `permission.tools.<name>` for `mcp`, `task`, and any third-party tool.
 
 ### `bash`
 
@@ -241,7 +242,7 @@ MCP permissions match against derived targets from tool input. These rules are m
 
 #### MCP Tool Fallback via `tools.mcp`
 
-The `mcp` built-in tool can use `tools.mcp` as an entry permission point. This provides a fallback when no specific MCP pattern matches:
+A registered `mcp` tool can use `tools.mcp` as an entry permission point. This provides a fallback when no specific MCP pattern matches:
 
 ```jsonc
 {
@@ -456,7 +457,7 @@ npx --yes ajv-cli@5 validate \
 |---------|-------|----------|
 | Config not applied (everything asks) | File not found or parse error | Verify file at `~/.pi/agent/pi-permissions.jsonc`; check for trailing commas |
 | Per-agent override not applied | Frontmatter parsing issue | Ensure `---` delimiters at file top; keep YAML simple; restart session |
-| Tool blocked as unregistered | Unknown tool name | Use built-in `mcp` tool for server tools: `{ "tool": "server:tool" }` |
+| Tool blocked as unregistered | Unknown tool name | Use a registered `mcp` tool for server tools: `{ "tool": "server:tool" }` |
 | `/skill:<name>` blocked | Missing context or deny policy | Requires active agent context; `ask` behaves as block in headless mode |
 
 ---

package/config.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-permission-system",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "main": "./index.ts",
@@ -21,7 +21,7 @@
   "scripts": {
     "build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
     "lint": "npm run build",
-    "test": "bun ./src/test.ts",
+    "test": "bun ./src/test.ts && bun ./src/config-modal-test.ts",
     "check": "npm run lint && npm run test"
   },
   "keywords": [
@@ -54,7 +54,8 @@
     ]
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "*",
-    "@sinclair/typebox": "*"
+    "@mariozechner/pi-coding-agent": "^0.62.0",
+    "@mariozechner/pi-tui": "^0.62.0",
+    "@sinclair/typebox": "^0.34.48"
   }
 }

package/schemas/permissions.schema.json

@@ -31,12 +31,14 @@
       }
     },
     "tools": {
+      "description": "Exact-name permissions for registered tools. Use this map for the canonical Pi built-ins and any extension-provided or third-party tools.",
       "$ref": "#/$defs/permissionMap"
     },
     "bash": {
       "$ref": "#/$defs/permissionMap"
     },
     "mcp": {
+      "description": "Pattern-based permissions for targets invoked through a registered `mcp` tool when available.",
       "$ref": "#/$defs/permissionMap"
     },
     "skills": {

package/src/config-modal-test.ts

@@ -0,0 +1,217 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { mock } from "bun:test";
+
+import {
+  DEFAULT_EXTENSION_CONFIG,
+  loadPermissionSystemConfig,
+  savePermissionSystemConfig,
+  type PermissionSystemExtensionConfig,
+} from "./extension-config.js";
+
+mock.module("@mariozechner/pi-coding-agent", () => ({
+  getSettingsListTheme: () => ({}),
+}));
+
+mock.module("@mariozechner/pi-tui", () => ({
+  Box: class {},
+  Container: class {
+    addChild(): void {}
+    render(): string[] {
+      return [];
+    }
+    invalidate(): void {}
+  },
+  SettingsList: class {
+    handleInput(): void {}
+    updateValue(): void {}
+    render(): string[] {
+      return [];
+    }
+    invalidate(): void {}
+  },
+  Spacer: class {},
+  Text: class {},
+  truncateToWidth: (text: string) => text,
+  visibleWidth: (text: string) => text.length,
+}));
+
+const { registerPermissionSystemCommand } = await import("./config-modal.js");
+
+type Notification = { message: string; level: "info" | "warning" | "error" };
+
+type CommandContextStub = {
+  hasUI: boolean;
+  ui: {
+    notify(message: string, level: "info" | "warning" | "error"): void;
+    custom<T>(renderer: (...args: unknown[]) => unknown, options?: unknown): Promise<T>;
+  };
+};
+
+function runTest(name: string, testFn: () => void): void {
+  testFn();
+  console.log(`[PASS] ${name}`);
+}
+
+async function runAsyncTest(name: string, testFn: () => Promise<void>): Promise<void> {
+  await testFn();
+  console.log(`[PASS] ${name}`);
+}
+
+function createCommandContext(
+  hasUI: boolean,
+): { ctx: CommandContextStub; notifications: Notification[]; getCustomCalls(): number } {
+  const notifications: Notification[] = [];
+  let customCalls = 0;
+
+  return {
+    ctx: {
+      hasUI,
+      ui: {
+        notify(message: string, level: "info" | "warning" | "error") {
+          notifications.push({ message, level });
+        },
+        async custom<T>(_renderer: (...args: unknown[]) => unknown, _options?: unknown): Promise<T> {
+          customCalls += 1;
+          return undefined as T;
+        },
+      },
+    },
+    notifications,
+    getCustomCalls: () => customCalls,
+  };
+}
+
+function lastNotification(notifications: Notification[]): Notification {
+  return notifications[notifications.length - 1] as Notification;
+}
+
+runTest("permission-system command completions expose top-level config actions", () => {
+  const baseDir = mkdtempSync(join(tmpdir(), "pi-permission-system-command-completions-"));
+  const configPath = join(baseDir, "config.json");
+  let config: PermissionSystemExtensionConfig = { ...DEFAULT_EXTENSION_CONFIG };
+
+  try {
+    const controller = {
+      getConfig: () => config,
+      setConfig: (next: PermissionSystemExtensionConfig) => {
+        config = next;
+      },
+      getConfigPath: () => configPath,
+    };
+
+    let definition: {
+      description: string;
+      getArgumentCompletions?: (argumentPrefix: string) => Array<{ value: string; label: string; description?: string }> | null;
+      handler: (args: string, ctx: CommandContextStub) => Promise<void>;
+    } | null = null;
+
+    registerPermissionSystemCommand(
+      {
+        registerCommand(_name: string, nextDefinition: typeof definition) {
+          definition = nextDefinition;
+        },
+      } as never,
+      controller as never,
+    );
+
+    assert.ok(definition !== null);
+    assert.ok(typeof definition?.getArgumentCompletions === "function");
+
+    const topLevel = definition?.getArgumentCompletions?.("");
+    assert.ok(Array.isArray(topLevel));
+    assert.ok(topLevel?.some((item) => item.value === "show"));
+    assert.ok(topLevel?.some((item) => item.value === "reset"));
+
+    const filtered = definition?.getArgumentCompletions?.("pa");
+    assert.deepEqual(filtered?.map((item) => item.value), ["path"]);
+    assert.equal(definition?.getArgumentCompletions?.("path extra"), null);
+    assert.equal(definition?.getArgumentCompletions?.("zzz"), null);
+  } finally {
+    rmSync(baseDir, { recursive: true, force: true });
+  }
+});
+
+await runAsyncTest("permission-system command handlers manage config summary, persistence, and modal routing", async () => {
+  const baseDir = mkdtempSync(join(tmpdir(), "pi-permission-system-command-"));
+  const configPath = join(baseDir, "config.json");
+  let config: PermissionSystemExtensionConfig = {
+    debugLog: true,
+    permissionReviewLog: false,
+    yoloMode: true,
+  };
+
+  try {
+    const initialSave = savePermissionSystemConfig(config, configPath);
+    assert.equal(initialSave.success, true);
+
+    const controller = {
+      getConfig: () => config,
+      setConfig: (next: PermissionSystemExtensionConfig) => {
+        const normalized = loadPermissionSystemConfig(configPath).config;
+        const saved = savePermissionSystemConfig(next, configPath);
+        assert.equal(saved.success, true);
+        config = loadPermissionSystemConfig(configPath).config;
+        assert.notDeepEqual(config, normalized);
+      },
+      getConfigPath: () => configPath,
+    };
+
+    let registeredName = "";
+    let definition: {
+      description: string;
+      getArgumentCompletions?: (argumentPrefix: string) => Array<{ value: string; label: string; description?: string }> | null;
+      handler: (args: string, ctx: CommandContextStub) => Promise<void>;
+    } | null = null;
+
+    registerPermissionSystemCommand(
+      {
+        registerCommand(name: string, nextDefinition: typeof definition) {
+          registeredName = name;
+          definition = nextDefinition;
+        },
+      } as never,
+      controller as never,
+    );
+
+    assert.equal(registeredName, "permission-system");
+    assert.ok(definition !== null);
+    assert.ok((definition?.description ?? "").includes("Configure pi-permission-system"));
+
+    const infoCtx = createCommandContext(true);
+    await definition?.handler("show", infoCtx.ctx);
+    assert.ok(lastNotification(infoCtx.notifications).message.includes("yoloMode=on"));
+    assert.ok(lastNotification(infoCtx.notifications).message.includes("debugLog=on"));
+
+    await definition?.handler("path", infoCtx.ctx);
+    assert.equal(lastNotification(infoCtx.notifications).message, `permission-system config: ${configPath}`);
+
+    await definition?.handler("help", infoCtx.ctx);
+    assert.ok(lastNotification(infoCtx.notifications).message.includes("Usage: /permission-system"));
+
+    await definition?.handler("reset", infoCtx.ctx);
+    assert.deepEqual(config, DEFAULT_EXTENSION_CONFIG);
+    assert.equal(lastNotification(infoCtx.notifications).message, "Permission system settings reset to defaults.");
+
+    const persisted = JSON.parse(readFileSync(configPath, "utf8")) as Record<string, unknown>;
+    assert.deepEqual(persisted, DEFAULT_EXTENSION_CONFIG);
+
+    await definition?.handler("unknown", infoCtx.ctx);
+    assert.equal(lastNotification(infoCtx.notifications).level, "warning");
+    assert.ok(lastNotification(infoCtx.notifications).message.includes("Usage: /permission-system"));
+
+    const headlessCtx = createCommandContext(false);
+    await definition?.handler("", headlessCtx.ctx);
+    assert.equal(lastNotification(headlessCtx.notifications).message, "/permission-system requires interactive TUI mode.");
+
+    const modalCtx = createCommandContext(true);
+    await definition?.handler("", modalCtx.ctx);
+    assert.equal(modalCtx.getCustomCalls(), 1);
+  } finally {
+    rmSync(baseDir, { recursive: true, force: true });
+  }
+});
+
+console.log("All permission-system config-modal tests passed.");

package/src/config-modal.ts

@@ -0,0 +1,231 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import type { SettingItem } from "@mariozechner/pi-tui";
+
+import { DEFAULT_EXTENSION_CONFIG, 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"];
+const COMMAND_ARGUMENTS = [
+  {
+    value: "show",
+    label: "Show active settings",
+    description: "Display the current permission-system config summary",
+  },
+  {
+    value: "path",
+    label: "Show config path",
+    description: "Display the config.json path used by pi-permission-system",
+  },
+  {
+    value: "reset",
+    label: "Reset defaults",
+    description: "Restore default yolo/logging settings and persist them",
+  },
+  {
+    value: "help",
+    label: "Show help",
+    description: "Display command usage",
+  },
+] as const;
+const USAGE_TEXT = "Usage: /permission-system [show|path|reset|help] (or run /permission-system with no args to open settings modal)";
+
+function cloneDefaultConfig(): PermissionSystemExtensionConfig {
+  return {
+    debugLog: DEFAULT_EXTENSION_CONFIG.debugLog,
+    permissionReviewLog: DEFAULT_EXTENSION_CONFIG.permissionReviewLog,
+    yoloMode: DEFAULT_EXTENSION_CONFIG.yoloMode,
+  };
+}
+
+function toOnOff(value: boolean): string {
+  return value ? "on" : "off";
+}
+
+function summarizeConfig(config: PermissionSystemExtensionConfig): string {
+  return [
+    `yoloMode=${toOnOff(config.yoloMode)}`,
+    `permissionReviewLog=${toOnOff(config.permissionReviewLog)}`,
+    `debugLog=${toOnOff(config.debugLog)}`,
+  ].join(", ");
+}
+
+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: "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 "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("debugLog", toOnOff(config.debugLog));
+}
+
+function getArgumentCompletions(argumentPrefix: string): Array<{ value: string; label: string; description: string }> | null {
+  const normalized = argumentPrefix.trim().toLowerCase();
+  if (normalized.includes(" ")) {
+    return null;
+  }
+
+  const filtered = COMMAND_ARGUMENTS.filter((item) => item.value.startsWith(normalized));
+  return filtered.length > 0 ? [...filtered] : null;
+}
+
+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: `/permission-system show • /permission-system reset • ${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 },
+  );
+}
+
+function handleArgs(args: string, ctx: ExtensionCommandContext, controller: PermissionSystemConfigController): boolean {
+  const normalized = args.trim().toLowerCase();
+  if (!normalized) {
+    return false;
+  }
+
+  if (normalized === "show") {
+    ctx.ui.notify(`permission-system: ${summarizeConfig(controller.getConfig())}`, "info");
+    return true;
+  }
+
+  if (normalized === "path") {
+    ctx.ui.notify(`permission-system config: ${controller.getConfigPath()}`, "info");
+    return true;
+  }
+
+  if (normalized === "reset") {
+    controller.setConfig(cloneDefaultConfig(), ctx);
+    ctx.ui.notify("Permission system settings reset to defaults.", "info");
+    return true;
+  }
+
+  if (normalized === "help") {
+    ctx.ui.notify(USAGE_TEXT, "info");
+    return true;
+  }
+
+  ctx.ui.notify(USAGE_TEXT, "warning");
+  return true;
+}
+
+export function registerPermissionSystemCommand(pi: ExtensionAPI, controller: PermissionSystemConfigController): void {
+  pi.registerCommand("permission-system", {
+    description: "Configure pi-permission-system logging and yolo-mode behavior",
+    getArgumentCompletions,
+    handler: async (args, ctx) => {
+      if (handleArgs(args, ctx, controller)) {
+        return;
+      }
+
+      if (!ctx.hasUI) {
+        ctx.ui.notify("/permission-system requires interactive TUI mode.", "warning");
+        return;
+      }
+
+      await openSettingsModal(ctx, controller);
+    },
+  });
+}