pi-permission-system 0.4.3 → 0.4.4

package/CHANGELOG.md

@@ -7,21 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.4.3] - 2026-04-22
+## [0.4.4] - 2026-04-25
 
 ### Added
-- Added `src/skill-prompt-sanitizer.ts` to centralize skill prompt parsing and sanitization helpers
+- Added runtime enforcement for the `external_directory` special permission on path-bearing tools (`read`, `write`, `edit`, `find`, `grep`, `ls`) before normal tool permission checks (thanks to @gotgenes for PR #9)
+- Added readable `ask` prompt summaries for built-in file tools and bounded input previews for generic extension tools so users can make informed approval decisions (thanks to @beantownbytes for PR #8)
+- Added `skill-prompt-sanitizer.ts` to parse and sanitize every `<available_skills>` block, including prompts with multiple skill sections
 
 ### Changed
-- Updated `@mariozechner/pi-coding-agent` and `@mariozechner/pi-tui` peer dependencies to `^0.68.1`
-- Refactored `src/index.ts` to reuse shared skill prompt sanitizer helpers
+- Updated `@mariozechner/pi-coding-agent` and `@mariozechner/pi-tui` peer dependencies to `^0.70.2`
+- Refactored skill prompt filtering out of `src/index.ts` into a dedicated module for clearer ownership and reuse
+- Permission prompts for `edit`, `write`, `read`, `find`, `grep`, and `ls` now show concise path/action summaries instead of raw multiline JSON
 
 ### Fixed
-- Skill prompt sanitization now removes denied skills from every `<available_skills>` block and drops fully denied blocks from the prompt
-- Hidden skills are no longer retained for skill path matching after sanitization
+- Denied skills are now removed from all available-skill prompt blocks instead of only the first block
+- Denied skill entries are no longer retained for later skill-read path matching after prompt sanitization
+- External path access now honors `special.external_directory: deny` and blocks `ask` decisions when no UI or forwarding channel is available
 
 ### Tests
-- Added regression coverage for multi-block `<available_skills>` parsing, sanitization, and visible-skill path matching
+- Added runtime `tool_call` coverage for external directory deny, ask-without-UI, ask approval, internal path allow, and optional path omission
+- Added prompt regression coverage for generic tool input previews and readable built-in file-tool approval summaries
+- Added multi-block skill prompt sanitizer regression coverage
 
 ## [0.4.2] - 2026-04-20
 

package/README.md

@@ -1,6 +1,6 @@
 # 🔐 pi-permission-system
 
-[![Version](https://img.shields.io/badge/version-0.4.2-blue.svg)](package.json)
+[![Version](https://img.shields.io/badge/version-0.4.4-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.
@@ -12,15 +12,16 @@ Permission enforcement extension for the Pi coding agent that provides centraliz
 
 - **Tool Filtering** — Hides disallowed tools from the agent before it starts (reduces "try another tool" behavior)
 - **System Prompt Sanitization** — Removes denied tool entries from the `Available tools:` system prompt section so the agent only sees tools it can actually call
-- **Runtime Enforcement** — Blocks/asks/allows at tool call time with UI confirmation dialogs
+- **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
+- **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
 - **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
+- **External Directory Guard** — Enforces `special.external_directory` for path-bearing file tools that target paths outside the active working directory
 
 ## Installation
 
@@ -84,6 +85,8 @@ The extension integrates via Pi's lifecycle hooks:
 - 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
 - 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
+- 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
 
@@ -122,7 +125,7 @@ The policy file is a JSON object with these sections:
 | `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                          |
+| `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.
 
@@ -310,7 +313,7 @@ Reserved permission checks:
 | Key                  | Description                              |
 |----------------------|------------------------------------------|
 | `doom_loop`          | Controls doom loop detection behavior    |
-| `external_directory` | Controls access outside working directory |
+| `external_directory` | Enforces ask/allow/deny decisions for path-bearing built-in tools (`read`, `write`, `edit`, `find`, `grep`, `ls`) when they target paths outside the active working directory |
 | `tool_call_limit`    | *(schema only, not enforced yet)*        |
 
 ```jsonc
@@ -322,6 +325,8 @@ Reserved permission checks:
 }
 ```
 
+`external_directory` is evaluated before the normal tool permission check. For example, `tools.read: "allow"` can permit ordinary reads while `special.external_directory: "ask"` still requires confirmation before reading `../outside.txt` or an absolute path outside `ctx.cwd`. Optional-path search tools (`find`, `grep`, `ls`) skip this check when no `path` is provided because they default to the active working directory.
+
 ---
 
 ## Common Recipes
@@ -390,6 +395,21 @@ permission:
 
 ## Technical Details
 
+### Permission Prompt Summaries
+
+When a tool permission resolves to `ask`, the prompt is designed to be readable enough for an informed approval decision:
+
+- `bash` prompts show the command and matched bash pattern when available.
+- `mcp` prompts show the derived MCP target and matched rule when available.
+- Built-in file tools show concise summaries, such as the target path and edit/write line counts, instead of raw multiline JSON.
+- Unknown or third-party extension tools show a bounded single-line JSON preview of the input so users are not asked to approve a blind tool name.
+
+Example edit approval prompt:
+
+```text
+Current agent requested tool 'edit' for '.gitignore' (1 replacement: edit #1 replaces 5 lines with 2 lines). Allow this call?
+```
+
 ### Subagent Permission Forwarding
 
 When a delegated or routed subagent runs without direct UI access, `ask` permissions can still be enforced by forwarding the confirmation request through Pi session directories. The main interactive session polls for forwarded requests, shows the confirmation prompt, writes the response, and the subagent resumes once that decision is available.
@@ -413,10 +433,11 @@ Actual global logs directory: $PI_CODING_AGENT_DIR/extensions/pi-permission-syst
 ```
 index.ts                    → Root Pi entrypoint shim
 src/
-├── index.ts                → Extension bootstrap, permission checks, review logging, reload handling, and subagent forwarding
+├── 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.)
@@ -442,6 +463,7 @@ The extension uses a modular architecture with shared utilities:
 | `wildcard-matcher.ts` | Compile-once wildcard patterns with specificity sorting: `compileWildcardPatterns()`, `findCompiledWildcardMatch()` |
 | `permission-manager.ts` | Policy resolution with file stamp caching for performance |
 | `bash-filter.ts` | Uses shared wildcard matcher for bash command patterns |
+| `skill-prompt-sanitizer.ts` | Parses all available skill prompt blocks, removes denied skills, and tracks visible skill paths for read protection |
 
 #### Performance Optimizations
 
@@ -457,6 +479,7 @@ The extension uses a modular architecture with shared utilities:
 - Agent calling tools it shouldn't use (e.g., `write`, dangerous `bash`)
 - Tool switching attempts (calling non-existent tool names)
 - Accidental escalation via skill loading
+- Unapproved path-bearing tool access outside the active working directory when `external_directory` is `ask` or `deny`
 
 **Limitations:**
 - If a dangerous action is possible via an allowed tool, policy must explicitly restrict it
@@ -484,6 +507,8 @@ npx --yes ajv-cli@5 validate \
 | 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. |
+| External file path blocked | `special.external_directory` is `ask` without UI or `deny` | Allow/ask the special permission or keep file tools inside the active working directory. |
+| Permission prompt is too verbose | Generic extension tool input is large | Built-in file tools are summarized automatically; third-party tools are capped to a bounded one-line JSON preview. |
 
 ---
 

package/config.json

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

package/package.json

@@ -1,65 +1,65 @@
-{
-  "name": "pi-permission-system",
-  "version": "0.4.3",
-  "description": "Permission enforcement extension for the Pi coding agent.",
-  "type": "module",
-  "main": "./index.ts",
-  "exports": {
-    ".": "./index.ts"
-  },
-  "files": [
-    "index.ts",
-    "src",
-    "tests",
-    "config.json",
-    "config/config.example.json",
-    "schemas/permissions.schema.json",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
-    "lint": "npm run build",
-    "test": "bun ./tests/permission-system.test.ts && bun ./tests/config-modal.test.ts",
-    "check": "npm run lint && 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"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ]
-  },
-  "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "^0.68.1",
-    "@mariozechner/pi-tui": "^0.68.1",
-    "@sinclair/typebox": "^0.34.49"
-  }
-}
+{
+  "name": "pi-permission-system",
+  "version": "0.4.4",
+  "description": "Permission enforcement extension for the Pi coding agent.",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "tests",
+    "config.json",
+    "config/config.example.json",
+    "schemas/permissions.schema.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
+    "lint": "npm run build",
+    "test": "bun ./tests/permission-system.test.ts && bun ./tests/config-modal.test.ts",
+    "check": "npm run lint && 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"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "^0.70.2",
+    "@mariozechner/pi-tui": "^0.70.2",
+    "@sinclair/typebox": "^0.34.49"
+  }
+}

package/src/index.ts

@@ -1,9 +1,9 @@
 import { getAgentDir, isToolCallEventType, type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext } from "@mariozechner/pi-coding-agent";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join, normalize, resolve, sep } from "node:path";
+import { join, normalize, resolve, sep } from "node:path";
 
-import { toRecord } from "./common.js";
+import { getNonEmptyString, toRecord } from "./common.js";
 import {
   createActiveToolsCacheKey,
   createBeforeAgentStartPromptStateKey,
@@ -72,6 +72,7 @@ type PermissionRequestEvent = {
 };
 
 const PERMISSION_REQUEST_EVENT_CHANNEL = "pi-permission-system:permission-request";
+const PATH_BEARING_TOOLS = new Set(["read", "write", "edit", "find", "grep", "ls"]);
 
 let extensionConfig: PermissionSystemExtensionConfig = { ...DEFAULT_EXTENSION_CONFIG };
 const extensionLogger = createPermissionSystemLogger({
@@ -143,6 +144,21 @@ function isPathWithinDirectory(pathValue: string, directory: string): boolean {
   return pathValue.startsWith(prefix);
 }
 
+function getPathBearingToolPath(toolName: string, input: unknown): string | null {
+  if (!PATH_BEARING_TOOLS.has(toolName)) {
+    return null;
+  }
+
+  return getNonEmptyString(toRecord(input).path);
+}
+
+function isPathOutsideWorkingDirectory(pathValue: string, cwd: string): boolean {
+  const normalizedCwd = normalizePathForComparison(cwd, cwd);
+  const normalizedPath = normalizePathForComparison(pathValue, cwd);
+  return Boolean(normalizedCwd && normalizedPath && !isPathWithinDirectory(normalizedPath, normalizedCwd));
+}
+
+
 function extractSkillNameFromInput(text: string): string | null {
   const trimmed = text.trim();
   if (!trimmed.startsWith("/skill:")) {
@@ -280,7 +296,147 @@ function formatUserDeniedReason(result: PermissionCheckResult, denialReason?: st
   return `${base}${reasonSuffix} ${formatPermissionHardStopHint(result)}`;
 }
 
-function formatAskPrompt(result: PermissionCheckResult, agentName?: string): string {
+const TOOL_INPUT_PREVIEW_MAX_LENGTH = 200;
+const TOOL_TEXT_SUMMARY_MAX_LENGTH = 80;
+
+function truncateInlineText(value: string, maxLength: number): string {
+  return value.length > maxLength ? `${value.slice(0, maxLength)}…` : value;
+}
+
+function sanitizeInlineText(value: string, maxLength = TOOL_TEXT_SUMMARY_MAX_LENGTH): string {
+  const normalized = value.replace(/\s+/g, " ").trim();
+  return normalized ? truncateInlineText(normalized, maxLength) : "empty text";
+}
+
+function countTextLines(value: string): number {
+  if (!value) {
+    return 0;
+  }
+
+  return value.split(/\r\n|\r|\n/).length;
+}
+
+function formatCount(value: number, singular: string, plural: string): string {
+  return `${value} ${value === 1 ? singular : plural}`;
+}
+
+function getPromptPath(input: Record<string, unknown>): string | null {
+  return getNonEmptyString(input.path) ?? getNonEmptyString(input.file_path);
+}
+
+function formatEditInputForPrompt(input: Record<string, unknown>): string {
+  const path = getPromptPath(input);
+  const rawEdits = Array.isArray(input.edits)
+    ? input.edits
+    : typeof input.oldText === "string" && typeof input.newText === "string"
+      ? [{ oldText: input.oldText, newText: input.newText }]
+      : [];
+
+  const edits = rawEdits
+    .map((edit) => toRecord(edit))
+    .filter((edit) => typeof edit.oldText === "string" && typeof edit.newText === "string");
+
+  const pathPart = path ? `for '${path}'` : "";
+  if (edits.length === 0) {
+    return pathPart ? `${pathPart} with edit input` : "with edit input";
+  }
+
+  const firstEdit = edits[0];
+  const oldText = String(firstEdit.oldText);
+  const newText = String(firstEdit.newText);
+  const firstEditSummary = `edit #1 replaces ${formatCount(countTextLines(oldText), "line", "lines")} with ${formatCount(countTextLines(newText), "line", "lines")}`;
+  const extraEdits = edits.length > 1 ? `, plus ${formatCount(edits.length - 1, "additional edit", "additional edits")}` : "";
+  const summary = `(${formatCount(edits.length, "replacement", "replacements")}: ${firstEditSummary}${extraEdits})`;
+  return pathPart ? `${pathPart} ${summary}` : summary;
+}
+
+function formatWriteInputForPrompt(input: Record<string, unknown>): string {
+  const path = getPromptPath(input);
+  const content = typeof input.content === "string" ? input.content : "";
+  const summary = `(${formatCount(countTextLines(content), "line", "lines")}, ${formatCount(content.length, "character", "characters")})`;
+  return path ? `for '${path}' ${summary}` : summary;
+}
+
+function formatReadInputForPrompt(input: Record<string, unknown>): string {
+  const path = getPromptPath(input);
+  const parts = path ? [`path '${path}'`] : [];
+  if (typeof input.offset === "number") {
+    parts.push(`offset ${input.offset}`);
+  }
+  if (typeof input.limit === "number") {
+    parts.push(`limit ${input.limit}`);
+  }
+  return parts.length > 0 ? `for ${parts.join(", ")}` : "";
+}
+
+function formatSearchInputForPrompt(toolName: string, input: Record<string, unknown>): string {
+  const parts: string[] = [];
+  const path = getPromptPath(input);
+  const pattern = getNonEmptyString(input.pattern);
+  const glob = getNonEmptyString(input.glob);
+
+  if (pattern) {
+    parts.push(`pattern '${sanitizeInlineText(pattern)}'`);
+  }
+  if (glob) {
+    parts.push(`glob '${sanitizeInlineText(glob)}'`);
+  }
+  if (path) {
+    parts.push(`path '${path}'`);
+  } else if (toolName === "find" || toolName === "grep" || toolName === "ls") {
+    parts.push("current working directory");
+  }
+
+  return parts.length > 0 ? `for ${parts.join(", ")}` : "";
+}
+
+function formatJsonInputForPrompt(input: unknown): string {
+  if (input === undefined || input === null) {
+    return "";
+  }
+
+  if (typeof input === "object" && !Array.isArray(input) && Object.keys(input as Record<string, unknown>).length === 0) {
+    return "";
+  }
+
+  let serialized: string;
+  try {
+    serialized = JSON.stringify(input);
+  } catch {
+    return "";
+  }
+
+  if (!serialized || serialized === "{}" || serialized === "null") {
+    return "";
+  }
+
+  const inline = serialized
+    .replace(/\\r\\n|\\n|\\r|\\t/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  return inline ? `with input ${truncateInlineText(inline, TOOL_INPUT_PREVIEW_MAX_LENGTH)}` : "";
+}
+
+function formatToolInputForPrompt(toolName: string, input: unknown): string {
+  const inputRecord = toRecord(input);
+
+  switch (toolName) {
+    case "edit":
+      return formatEditInputForPrompt(inputRecord);
+    case "write":
+      return formatWriteInputForPrompt(inputRecord);
+    case "read":
+      return formatReadInputForPrompt(inputRecord);
+    case "find":
+    case "grep":
+    case "ls":
+      return formatSearchInputForPrompt(toolName, inputRecord);
+    default:
+      return formatJsonInputForPrompt(input);
+  }
+}
+
+function formatAskPrompt(result: PermissionCheckResult, agentName?: string, input?: unknown): string {
   const subject = agentName ? `Agent '${agentName}'` : "Current agent";
 
   if (result.toolName === "bash") {
@@ -294,7 +450,9 @@ function formatAskPrompt(result: PermissionCheckResult, agentName?: string): str
   }
 
   const patternInfo = result.matchedPattern ? ` (matched '${result.matchedPattern}')` : "";
-  return `${subject} requested tool '${result.toolName}'${patternInfo}. Allow this call?`;
+  const inputPreview = formatToolInputForPrompt(result.toolName, input);
+  const inputSuffix = inputPreview ? ` ${inputPreview}` : "";
+  return `${subject} requested tool '${result.toolName}'${patternInfo}${inputSuffix}. Allow this call?`;
 }
 
 function formatSkillAskPrompt(skillName: string, agentName?: string): string {
@@ -312,6 +470,39 @@ function formatSkillPathDenyReason(skill: SkillPromptEntry, readPath: string, ag
   return `${subject} is not permitted to access skill '${skill.name}' via '${readPath}'.`;
 }
 
+function formatExternalDirectoryHardStopHint(): string {
+  return "Hard stop: this external directory permission denial is policy-enforced. Do not retry this path, do not attempt a filesystem bypass, and report the block to the user.";
+}
+
+function formatExternalDirectoryAskPrompt(
+  toolName: string,
+  pathValue: string,
+  cwd: string,
+  agentName?: string,
+): string {
+  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
+  return `${subject} requested tool '${toolName}' for path '${pathValue}' outside working directory '${cwd}'. Allow this external directory access?`;
+}
+
+function formatExternalDirectoryDenyReason(
+  toolName: string,
+  pathValue: string,
+  cwd: string,
+  agentName?: string,
+): string {
+  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
+  return `${subject} is not permitted to run tool '${toolName}' for path '${pathValue}' outside working directory '${cwd}'. ${formatExternalDirectoryHardStopHint()}`;
+}
+
+function formatExternalDirectoryUserDeniedReason(
+  toolName: string,
+  pathValue: string,
+  denialReason?: string,
+): string {
+  const reasonSuffix = denialReason ? ` Reason: ${denialReason}.` : "";
+  return `User denied external directory access for tool '${toolName}' path '${pathValue}'.${reasonSuffix} ${formatExternalDirectoryHardStopHint()}`;
+}
+
 function getPermissionLogContext(result: PermissionCheckResult): { command?: string; target?: string } {
   return {
     command: result.command,
@@ -1282,6 +1473,78 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     }
 
     const input = getEventInput(event);
+    const externalDirectoryPath = ctx.cwd ? getPathBearingToolPath(toolName, input) : null;
+
+    if (ctx.cwd && externalDirectoryPath && isPathOutsideWorkingDirectory(externalDirectoryPath, ctx.cwd)) {
+      const extCheck = permissionManager.checkPermission("external_directory", {}, agentName ?? undefined);
+
+      if (extCheck.state === "deny") {
+        writeReviewLog("permission_request.blocked", {
+          source: "tool_call",
+          toolCallId: event.toolCallId,
+          toolName,
+          agentName,
+          path: externalDirectoryPath,
+          resolution: "policy_denied",
+        });
+        return {
+          block: true,
+          reason: formatExternalDirectoryDenyReason(
+            toolName,
+            externalDirectoryPath,
+            ctx.cwd,
+            agentName ?? undefined,
+          ),
+        };
+      }
+
+      if (extCheck.state === "ask") {
+        const message = formatExternalDirectoryAskPrompt(
+          toolName,
+          externalDirectoryPath,
+          ctx.cwd,
+          agentName ?? undefined,
+        );
+        if (!canRequestPermissionConfirmation(ctx)) {
+          writeReviewLog("permission_request.blocked", {
+            source: "tool_call",
+            toolCallId: event.toolCallId,
+            toolName,
+            agentName,
+            path: externalDirectoryPath,
+            message,
+            resolution: "confirmation_unavailable",
+          });
+          return {
+            block: true,
+            reason: `Accessing '${externalDirectoryPath}' outside the working directory requires approval, but no interactive UI is available.`,
+          };
+        }
+
+        const extDecision = await promptPermission(ctx, {
+          requestId: event.toolCallId,
+          source: "tool_call",
+          agentName,
+          message,
+          toolCallId: event.toolCallId,
+          toolName,
+          path: externalDirectoryPath,
+        });
+
+        if (!extDecision.approved) {
+          return {
+            block: true,
+            reason: formatExternalDirectoryUserDeniedReason(
+              toolName,
+              externalDirectoryPath,
+              extDecision.denialReason,
+            ),
+          };
+        }
+      }
+      // state === "allow" → fall through to normal permission check
+    }
+
     const check = permissionManager.checkPermission(toolName, input, agentName ?? undefined);
     const permissionLogContext = getPermissionLogContext(check);
 
@@ -1304,7 +1567,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
           ? "Using tool 'mcp' requires approval, but no interactive UI is available."
           : `Using tool '${toolName}' requires approval, but no interactive UI is available.`;
 
-      const message = formatAskPrompt(check, agentName ?? undefined);
+      const message = formatAskPrompt(check, agentName ?? undefined, input);
       if (!canRequestPermissionConfirmation(ctx)) {
         writeReviewLog("permission_request.blocked", {
           source: "tool_call",