pi-permission-system 0.4.7 → 0.4.8

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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).
 
+## [Unreleased]
+
+## [0.4.8] - 2026-05-04
+
+### Added
+- Added runtime yolo-mode control through the `/permission-system` settings modal and `globalThis.__piPermissionSystem` for other extensions.
+- Added wildcard support for `permission.tools` so direct tools from any extension can be controlled without adapter-specific hardcoding.
+- Added `PI_PERMISSION_SYSTEM_POLICY_AGENT_DIR` so global policy and global agent override lookup can be pointed at a different agent root when needed.
+
+### Changed
+- Simplified `/permission-system` to only open the settings modal, removing the previous `show`, `path`, `reset`, `help`, and `yolo ...` subcommands.
+- Expanded the README with an OpenCode-to-Pi migration guide covering agent file placement, frontmatter structure, permission mapping, Pi-specific `tools` vs `mcp` behavior, and policy-root overrides.
+
+### Fixed
+- Removed artifact validation that forced local runtime `config.json` values to match release defaults.
+- Restored requested bash command text in permission review log entries while keeping prompts and generic tool payload previews redacted.
+- Clarified last-declared-match wildcard precedence in the README and fixed wildcard-order examples/recipes so documented `tools` and `mcp` examples now match runtime behavior (thanks to @Nateowami for issue #17 and @gotgenes for the rule-order diagnosis).
+- Replaced the removed `session_switch` lifecycle subscription with a single supported `session_start` refresh path so session changes rebuild runtime permission state without duplicate handlers (thanks to @gotgenes for PR #11).
+- Removed stale README wording around exact-name tool matching and refreshed the documented architecture/module list to match the current extension layout.
+
 ## [0.4.7] - 2026-05-04
 
 ### Added

package/README.md

@@ -6,6 +6,87 @@ Permission enforcement extension for the Pi coding agent that provides centraliz
 
 <img width="1360" height="752" alt="image" src="https://github.com/user-attachments/assets/3e85190a-17fa-4d94-ac8e-efa54337df5d" />
 
+## Coming from OpenCode?
+
+Yes — this extension was designed so OpenCode-style agent permission policies can be ported into Pi with minimal friction.
+
+### Start here
+
+| If you have this in OpenCode | In Pi, use this |
+|---|---|
+| Agent markdown file | `~/.pi/agent/agents/<agent-name>.md` (respects `PI_CODING_AGENT_DIR`) |
+| YAML frontmatter | Same place: top of the markdown file |
+| Agent instructions / system prompt body | Same file, below frontmatter |
+| Agent permission rules | `permission:` inside that same frontmatter |
+
+### Important compatibility notes
+
+- **Agents are still markdown files with YAML frontmatter.**
+- **Wildcard permissions still use last-match-wins ordering.**
+- **Keep frontmatter simple when porting.** This extension intentionally supports `key: value` scalars and nested maps, not full YAML features like arrays, anchors, or multiline scalars.
+
+### Minimal Pi agent example
+
+```md
+---
+name: my-agent
+mode: primary
+description: My ported agent
+permission:
+  tools:
+    read: allow
+    grep: allow
+  bash:
+    "*": ask
+  mcp:
+    "*": ask
+---
+
+Your agent instructions go here.
+```
+
+### Compatibility matrix
+
+| OpenCode concept | Pi equivalent with this extension | Compatibility | Porting notes |
+|---|---|---:|---|
+| Agent markdown files with YAML frontmatter | `~/.pi/agent/agents/<agent-name>.md` | High | Your agent-local `permission:` frontmatter pattern carries over cleanly. |
+| Wildcard precedence | Same last-declared-match-wins behavior | High | Broad rules first, specific overrides later. |
+| `bash` permission rules | `permission.bash` | High | Command-pattern gating ports cleanly. |
+| Per-tool permission rules like `read`, `grep`, `list`, `task`, or arbitrary extension tool names | `permission.tools` | Medium-High | Pi groups registered tool names under `tools`, including built-ins and extension tools. |
+| `external_directory` | `permission.special.external_directory` | Medium | Same idea, different location. |
+| `doom_loop` | `permission.special.doom_loop` | Medium | Same idea, different location. |
+| `skill` permission rules | `permission.skills` | Medium | Same purpose, but Pi uses a dedicated plural `skills` section. |
+| MCP-related access | `permission.mcp` for proxy targets, `permission.tools` for direct registered tools | Medium | This is the biggest Pi-specific difference: proxy MCP targets and direct tool names are intentionally split. |
+| OpenCode-specific permissions like `webfetch`, `websearch`, `question`, `lsp`, `todowrite` | Usually extension-specific Pi tool names under `permission.tools` | Low-Medium | These do not have universal built-in one-to-one Pi names; map them to the actual registered tools available in your Pi setup. |
+
+### Most important difference
+
+In OpenCode, many permission names live in one broad permission namespace. In Pi with this extension, there is a deliberate split:
+
+| Use this when... | Put the rule here |
+|---|---|
+| You are targeting the registered **`mcp` proxy tool** and its internal server/tool targets | `permission.mcp` |
+| You are targeting an actual registered tool name, including direct extension tools like `context7_*`, `github_*`, or `exa_*` | `permission.tools` |
+
+### Fast porting guide
+
+| If your OpenCode agent has... | In Pi, do this |
+|---|---|
+| `permission.bash` rules | Move them into `permission.bash` |
+| `permission.external_directory` | Move it to `permission.special.external_directory` |
+| `permission.doom_loop` | Move it to `permission.special.doom_loop` |
+| `permission.skill` rules | Move them to `permission.skills` |
+| Tool-ish permissions like `read`, `grep`, `list`, `task`, or third-party tool names | Put them in `permission.tools` |
+| MCP server/tool target logic | Put proxy-target rules in `permission.mcp` |
+
+### Practical takeaway
+
+If you are coming from OpenCode, you usually do **not** need to rewrite your whole agent. In most cases, porting is just:
+
+1. Keep the agent markdown/frontmatter structure.
+2. Move OpenCode-style tool permissions into Pi's `tools` section.
+3. Move `external_directory` and `doom_loop` into `special`.
+4. Split MCP proxy target rules into `mcp` and direct registered tool rules into `tools`.
 
 ## Features
 
@@ -17,6 +98,7 @@ Permission enforcement extension for the Pi coding agent that provides centraliz
 - **Skill Protection** — Controls which skills can be loaded or read from disk, including multi-block prompt sanitization
 - **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
 - **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
@@ -41,7 +123,7 @@ Place this folder in one of the following locations:
 
 Pi auto-discovers extensions in these paths.
 
-> **Tip:** All `~/.pi/agent` paths shown in this document are defaults. If the `PI_CODING_AGENT_DIR` environment variable is set, pi uses that directory instead. The extension automatically follows pi's `getAgentDir()` helper, so global policy files, per-agent overrides, session directories, and extension installation paths all resolve under the configured agent directory.
+> **Tip:** All `~/.pi/agent` paths shown in this document are defaults. If the `PI_CODING_AGENT_DIR` environment variable is set, pi uses that directory instead. The extension automatically follows pi's `getAgentDir()` helper for extension installation, session directories, and extension-local config paths. If you need policy lookup to come from a different global agent root, set `PI_PERMISSION_SYSTEM_POLICY_AGENT_DIR`.
 
 ## Usage
 
@@ -90,10 +172,10 @@ 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
-- Extension-provided tools like `task`, `mcp`, and third-party tools are handled by exact registered name instead of private built-in hardcodes
+- 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 without writing raw prompts, commands, or tool payload previews
+- Permission review logs include requested bash command text plus redacted prompt/input metadata for auditing without writing raw prompts or generic tool payload previews
 - 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`
 
 ## Configuration
@@ -104,7 +186,7 @@ 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 only extension-local logging behavior:
+The extension creates this file automatically when it is missing. It controls extension-local logging behavior and yolo mode defaults:
 
 ```json
 {
@@ -122,16 +204,43 @@ The extension creates this file automatically when it is missing. It controls on
 
 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.
 
+### Runtime YOLO Control
+
+Use `/permission-system` to open the settings modal and inspect or change yolo mode interactively.
+
+Other extensions can toggle yolo mode immediately through the shared runtime API:
+
+```ts
+type PermissionSystemGlobal = typeof globalThis & {
+  __piPermissionSystem?: {
+    toggleYoloMode(options?: { persist?: boolean; source?: string }): { error?: string };
+  };
+};
+
+pi.registerShortcut("f8", {
+  description: "Toggle pi-permission-system YOLO mode",
+  handler: () => {
+    const permissionSystem = (globalThis as PermissionSystemGlobal).__piPermissionSystem;
+    const result = permissionSystem?.toggleYoloMode({ source: "my-extension" });
+    if (result?.error) {
+      // Notify or log the error in your extension.
+    }
+  },
+});
+```
+
+The runtime API exposes `getYoloMode()`, `setYoloMode(enabled, options?)`, and `toggleYoloMode(options?)`. Runtime updates persist to `config.json` by default; pass `{ persist: false }` for a current-session-only toggle.
+
 ### Global Policy File
 
-**Location:** global Pi policy file (default: `~/.pi/agent/pi-permissions.jsonc`, respects `PI_CODING_AGENT_DIR`)
+**Location:** global Pi policy file (default: `~/.pi/agent/pi-permissions.jsonc`, respects `PI_PERMISSION_SYSTEM_POLICY_AGENT_DIR` when set and otherwise follows `PI_CODING_AGENT_DIR`)
 
 The policy file is a JSON object with these sections:
 
 | Section         | Description                                         |
 |-----------------|-----------------------------------------------------|
 | `defaultPolicy` | Fallback permissions per category                   |
-| `tools`         | Exact-name tool permissions for registered tools    |
+| `tools`         | Pattern-based 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                      |
@@ -141,7 +250,7 @@ The policy file is a JSON object with these sections:
 
 ### Global Per-Agent Overrides
 
-Override global permissions for specific agents via YAML frontmatter in the global Pi agents directory (default: `~/.pi/agent/agents/<agent>.md`, respects `PI_CODING_AGENT_DIR`):
+Override global permissions for specific agents via YAML frontmatter in the global Pi agents directory (default: `~/.pi/agent/agents/<agent-name>.md`, respects `PI_PERMISSION_SYSTEM_POLICY_AGENT_DIR` when set and otherwise follows `PI_CODING_AGENT_DIR`):
 
 ```yaml
 ---
@@ -164,7 +273,7 @@ permission:
 
 **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.
+**Limitations:** The frontmatter parser is intentionally minimal. Use only `key: value` scalars and nested maps. Avoid arrays, multi-line scalars, and YAML anchors. If you are porting from OpenCode, simplify richer YAML frontmatter before expecting a clean migration.
 
 ### Project-Level Policy Files
 
@@ -173,7 +282,7 @@ The extension can also layer project-local permission files relative to the acti
 | Scope | Path |
 |-------|------|
 | Project policy | `<cwd>/.pi/agent/pi-permissions.jsonc` |
-| Project agent override | `<cwd>/.pi/agent/agents/<agent>.md` |
+| Project agent override | `<cwd>/.pi/agent/agents/<agent-name>.md` |
 
 Project-local files use the same formats as the global policy file and global agent frontmatter. These project files are resolved from Pi's current session `cwd`, so they are workspace-specific and do **not** move under `PI_CODING_AGENT_DIR`.
 
@@ -183,7 +292,7 @@ Project-local files use the same formats as the global policy file and global ag
 3. Global agent frontmatter
 4. Project agent frontmatter
 
-Later trusted layers override earlier layers within the same permission category, and project-local layers can tighten policy by adding `deny` rules. Project-local policy cannot relax a `deny` from the global policy file or global agent frontmatter: an `allow` or `ask` in a project policy is ignored when the latest matching trusted layer is `deny`. For wildcard-based sections like `bash`, `mcp`, `skills`, and `special`, matching still follows **last matching rule wins** within the applicable trust boundary, with global/system `deny` rules acting as floors for project-local overrides.
+Later trusted layers override earlier layers within the same permission category, and project-local layers can tighten policy by adding `deny` rules. Project-local policy cannot relax a `deny` from the global policy file or global agent frontmatter: an `allow` or `ask` in a project policy is ignored when the latest matching trusted layer is `deny`. For wildcard-based sections like `tools`, `bash`, `mcp`, `skills`, and `special`, matching still follows **last matching rule wins** within the applicable trust boundary, with global/system `deny` rules acting as floors for project-local overrides.
 
 ---
 
@@ -207,7 +316,7 @@ Sets fallback permissions when no specific rule matches:
 
 ### `tools`
 
-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.
+Controls tools by registered name pattern. This is the recommended standalone format for **all** tool entries, including Pi built-ins and arbitrary third-party extension tools. Patterns use `*` wildcards and follow last-declared-match semantics, so put broad fallbacks first and specific overrides later.
 
 | Tool name example     | Description |
 |-----------------------|-------------|
@@ -216,29 +325,33 @@ Controls tools by exact registered name (no wildcards). This is the recommended
 | `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 |
+| `context7_*`          | Wildcard for direct tools registered by another extension |
+| `*`                   | Fallback for every registered tool not matched by a later rule |
 
 ```jsonc
 {
   "tools": {
-    "read": "allow",
-    "write": "deny",
+    "*": "ask",
+    "context7_*": "ask",
+    "third_party_tool": "ask",
     "mcp": "allow",
-    "third_party_tool": "ask"
+    "read": "allow",
+    "write": "deny"
   }
 }
 ```
 
-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.
+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. Wildcard `tools` rules apply to direct tools from any extension; no adapter-specific naming is required.
 
 > **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 a registered `mcp` tool when one is available. Specific `mcp` rules still override it when a target pattern matches.
+> **Note:** Setting `tools.mcp` controls coarse access to a registered `mcp` proxy tool when one is available. Specific `mcp` rules still override it when a proxy target pattern matches. Direct MCP tools registered by extensions are regular registered tools and should be controlled with `tools` patterns such as `context7_*` or `github_*`.
 >
 > **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`
 
-Command patterns use `*` wildcards and match against the full command string. If multiple patterns match, the **last matching rule wins**.
+Command patterns use `*` wildcards and match against the full command string. If multiple patterns match, the **last declared matching rule wins**. Put broad fallback rules first and more specific overrides later.
 
 ```jsonc
 {
@@ -264,9 +377,10 @@ MCP permissions match against derived targets from tool input. These rules are m
 ```jsonc
 {
   "mcp": {
+    "*": "ask",
+    "myServer:*": "ask",
     "mcp_status": "allow",
     "mcp_list": "allow",
-    "myServer:*": "ask",
     "dangerousServer": "deny"
   }
 }
@@ -362,10 +476,10 @@ Reserved permission checks:
 {
   "defaultPolicy": { "tools": "ask", "bash": "deny", "mcp": "ask", "skills": "ask", "special": "ask" },
   "bash": {
+    "git *": "ask",
     "git status": "allow",
     "git diff": "allow",
-    "git log *": "allow",
-    "git *": "ask"
+    "git log *": "allow"
   }
 }
 ```
@@ -376,11 +490,11 @@ Reserved permission checks:
 {
   "defaultPolicy": { "tools": "ask", "bash": "ask", "mcp": "ask", "skills": "ask", "special": "ask" },
   "mcp": {
+    "*": "ask",
     "mcp_status": "allow",
     "mcp_list": "allow",
     "mcp_search": "allow",
-    "mcp_describe": "allow",
-    "*": "ask"
+    "mcp_describe": "allow"
   }
 }
 ```
@@ -441,26 +555,36 @@ Override logs directory: $PI_PERMISSION_SYSTEM_LOGS_DIR when set
 ### Architecture
 
 ```
-index.ts                    → Root Pi entrypoint shim
+index.ts                         → Root Pi entrypoint shim
 src/
-├── index.ts                → Extension bootstrap, permission checks, readable prompts, review logging, reload handling, and subagent forwarding
-├── extension-config.ts     → Extension-local config loading and default creation
-├── logging.ts              → File-only debug/review logging helpers
-├── permission-manager.ts   → Global/project policy loading, merging, and resolution with caching
-├── skill-prompt-sanitizer.ts → Skill prompt parsing, multi-block sanitization, and skill-read path matching
-├── bash-filter.ts          → Bash command wildcard pattern matching
-├── wildcard-matcher.ts     → Shared wildcard pattern compilation and matching
-├── common.ts               → Shared utilities (YAML parsing, type guards, etc.)
-├── tool-registry.ts        → Registered tool name resolution
-└── types.ts                → TypeScript type definitions
+├── index.ts                     → Extension bootstrap, permission checks, readable prompts, review logging, 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
+├── 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
+├── permission-manager.ts        → Global/project policy loading, merging, and resolution with caching
+├── skill-prompt-sanitizer.ts    → Skill prompt parsing, multi-block sanitization, and skill-read path matching
+├── status.ts                    → Status line integration for runtime yolo state
+├── system-prompt-sanitizer.ts   → Available-tools prompt filtering helpers
+├── tool-registry.ts             → Registered tool name resolution
+├── types.ts                     → TypeScript type definitions
+├── wildcard-matcher.ts          → Shared wildcard pattern compilation and matching
+├── yolo-mode.ts                 → Runtime yolo approval helpers
+├── yolo-mode-api.ts             → Shared global runtime API for yolo toggling
+└── zellij-modal.ts              → Reusable modal/settings UI components
 tests/
-├── permission-system.test.ts → Core permission, layering, forwarding, and policy tests
-├── config-modal.test.ts      → Config command and modal behavior tests
-└── test-harness.ts           → Shared lightweight test helpers
+├── permission-system.test.ts    → Core permission, layering, forwarding, and policy tests
+├── config-modal.test.ts         → Modal command behavior tests
+└── test-harness.ts              → Shared lightweight test helpers
 schemas/
-└── permissions.schema.json → JSON Schema for policy validation
+└── permissions.schema.json      → JSON Schema for policy validation
 config/
-└── config.example.json     → Starter global policy template
+└── config.example.json          → Starter global policy template
 ```
 
 #### Module Organization

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-permission-system",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "main": "./index.ts",

package/schemas/permissions.schema.json

@@ -31,7 +31,7 @@
       }
     },
     "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.",
+      "description": "Pattern-based permissions for registered tools. Use exact names or `*` wildcards for canonical Pi built-ins and any extension-provided or third-party tools.",
       "$ref": "#/$defs/permissionMap"
     },
     "bash": {

package/src/config-modal.ts

@@ -1,7 +1,7 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
 import type { SettingItem } from "@mariozechner/pi-tui";
 
-import { cloneDefaultConfig, type PermissionSystemExtensionConfig } from "./extension-config.js";
+import type { PermissionSystemExtensionConfig } from "./extension-config.js";
 import { ZellijModal, ZellijSettingsModal } from "./zellij-modal.js";
 
 interface PermissionSystemConfigController {
@@ -15,42 +15,11 @@ interface SettingValueSyncTarget {
 }
 
 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 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 [
     {
@@ -100,16 +69,6 @@ function syncSettingValues(settingsList: SettingValueSyncTarget, config: Permiss
   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 };
 
@@ -132,7 +91,7 @@ async function openSettingsModal(ctx: ExtensionCommandContext, controller: Permi
             }
           },
           onClose: () => done(),
-          helpText: `/permission-system show • /permission-system reset • ${controller.getConfigPath()}`,
+          helpText: `Config file: ${controller.getConfigPath()}`,
           enableSearch: true,
         },
         theme,
@@ -172,46 +131,10 @@ async function openSettingsModal(ctx: ExtensionCommandContext, controller: Permi
   );
 }
 
-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;
-      }
-
+    handler: async (_args, ctx) => {
       if (!ctx.hasUI) {
         ctx.ui.notify("/permission-system requires interactive TUI mode.", "warning");
         return;

package/src/index.ts

@@ -47,6 +47,13 @@ import { checkRequestedToolRegistration, getToolNameFromValue } from "./tool-reg
 import type { PermissionCheckResult } from "./types.js";
 import { PERMISSION_SYSTEM_STATUS_KEY, syncPermissionSystemStatus } from "./status.js";
 import { canResolveAskPermissionRequest, shouldAutoApprovePermissionState } from "./yolo-mode.js";
+import {
+  registerPiPermissionSystemRuntimeApi,
+  unregisterPiPermissionSystemRuntimeApi,
+  type PiPermissionSystemRuntimeApi,
+  type YoloModeControlOptions,
+  type YoloModeControlResult,
+} from "./yolo-mode-api.js";
 import { registerModelOptionCompatibilityGuard } from "./model-option-compatibility.js";
 
 const PI_AGENT_DIR = getAgentDir();
@@ -82,6 +89,7 @@ const PERMISSION_REQUEST_EVENT_CHANNEL = "pi-permission-system:permission-reques
 const PATH_BEARING_TOOLS = new Set(["read", "write", "edit", "find", "grep", "ls"]);
 
 let extensionConfig: PermissionSystemExtensionConfig = { ...DEFAULT_EXTENSION_CONFIG };
+let runtimeApi: PiPermissionSystemRuntimeApi | null = null;
 const extensionLogger = createPermissionSystemLogger({
   getConfig: () => extensionConfig,
 });
@@ -514,8 +522,14 @@ function createSensitiveLogMetadata(value: string | undefined): SensitiveLogMeta
 function getPermissionLogContext(
   result: PermissionCheckResult,
   input: unknown,
-): { commandMetadata: SensitiveLogMetadata | null; target?: string; toolInputPreviewMetadata: SensitiveLogMetadata | null } {
+): {
+  command?: string;
+  commandMetadata: SensitiveLogMetadata | null;
+  target?: string;
+  toolInputPreviewMetadata: SensitiveLogMetadata | null;
+} {
   return {
+    command: result.toolName === "bash" && result.command ? result.command : undefined,
     commandMetadata: createSensitiveLogMetadata(result.command),
     target: result.target,
     toolInputPreviewMetadata: createSensitiveLogMetadata(getToolInputPreviewForLog(result, input)),
@@ -1066,6 +1080,20 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     });
   };
 
+  const syncPermissionSystemStatusWhenPossible = (
+    config: PermissionSystemExtensionConfig,
+    ctx?: ExtensionCommandContext | ExtensionContext,
+  ): void => {
+    if (ctx) {
+      syncPermissionSystemStatus(ctx, config);
+      return;
+    }
+
+    if (runtimeContext?.hasUI) {
+      syncPermissionSystemStatus(runtimeContext, config);
+    }
+  };
+
   const saveExtensionConfig = (next: PermissionSystemExtensionConfig, ctx: ExtensionCommandContext): void => {
     const normalized = normalizePermissionSystemConfig(next);
     const saved = savePermissionSystemConfig(normalized);
@@ -1077,7 +1105,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     }
 
     setExtensionConfig(normalized);
-    syncPermissionSystemStatus(ctx, normalized);
+    syncPermissionSystemStatusWhenPossible(normalized, ctx);
     lastConfigWarning = null;
 
     writeDebugLog("config.saved", {
@@ -1087,8 +1115,62 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     });
   };
 
+  const setYoloModeFromRuntimeApi = (enabled: boolean, options: YoloModeControlOptions = {}): YoloModeControlResult => {
+    if (typeof enabled !== "boolean") {
+      return {
+        yoloMode: extensionConfig.yoloMode,
+        changed: false,
+        persisted: false,
+        error: "setYoloMode(enabled) requires a boolean value.",
+      };
+    }
+
+    const normalized = normalizePermissionSystemConfig({ ...extensionConfig, yoloMode: enabled });
+    const persisted = options.persist !== false;
+    const changed = extensionConfig.yoloMode !== normalized.yoloMode;
+
+    if (persisted) {
+      const saved = savePermissionSystemConfig(normalized);
+      if (!saved.success) {
+        const error = saved.error ?? "Failed to persist pi-permission-system config.";
+        writeDebugLog("yolo_mode.update_failed", {
+          error,
+          requestedYoloMode: normalized.yoloMode,
+          source: getNonEmptyString(options.source) ?? "runtime-api",
+        });
+        return {
+          yoloMode: extensionConfig.yoloMode,
+          changed: false,
+          persisted: false,
+          error,
+        };
+      }
+      lastConfigWarning = null;
+    }
+
+    setExtensionConfig(normalized);
+    syncPermissionSystemStatusWhenPossible(normalized);
+    writeDebugLog("yolo_mode.updated", {
+      changed,
+      persisted,
+      source: getNonEmptyString(options.source) ?? "runtime-api",
+      yoloMode: normalized.yoloMode,
+    });
+
+    return {
+      yoloMode: normalized.yoloMode,
+      changed,
+      persisted,
+    };
+  };
+
   setLoggingWarningReporter(notifyWarning);
   refreshExtensionConfig();
+  runtimeApi = registerPiPermissionSystemRuntimeApi({
+    getYoloMode: () => extensionConfig.yoloMode,
+    setYoloMode: setYoloModeFromRuntimeApi,
+    toggleYoloMode: (options?: YoloModeControlOptions) => setYoloModeFromRuntimeApi(!extensionConfig.yoloMode, options),
+  });
   registerModelOptionCompatibilityGuard(pi);
 
   registerPermissionSystemCommand(pi, {
@@ -1125,6 +1207,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       toolName?: string;
       skillName?: string;
       path?: string;
+      command?: string;
       commandMetadata?: SensitiveLogMetadata | null;
       target?: string;
       toolInputPreviewMetadata?: SensitiveLogMetadata | null;
@@ -1141,6 +1224,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       toolName: details.toolName ?? null,
       skillName: details.skillName ?? null,
       path: details.path ?? null,
+      command: details.command ?? null,
       commandMetadata: details.commandMetadata ?? null,
       target: details.target ?? null,
       toolInputPreviewMetadata: details.toolInputPreviewMetadata ?? null,
@@ -1160,6 +1244,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       toolName?: string;
       skillName?: string;
       path?: string;
+      command?: string;
       commandMetadata?: SensitiveLogMetadata | null;
       target?: string;
       toolInputPreviewMetadata?: SensitiveLogMetadata | null;
@@ -1176,6 +1261,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
         toolName: details.toolName,
         skillName: details.skillName,
         path: details.path,
+        command: details.command,
         target: details.target,
         agentName: details.agentName,
       });
@@ -1192,6 +1278,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       toolName: details.toolName,
       skillName: details.skillName,
       path: details.path,
+      command: details.command,
       target: details.target,
       agentName: details.agentName,
     });
@@ -1211,6 +1298,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       toolName: details.toolName,
       skillName: details.skillName,
       path: details.path,
+      command: details.command,
       target: details.target,
       agentName: details.agentName,
     });
@@ -1276,13 +1364,17 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     return toolPermission !== "deny";
   };
 
-  pi.on("session_start", async (event, ctx) => {
+  const refreshSessionRuntimeState = (ctx: ExtensionContext): void => {
     runtimeContext = ctx;
     refreshExtensionConfig(ctx);
     permissionManager = createPermissionManagerForCwd(ctx.cwd);
     invalidateAgentStartCache();
     lastKnownActiveAgentName = getActiveAgentName(ctx);
     startForwardedPermissionPolling(ctx);
+  };
+
+  pi.on("session_start", async (event, ctx) => {
+    refreshSessionRuntimeState(ctx);
 
     if (event.reason === "reload") {
       writeDebugLog("lifecycle.reload", {
@@ -1293,15 +1385,6 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     }
   });
 
-  pi.on("session_switch", async (_event, ctx) => {
-    runtimeContext = ctx;
-    refreshExtensionConfig(ctx);
-    permissionManager = createPermissionManagerForCwd(ctx.cwd);
-    invalidateAgentStartCache();
-    lastKnownActiveAgentName = getActiveAgentName(ctx);
-    startForwardedPermissionPolling(ctx);
-  });
-
   pi.on("resources_discover", async (event, _ctx) => {
     if (event.reason === "reload") {
       permissionManager = runtimeContext ? createPermissionManagerForCwd(runtimeContext.cwd) : new PermissionManager();
@@ -1318,6 +1401,8 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   pi.on("session_shutdown", async () => {
     runtimeContext?.ui.setStatus(PERMISSION_SYSTEM_STATUS_KEY, undefined);
     runtimeContext = null;
+    unregisterPiPermissionSystemRuntimeApi(runtimeApi ?? undefined);
+    runtimeApi = null;
     invalidateAgentStartCache();
     stopForwardedPermissionPolling();
   });

package/src/permission-manager.ts

@@ -1,6 +1,6 @@
 import { getAgentDir } from "@mariozechner/pi-coding-agent";
 import { readFileSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 
 import { extractFrontmatter, getNonEmptyString, isPermissionState, parseSimpleYamlMap, toRecord } from "./common.js";
 import type {
@@ -17,10 +17,17 @@ import {
   type CompiledWildcardPattern,
 } from "./wildcard-matcher.js";
 
-function defaultGlobalConfigPath(): string { return join(getAgentDir(), "pi-permissions.jsonc"); }
-function defaultAgentsDir(): string { return join(getAgentDir(), "agents"); }
-function defaultLegacyGlobalSettingsPath(): string { return join(getAgentDir(), "settings.json"); }
-function defaultGlobalMcpConfigPath(): string { return join(getAgentDir(), "mcp.json"); }
+const PERMISSION_POLICY_AGENT_DIR_ENV_KEY = "PI_PERMISSION_SYSTEM_POLICY_AGENT_DIR";
+
+function defaultPolicyAgentDir(): string {
+  const override = process.env[PERMISSION_POLICY_AGENT_DIR_ENV_KEY]?.trim();
+  return override ? resolve(override) : getAgentDir();
+}
+
+function defaultGlobalConfigPath(): string { return join(defaultPolicyAgentDir(), "pi-permissions.jsonc"); }
+function defaultAgentsDir(): string { return join(defaultPolicyAgentDir(), "agents"); }
+function defaultLegacyGlobalSettingsPath(): string { return join(defaultPolicyAgentDir(), "settings.json"); }
+function defaultGlobalMcpConfigPath(): string { return join(defaultPolicyAgentDir(), "mcp.json"); }
 
 const BUILT_IN_TOOL_PERMISSION_NAMES = new Set(["bash", "read", "write", "edit", "grep", "find", "ls"]);
 const SPECIAL_PERMISSION_KEYS = new Set(["doom_loop", "external_directory"]);
@@ -384,6 +391,7 @@ type ResolvedPermissions = {
   agentConfig: AgentPermissions;
   merged: GlobalPermissionConfig;
   layers: readonly PermissionLayer[];
+  compiledTools: CompiledPermissionPatterns;
   compiledSpecial: CompiledPermissionPatterns;
   compiledSkills: CompiledPermissionPatterns;
   compiledMcp: CompiledPermissionPatterns;
@@ -754,6 +762,7 @@ export class PermissionManager {
       agentConfig,
       merged,
       layers,
+      compiledTools: compilePermissionPatternsFromLayers("tools", layers),
       compiledSpecial: compilePermissionPatternsFromLayers("special", layers),
       compiledSkills: compilePermissionPatternsFromLayers("skills", layers),
       compiledMcp: compilePermissionPatternsFromLayers("mcp", layers),
@@ -798,7 +807,7 @@ export class PermissionManager {
    * @returns The permission state for the tool at the tool level
    */
   getToolPermission(toolName: string, agentName?: string): PermissionState {
-    const { layers } = this.resolvePermissions(agentName);
+    const { layers, compiledTools } = this.resolvePermissions(agentName);
     const normalizedToolName = toolName.trim();
 
     if (SPECIAL_PERMISSION_KEYS.has(normalizedToolName)) {
@@ -809,26 +818,29 @@ export class PermissionManager {
       return resolveLayeredDefaultPermission(layers, "skills")?.state ?? DEFAULT_POLICY.skills;
     }
 
+    const toolMatch = findCompiledPermissionMatch(compiledTools, normalizedToolName);
+
     if (normalizedToolName === "bash") {
-      return resolveLayeredRecordPermission(layers, "tools", "bash")?.state
+      return toolMatch?.state
         ?? resolveLayeredDefaultPermission(layers, "bash")?.state
         ?? DEFAULT_POLICY.bash;
     }
 
     if (normalizedToolName === "mcp") {
-      return resolveLayeredRecordPermission(layers, "tools", "mcp")?.state
+      return toolMatch?.state
         ?? resolveLayeredDefaultPermission(layers, "mcp")?.state
         ?? DEFAULT_POLICY.mcp;
     }
 
-    return resolveLayeredRecordPermission(layers, "tools", normalizedToolName)?.state
+    return toolMatch?.state
       ?? resolveLayeredDefaultPermission(layers, "tools")?.state
       ?? DEFAULT_POLICY.tools;
   }
 
   checkPermission(toolName: string, input: unknown, agentName?: string): PermissionCheckResult {
-    const { merged, layers, compiledSpecial, compiledSkills, compiledMcp, compiledBash } = this.resolvePermissions(agentName);
+    const { merged, layers, compiledTools, compiledSpecial, compiledSkills, compiledMcp, compiledBash } = this.resolvePermissions(agentName);
     const normalizedToolName = toolName.trim();
+    const toolMatch = findCompiledPermissionMatch(compiledTools, normalizedToolName);
 
     if (SPECIAL_PERMISSION_KEYS.has(normalizedToolName)) {
       const result = findCompiledPermissionMatch(compiledSpecial, normalizedToolName);
@@ -867,7 +879,7 @@ export class PermissionManager {
       return {
         toolName,
         state: result?.state
-          ?? resolveLayeredRecordPermission(layers, "tools", "bash")?.state
+          ?? toolMatch?.state
           ?? resolveLayeredDefaultPermission(layers, "bash")?.state
           ?? DEFAULT_POLICY.bash,
         command,
@@ -879,7 +891,6 @@ export class PermissionManager {
     if (normalizedToolName === "mcp") {
       const mcpTargets = [...createMcpPermissionTargets(input, this.getConfiguredMcpServerNames()), "mcp"];
       const fallbackTarget = mcpTargets[0] || "mcp";
-      const toolLevelMcpState = resolveLayeredRecordPermission(layers, "tools", "mcp")?.state;
       const defaultMcpState = resolveLayeredDefaultPermission(layers, "mcp")?.state ?? DEFAULT_POLICY.mcp;
 
       const mcpMatch = findCompiledPermissionMatchForNames(compiledMcp, mcpTargets);
@@ -893,10 +904,11 @@ export class PermissionManager {
         };
       }
 
-      if (toolLevelMcpState) {
+      if (toolMatch) {
         return {
           toolName,
-          state: toolLevelMcpState,
+          state: toolMatch.state,
+          matchedPattern: toolMatch.matchedPattern,
           target: fallbackTarget,
           source: "tool",
         };
@@ -923,21 +935,22 @@ export class PermissionManager {
       };
     }
 
-    const explicitToolPermission = resolveLayeredRecordPermission(layers, "tools", normalizedToolName);
     if (BUILT_IN_TOOL_PERMISSION_NAMES.has(normalizedToolName)) {
       return {
         toolName,
-        state: explicitToolPermission?.state
+        state: toolMatch?.state
           ?? resolveLayeredDefaultPermission(layers, "tools")?.state
           ?? DEFAULT_POLICY.tools,
+        matchedPattern: toolMatch?.matchedPattern,
         source: "tool",
       };
     }
 
-    if (explicitToolPermission) {
+    if (toolMatch) {
       return {
         toolName,
-        state: explicitToolPermission.state,
+        state: toolMatch.state,
+        matchedPattern: toolMatch.matchedPattern,
         source: "tool",
       };
     }

package/src/yolo-mode-api.ts

@@ -0,0 +1,43 @@
+export interface YoloModeControlOptions {
+  persist?: boolean;
+  source?: string;
+}
+
+export interface YoloModeControlResult {
+  yoloMode: boolean;
+  changed: boolean;
+  persisted: boolean;
+  error?: string;
+}
+
+export interface PiPermissionSystemRuntimeApi {
+  getYoloMode(): boolean;
+  setYoloMode(enabled: boolean, options?: YoloModeControlOptions): YoloModeControlResult;
+  toggleYoloMode(options?: YoloModeControlOptions): YoloModeControlResult;
+}
+
+type GlobalWithPermissionSystemRuntimeApi = typeof globalThis & {
+  __piPermissionSystem?: PiPermissionSystemRuntimeApi;
+};
+
+export function registerPiPermissionSystemRuntimeApi(
+  api: PiPermissionSystemRuntimeApi,
+): PiPermissionSystemRuntimeApi {
+  const globalScope = globalThis as GlobalWithPermissionSystemRuntimeApi;
+  globalScope.__piPermissionSystem = api;
+  return api;
+}
+
+export function unregisterPiPermissionSystemRuntimeApi(api?: PiPermissionSystemRuntimeApi): void {
+  const globalScope = globalThis as GlobalWithPermissionSystemRuntimeApi;
+  if (api !== undefined && globalScope.__piPermissionSystem !== undefined && globalScope.__piPermissionSystem !== api) {
+    return;
+  }
+
+  delete globalScope.__piPermissionSystem;
+}
+
+export function getPiPermissionSystemRuntimeApi(): PiPermissionSystemRuntimeApi | null {
+  const globalScope = globalThis as GlobalWithPermissionSystemRuntimeApi;
+  return globalScope.__piPermissionSystem ?? null;
+}

package/tests/config-modal.test.ts

@@ -1,15 +1,7 @@
 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 "../src/extension-config.js";
+import type { PermissionSystemExtensionConfig } from "../src/extension-config.js";
 import { runAsyncTest, runTest } from "./test-harness.js";
 
 mock.module("@mariozechner/pi-coding-agent", () => ({
@@ -90,122 +82,68 @@ function getRegisteredDefinition(definition: RegisteredCommandDefinition | null)
   return definition;
 }
 
-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 };
+function registerForTest(config: PermissionSystemExtensionConfig): RegisteredCommandDefinition {
+  let definition: RegisteredCommandDefinition | null = null;
 
-  try {
-    const controller = {
+  registerPermissionSystemCommand(
+    {
+      registerCommand(_name: string, nextDefinition: RegisteredCommandDefinition) {
+        definition = nextDefinition;
+      },
+    } as never,
+    {
       getConfig: () => config,
       setConfig: (next: PermissionSystemExtensionConfig) => {
         config = next;
       },
-      getConfigPath: () => configPath,
-    };
+      getConfigPath: () => "C:/tmp/pi-permission-system/config.json",
+    } as never,
+  );
+
+  return getRegisteredDefinition(definition);
+}
 
-    let definition: RegisteredCommandDefinition | null = null;
+runTest("permission-system command exposes no subcommand completions", () => {
+  const registeredDefinition = registerForTest({
+    debugLog: false,
+    permissionReviewLog: true,
+    yoloMode: false,
+  });
 
-    registerPermissionSystemCommand(
-      {
-        registerCommand(_name: string, nextDefinition: RegisteredCommandDefinition) {
-          definition = nextDefinition;
-        },
-      } as never,
-      controller as never,
-    );
-
-    const registeredDefinition = getRegisteredDefinition(definition);
-    assert.ok(typeof registeredDefinition.getArgumentCompletions === "function");
-
-    const topLevel = registeredDefinition.getArgumentCompletions("");
-    assert.ok(Array.isArray(topLevel));
-    assert.ok(topLevel.some((item) => item.value === "show"));
-    assert.ok(topLevel.some((item) => item.value === "reset"));
-
-    const filtered = registeredDefinition.getArgumentCompletions("pa");
-    assert.deepEqual(filtered?.map((item) => item.value), ["path"]);
-    assert.equal(registeredDefinition.getArgumentCompletions("path extra"), null);
-    assert.equal(registeredDefinition.getArgumentCompletions("zzz"), null);
-  } finally {
-    rmSync(baseDir, { recursive: true, force: true });
-  }
+  assert.equal(registeredDefinition.getArgumentCompletions, undefined);
 });
 
-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 = {
+await runAsyncTest("permission-system command only opens the settings modal", async () => {
+  const 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: RegisteredCommandDefinition | null = null;
-
-    registerPermissionSystemCommand(
-      {
-        registerCommand(name: string, nextDefinition: RegisteredCommandDefinition) {
-          registeredName = name;
-          definition = nextDefinition;
-        },
-      } as never,
-      controller as never,
-    );
-
-    assert.equal(registeredName, "permission-system");
-    const registeredDefinition = getRegisteredDefinition(definition);
-    assert.ok(registeredDefinition.description.includes("Configure pi-permission-system"));
-
-    const infoCtx = createCommandContext(true);
-    await registeredDefinition.handler("show", infoCtx.ctx);
-    assert.ok(lastNotification(infoCtx.notifications).message.includes("yoloMode=on"));
-    assert.ok(lastNotification(infoCtx.notifications).message.includes("debugLog=on"));
-
-    await registeredDefinition.handler("path", infoCtx.ctx);
-    assert.equal(lastNotification(infoCtx.notifications).message, `permission-system config: ${configPath}`);
-
-    await registeredDefinition.handler("help", infoCtx.ctx);
-    assert.ok(lastNotification(infoCtx.notifications).message.includes("Usage: /permission-system"));
-
-    await registeredDefinition.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 registeredDefinition.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 registeredDefinition.handler("", headlessCtx.ctx);
-    assert.equal(lastNotification(headlessCtx.notifications).message, "/permission-system requires interactive TUI mode.");
-
-    const modalCtx = createCommandContext(true);
-    await registeredDefinition.handler("", modalCtx.ctx);
-    assert.equal(modalCtx.getCustomCalls(), 1);
-  } finally {
-    rmSync(baseDir, { recursive: true, force: true });
-  }
+  const registeredDefinition = registerForTest(config);
+
+  assert.ok(registeredDefinition.description.includes("Configure pi-permission-system"));
+
+  const headlessCtx = createCommandContext(false);
+  await registeredDefinition.handler("", headlessCtx.ctx);
+  assert.equal(lastNotification(headlessCtx.notifications).message, "/permission-system requires interactive TUI mode.");
+  assert.equal(headlessCtx.getCustomCalls(), 0);
+
+  const modalCtx = createCommandContext(true);
+  await registeredDefinition.handler("", modalCtx.ctx);
+  assert.equal(modalCtx.getCustomCalls(), 1);
+  assert.equal(modalCtx.notifications.length, 0);
+
+  const subcommandCtx = createCommandContext(true);
+  await registeredDefinition.handler("yolo off", subcommandCtx.ctx);
+  await registeredDefinition.handler("show", subcommandCtx.ctx);
+  await registeredDefinition.handler("reset", subcommandCtx.ctx);
+  assert.equal(subcommandCtx.getCustomCalls(), 3);
+  assert.equal(subcommandCtx.notifications.length, 0);
+  assert.deepEqual(config, {
+    debugLog: true,
+    permissionReviewLog: false,
+    yoloMode: true,
+  });
 });
 
 console.log("All permission-system config-modal tests passed.");

package/tests/permission-system.test.ts

@@ -85,10 +85,21 @@ type MockHandler = (
   ctx: Record<string, unknown>,
 ) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
 
+type PermissionSystemRuntimeApi = {
+  getYoloMode(): boolean;
+  setYoloMode(enabled: boolean, options?: { persist?: boolean; source?: string }): { yoloMode: boolean; changed: boolean; persisted: boolean; error?: string };
+  toggleYoloMode(options?: { persist?: boolean; source?: string }): { yoloMode: boolean; changed: boolean; persisted: boolean; error?: string };
+};
+
+type GlobalWithPermissionSystem = typeof globalThis & {
+  __piPermissionSystem?: PermissionSystemRuntimeApi;
+};
+
 type ExtensionHarness = {
   baseDir: string;
   cwd: string;
   handlers: Record<string, MockHandler>;
+  registeredEvents: string[];
   prompts: string[];
   reviewLogPath: string;
   cleanup: () => Promise<void>;
@@ -99,6 +110,7 @@ type ExtensionHarnessOptions = {
   hasUI?: boolean;
   selectResponse?: string;
   inputResponse?: string;
+  statusUpdates?: Array<{ key: string; value: string | undefined }>;
 };
 
 const INHERITED_SUBAGENT_ENV_KEYS = [
@@ -135,6 +147,7 @@ function createToolCallHarness(
   const cwd = options.cwd || baseDir;
   const prompts: string[] = [];
   const handlers: Record<string, MockHandler> = {};
+  const registeredEvents: string[] = [];
   const extensionConfigPath = join(baseDir, "extension-config.json");
   const logsDir = join(baseDir, "extension-logs");
   const reviewLogPath = join(logsDir, "pi-permission-system-permission-review.jsonl");
@@ -153,6 +166,7 @@ function createToolCallHarness(
   try {
     piPermissionSystemExtension({
       on: (name: string, handler: MockHandler): void => {
+        registeredEvents.push(name);
         handlers[name] = handler;
       },
       registerCommand: (): void => {},
@@ -175,6 +189,7 @@ function createToolCallHarness(
     baseDir,
     cwd,
     handlers,
+    registeredEvents,
     prompts,
     reviewLogPath,
     cleanup: async (): Promise<void> => {
@@ -209,7 +224,9 @@ function createMockContext(
     },
     ui: {
       notify: (): void => {},
-      setStatus: (): void => {},
+      setStatus: (key: string, value: string | undefined): void => {
+        options.statusUpdates?.push({ key, value });
+      },
       select: async (title: string): Promise<string | undefined> => {
         prompts.push(title);
         return options.selectResponse ?? "Yes";
@@ -233,6 +250,53 @@ async function runToolCall(
   return (result ?? {}) as Record<string, unknown>;
 }
 
+await runAsyncTest("Extension registers only one supported session_start lifecycle handler", async () => {
+  const harness = createToolCallHarness({ defaultPolicy: { tools: "allow", bash: "allow", mcp: "allow", skills: "allow", special: "allow" } }, []);
+
+  try {
+    assert.equal(harness.registeredEvents.includes("session_switch"), false);
+    assert.equal(harness.registeredEvents.filter((eventName) => eventName === "session_start").length, 1);
+  } finally {
+    await harness.cleanup();
+  }
+});
+
+await runAsyncTest("Extension exposes a runtime YOLO API for other extensions", async () => {
+  const statusUpdates: Array<{ key: string; value: string | undefined }> = [];
+  const harness = createToolCallHarness(
+    { defaultPolicy: { tools: "allow", bash: "allow", mcp: "allow", skills: "allow", special: "allow" } },
+    [],
+    { hasUI: true, statusUpdates },
+  );
+
+  try {
+    const globalScope = globalThis as GlobalWithPermissionSystem;
+    const api = globalScope.__piPermissionSystem;
+    assert.ok(api);
+    assert.equal(api.getYoloMode(), false);
+
+    await Promise.resolve(harness.handlers.session_start?.({ reason: "startup" }, createMockContext(harness.cwd, harness.prompts, { hasUI: true, statusUpdates })));
+
+    const transient = api.toggleYoloMode({ persist: false, source: "test-extension" });
+    assert.deepEqual(transient, { yoloMode: true, changed: true, persisted: false });
+    assert.equal(loadPermissionSystemConfig().config.yoloMode, false);
+    const enabledStatus = statusUpdates.at(-1);
+    assert.equal(enabledStatus?.key, "pi-permission-system");
+    assert.equal(enabledStatus?.value, "yolo");
+
+    const persisted = api.setYoloMode(false, { source: "test-extension" });
+    assert.deepEqual(persisted, { yoloMode: false, changed: true, persisted: true });
+    assert.equal(loadPermissionSystemConfig().config.yoloMode, false);
+    const disabledStatus = statusUpdates.at(-1);
+    assert.equal(disabledStatus?.key, "pi-permission-system");
+    assert.equal(disabledStatus?.value, undefined);
+  } finally {
+    await harness.cleanup();
+  }
+
+  assert.equal((globalThis as GlobalWithPermissionSystem).__piPermissionSystem, undefined);
+});
+
 runTest("Permission-system extension config defaults debug off, review log on, and yolo mode off", () => {
   const baseDir = mkdtempSync(join(tmpdir(), "pi-permission-system-config-"));
   const configPath = join(baseDir, "config.json");
@@ -729,6 +793,63 @@ runTest("Arbitrary extension tools use exact-name tool permissions instead of MC
   }
 });
 
+runTest("Tool permissions support wildcard patterns for extension tools", () => {
+  const { manager, cleanup } = createManager({
+    defaultPolicy: {
+      tools: "deny",
+      bash: "ask",
+      mcp: "ask",
+      skills: "ask",
+      special: "ask",
+    },
+    tools: {
+      "*": "ask",
+      "context7_*": "allow",
+    },
+  });
+
+  try {
+    const context7 = manager.checkPermission("context7_query-docs", {});
+    assert.equal(context7.state, "allow");
+    assert.equal(context7.source, "tool");
+    assert.equal(context7.matchedPattern, "context7_*");
+    assert.equal(manager.getToolPermission("context7_query-docs"), "allow");
+
+    const unknown = manager.checkPermission("unknown_extension_tool", {});
+    assert.equal(unknown.state, "ask");
+    assert.equal(unknown.source, "tool");
+    assert.equal(unknown.matchedPattern, "*");
+    assert.equal(manager.getToolPermission("unknown_extension_tool"), "ask");
+  } finally {
+    cleanup();
+  }
+});
+
+runTest("Tool permission wildcards use last matching rule wins", () => {
+  const { manager, cleanup } = createManager({
+    defaultPolicy: {
+      tools: "deny",
+      bash: "ask",
+      mcp: "ask",
+      skills: "ask",
+      special: "ask",
+    },
+    tools: {
+      "context7_*": "allow",
+      "*": "ask",
+    },
+  });
+
+  try {
+    const context7 = manager.checkPermission("context7_query-docs", {});
+    assert.equal(context7.state, "ask");
+    assert.equal(context7.source, "tool");
+    assert.equal(context7.matchedPattern, "*");
+  } finally {
+    cleanup();
+  }
+});
+
 runTest("Skill permission matching", () => {
   const { manager, cleanup } = createManager({
     defaultPolicy: {
@@ -2096,6 +2217,29 @@ await runAsyncTest("generic ask prompts include serialized tool input for inform
   }
 });
 
+await runAsyncTest("permission review logs include requested bash commands", async () => {
+  const harness = createToolCallHarness(
+    {
+      defaultPolicy: { tools: "ask", bash: "ask", mcp: "ask", skills: "ask", special: "ask" },
+    },
+    ["bash"],
+  );
+
+  try {
+    const result = await runToolCall(harness, {
+      toolName: "bash",
+      toolCallId: "review-bash-command",
+      input: { command: "git status --short" },
+    });
+
+    assert.equal(result.block, true);
+    const reviewLog = readFileSync(harness.reviewLogPath, "utf8");
+    assert.match(reviewLog, /\"command\":\"git status --short\"/);
+  } finally {
+    await harness.cleanup();
+  }
+});
+
 await runAsyncTest("permission review logs redact raw prompts and tool input previews", async () => {
   const harness = createToolCallHarness(
     {