@gotgenes/pi-permission-system 3.0.4 → 3.1.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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).
 
+## [3.1.0](https://github.com/gotgenes/pi-permission-system/compare/v3.0.5...v3.1.0) (2026-05-03)
+
+
+### Features
+
+* add bash external-directory format helpers ([#39](https://github.com/gotgenes/pi-permission-system/issues/39)) ([5c7e93c](https://github.com/gotgenes/pi-permission-system/commit/5c7e93cbe5c428ab3ed5e32ab3f2bb8c3fe0431b))
+* enforce external_directory gate on bash commands ([#39](https://github.com/gotgenes/pi-permission-system/issues/39)) ([5342139](https://github.com/gotgenes/pi-permission-system/commit/53421391c5f5f3b277e26ea7cbee23ef06b6db41))
+* extract external paths from bash command tokens ([#39](https://github.com/gotgenes/pi-permission-system/issues/39)) ([8cb3c2a](https://github.com/gotgenes/pi-permission-system/commit/8cb3c2a1b56007ca10e634bd6be5b464ddfea957))
+
+
+### Documentation
+
+* document bash external_directory gate in README ([#39](https://github.com/gotgenes/pi-permission-system/issues/39)) ([d33e1ea](https://github.com/gotgenes/pi-permission-system/commit/d33e1ea2686e5390f9904d554668c00305702fc1))
+* plan bash external_directory gate ([#39](https://github.com/gotgenes/pi-permission-system/issues/39)) ([ba80c64](https://github.com/gotgenes/pi-permission-system/commit/ba80c647668542f934e2c14148cf94fb11d110da))
+
+## [3.0.5](https://github.com/gotgenes/pi-permission-system/compare/v3.0.4...v3.0.5) (2026-05-03)
+
+
+### Miscellaneous Chores
+
+* **deps:** update dependencies and clean up unused peers ([d8482a9](https://github.com/gotgenes/pi-permission-system/commit/d8482a9aab4a41798ba50e7b5db9ede1dcb7897a))
+
 ## [3.0.4](https://github.com/gotgenes/pi-permission-system/compare/v3.0.3...v3.0.4) (2026-05-03)
 
 

package/README.md

@@ -21,7 +21,7 @@ Permission enforcement extension for the Pi coding agent that provides centraliz
 - **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
+- **External Directory Guard** — Enforces `special.external_directory` for path-bearing file tools and bash commands that reference paths outside the active working directory
 
 ## Installation
 
@@ -97,6 +97,7 @@ The extension integrates via Pi's lifecycle hooks:
 - 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 bounded `toolInputPreview` values for non-bash/non-MCP tool calls so approvals can be audited without writing raw full payloads
 - 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`
+- Bash commands are scanned for path tokens (absolute, `~/`, or `..`-relative) that resolve outside `ctx.cwd`; matching commands trigger the same `special.external_directory` gate before the normal bash pattern check
 
 ## Configuration
 
@@ -353,7 +354,7 @@ Reserved permission checks:
 | Key                  | Description                                                                                                                                                                   |
 | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `doom_loop`          | Controls doom loop detection behavior                                                                                                                                         |
-| `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 |
+| `external_directory` | Enforces ask/allow/deny decisions for path-bearing tools and bash commands that reference paths outside the active working directory                                          |
 
 ```jsonc
 {
@@ -366,6 +367,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.
 
+Bash commands are also covered: the extension extracts path-like tokens from the command string and applies the same gate when any resolve outside `ctx.cwd`. Quoted strings are stripped first to reduce false positives (e.g., paths inside `git commit -m "..."` messages). This is a best-effort heuristic — variable expansion, subshells, and escaped quotes are not parsed.
+
 ---
 
 ## Common Recipes
@@ -626,14 +629,14 @@ The old extension-root `config.json` is no longer read from the install director
 ## Development
 
 ```bash
-npm run build       # Type-check TypeScript (no emit)
-npm run lint        # Biome lint + format check
-npm run lint:fix    # Biome lint + format auto-fix
-npm run lint:md     # markdownlint-cli2 on README etc.
-npm run lint:all    # lint + lint:md
-npm run format      # Biome format --write
-npm run test        # Run tests from ./tests
-npm run check       # build + lint:all + test
+pnpm run build       # Type-check TypeScript (no emit)
+pnpm run lint        # Biome lint + format check
+pnpm run lint:fix    # Biome lint + format auto-fix
+pnpm run lint:md     # markdownlint-cli2 on README etc.
+pnpm run lint:all    # lint + lint:md
+pnpm run format      # Biome format --write
+pnpm run test        # Run tests from ./tests
+pnpm run check       # build + lint:all + test
 ```
 
 ### Pre-commit hooks
@@ -642,7 +645,7 @@ This project uses [prek](https://prek.j178.dev/) to run Biome and markdownlint o
 This catches lint and formatting issues locally instead of waiting for CI.
 
 1. Install prek ([installation guide](https://prek.j178.dev/installation/)).
-2. Run `npm install` — the `prepare` script calls `prek install` automatically.
+2. Run `pnpm install` — the `prepare` script calls `prek install` automatically.
    If prek is not installed, the script prints a warning and continues.
 3. Hooks run automatically on `git commit`.
    To skip in emergencies: `git commit --no-verify`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "3.0.4",
+  "version": "3.1.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "main": "./index.ts",
@@ -17,20 +17,6 @@
     "CHANGELOG.md",
     "LICENSE"
   ],
-  "scripts": {
-    "prepare": "command -v prek >/dev/null 2>&1 && prek install || echo 'prek not found — skipping hook install (see README)'",
-    "build": "tsc -p tsconfig.json",
-    "lint": "biome check .",
-    "lint:fix": "biome check --write .",
-    "lint:md": "markdownlint-cli2 '*.md' 'docs/**/*.md' '.pi/prompts/**/*.md'",
-    "lint:md:fix": "markdownlint-cli2 --fix '*.md' 'docs/**/*.md' '.pi/prompts/**/*.md'",
-    "lint:imports": "! grep -rn --include='*.ts' 'from \"\\.[./][^\"]*\\.js\"' src/ tests/ index.ts",
-    "lint:all": "npm run lint && npm run lint:md && npm run lint:imports",
-    "format": "biome format --write .",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "check": "npm run build && npm run lint:all && npm run test"
-  },
   "keywords": [
     "pi-package",
     "pi",
@@ -67,20 +53,29 @@
     ]
   },
   "peerDependencies": {
-    "@mariozechner/pi-ai": "^0.70.5",
-    "@mariozechner/pi-coding-agent": "^0.70.5",
-    "@mariozechner/pi-tui": "^0.70.5",
-    "@sinclair/typebox": "^0.34.49"
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.13",
-    "@mariozechner/pi-ai": "^0.70.5",
-    "@mariozechner/pi-coding-agent": "^0.70.5",
-    "@mariozechner/pi-tui": "^0.70.5",
-    "@sinclair/typebox": "^0.34.49",
-    "@types/node": "^22.19.17",
+    "@mariozechner/pi-coding-agent": "^0.72.1",
+    "@mariozechner/pi-tui": "^0.72.1",
+    "@types/node": "^25.6.0",
     "markdownlint-cli2": "^0.22.1",
     "typescript": "6.0.3",
     "vitest": "^4.1.5"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "lint:md": "markdownlint-cli2 '*.md' 'docs/**/*.md' '.pi/prompts/**/*.md'",
+    "lint:md:fix": "markdownlint-cli2 --fix '*.md' 'docs/**/*.md' '.pi/prompts/**/*.md'",
+    "lint:imports": "! grep -rn --include='*.ts' 'from \"\\.[./][^\"]*\\.js\"' src/ tests/ index.ts",
+    "lint:all": "pnpm run lint && pnpm run lint:md && pnpm run lint:imports",
+    "format": "biome format --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check": "pnpm run build && pnpm run lint:all && pnpm run test"
   }
-}
+}

package/src/external-directory.ts

@@ -111,3 +111,105 @@ export function formatExternalDirectoryUserDeniedReason(
   const reasonSuffix = denialReason ? ` Reason: ${denialReason}.` : "";
   return `User denied external directory access for tool '${toolName}' path '${pathValue}'.${reasonSuffix} ${formatExternalDirectoryHardStopHint()}`;
 }
+
+export function formatBashExternalDirectoryAskPrompt(
+  command: string,
+  externalPaths: string[],
+  cwd: string,
+  agentName?: string,
+): string {
+  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
+  const pathList = externalPaths.join(", ");
+  return `${subject} requested bash command '${command}' which references path(s) outside working directory '${cwd}': ${pathList}. Allow this external directory access?`;
+}
+
+export function formatBashExternalDirectoryDenyReason(
+  command: string,
+  externalPaths: string[],
+  cwd: string,
+  agentName?: string,
+): string {
+  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
+  const pathList = externalPaths.join(", ");
+  return `${subject} is not permitted to run bash command '${command}' which references path(s) outside working directory '${cwd}': ${pathList}. ${formatExternalDirectoryHardStopHint()}`;
+}
+
+/**
+ * URL pattern to skip tokens that look like URLs rather than paths.
+ */
+const URL_PATTERN = /^[a-z][a-z0-9+.-]*:\/\//i;
+
+/**
+ * Determines whether a token looks like a path candidate worth resolving.
+ * Returns the raw token string if it's a candidate, or null to skip.
+ */
+function classifyTokenAsPathCandidate(token: string): string | null {
+  // Skip empty tokens
+  if (!token) return null;
+
+  // Skip flags
+  if (token.startsWith("-")) return null;
+
+  // Skip env assignments (FOO=/bar)
+  const eqIndex = token.indexOf("=");
+  const slashIndex = token.indexOf("/");
+  if (eqIndex !== -1 && (slashIndex === -1 || eqIndex < slashIndex)) {
+    return null;
+  }
+
+  // Skip URLs
+  if (URL_PATTERN.test(token)) return null;
+
+  // Skip @scope/package patterns
+  if (token.startsWith("@") && !token.startsWith("@/")) return null;
+
+  // Must look like a path: starts with /, ~/, or contains ..
+  if (token.startsWith("/")) return token;
+  if (token.startsWith("~/")) return token;
+  if (token.includes("..")) return token;
+
+  return null;
+}
+
+/**
+ * Strips content inside single and double quotes from a command string.
+ * Replaces quoted segments with empty string so paths inside quotes are not tokenized.
+ * This is a simple regex approach — it cannot handle escaped quotes within strings.
+ */
+function stripQuotedStrings(command: string): string {
+  return command.replace(/"[^"]*"/g, "").replace(/'[^']*'/g, "");
+}
+
+/**
+ * Extracts paths from a bash command string that resolve outside CWD.
+ * This is a best-effort heuristic (token splitting, not full shell parsing).
+ */
+export function extractExternalPathsFromBashCommand(
+  command: string,
+  cwd: string,
+): string[] {
+  // Strip quoted strings to avoid false positives on paths in messages
+  const unquoted = stripQuotedStrings(command);
+  // Split on shell metacharacters to isolate tokens
+  const tokens = unquoted.split(/[|;&><\s]+/).filter(Boolean);
+  const seen = new Set<string>();
+  const externalPaths: string[] = [];
+
+  for (const token of tokens) {
+    const candidate = classifyTokenAsPathCandidate(token);
+    if (!candidate) continue;
+
+    const normalized = normalizePathForComparison(candidate, cwd);
+    if (!normalized) continue;
+
+    if (
+      isPathOutsideWorkingDirectory(candidate, cwd) &&
+      !seen.has(normalized)
+    ) {
+      seen.add(normalized);
+      externalPaths.push(normalized);
+    }
+  }
+
+  return externalPaths;
+}

package/src/index.ts

@@ -22,7 +22,7 @@ import {
   createBeforeAgentStartPromptStateKey,
   shouldApplyCachedAgentStartState,
 } from "./before-agent-start-cache";
-import { toRecord } from "./common";
+import { getNonEmptyString, toRecord } from "./common";
 import { loadAndMergeConfigs, loadUnifiedConfig } from "./config-loader";
 import { registerPermissionSystemCommand } from "./config-modal";
 import {
@@ -44,8 +44,12 @@ import {
   type PermissionSystemExtensionConfig,
 } from "./extension-config";
 import {
+  extractExternalPathsFromBashCommand,
+  formatBashExternalDirectoryAskPrompt,
+  formatBashExternalDirectoryDenyReason,
   formatExternalDirectoryAskPrompt,
   formatExternalDirectoryDenyReason,
+  formatExternalDirectoryHardStopHint,
   formatExternalDirectoryUserDeniedReason,
   getPathBearingToolPath,
   isPathOutsideWorkingDirectory,
@@ -897,6 +901,90 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       // state === "allow" → fall through to normal permission check
     }
 
+    // Bash external directory gate: extract paths from bash commands
+    if (ctx.cwd && toolName === "bash") {
+      const command = getNonEmptyString(toRecord(input).command);
+      if (command) {
+        const externalPaths = extractExternalPathsFromBashCommand(
+          command,
+          ctx.cwd,
+        );
+        if (externalPaths.length > 0) {
+          const extCheck = permissionManager.checkPermission(
+            "external_directory",
+            {},
+            agentName ?? undefined,
+          );
+
+          if (extCheck.state === "deny") {
+            writeReviewLog("permission_request.blocked", {
+              source: "tool_call",
+              toolCallId: event.toolCallId,
+              toolName,
+              agentName,
+              command,
+              externalPaths,
+              resolution: "policy_denied",
+            });
+            return {
+              block: true,
+              reason: formatBashExternalDirectoryDenyReason(
+                command,
+                externalPaths,
+                ctx.cwd,
+                agentName ?? undefined,
+              ),
+            };
+          }
+
+          if (extCheck.state === "ask") {
+            const message = formatBashExternalDirectoryAskPrompt(
+              command,
+              externalPaths,
+              ctx.cwd,
+              agentName ?? undefined,
+            );
+            if (!canRequestPermissionConfirmation(ctx)) {
+              writeReviewLog("permission_request.blocked", {
+                source: "tool_call",
+                toolCallId: event.toolCallId,
+                toolName,
+                agentName,
+                command,
+                externalPaths,
+                message,
+                resolution: "confirmation_unavailable",
+              });
+              return {
+                block: true,
+                reason: `Bash command '${command}' references path(s) outside the working directory and 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,
+              command,
+            });
+            if (!extDecision.approved) {
+              const reasonSuffix = extDecision.denialReason
+                ? ` Reason: ${extDecision.denialReason}.`
+                : "";
+              return {
+                block: true,
+                reason: `User denied external directory access for bash command '${command}'.${reasonSuffix} ${formatExternalDirectoryHardStopHint()}`,
+              };
+            }
+          }
+          // state === "allow" → fall through to normal bash permission check
+        }
+      }
+    }
+
     const check = permissionManager.checkPermission(
       toolName,
       input,

package/tests/bash-external-directory.test.ts

@@ -0,0 +1,301 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+
+// Mock node:os so tilde-expansion is deterministic across platforms.
+vi.mock("node:os", () => {
+  const homedir = vi.fn(() => "/mock/home");
+  return {
+    homedir,
+    default: { homedir },
+  };
+});
+
+import {
+  extractExternalPathsFromBashCommand,
+  formatBashExternalDirectoryAskPrompt,
+  formatBashExternalDirectoryDenyReason,
+} from "../src/external-directory";
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("extractExternalPathsFromBashCommand", () => {
+  const cwd = "/projects/my-app";
+
+  describe("absolute paths", () => {
+    test("detects absolute path outside CWD", () => {
+      const result = extractExternalPathsFromBashCommand("cat /etc/hosts", cwd);
+      expect(result).toContain("/etc/hosts");
+    });
+
+    test("detects multiple absolute paths outside CWD", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "diff /etc/hosts /var/log/syslog",
+        cwd,
+      );
+      expect(result).toContain("/etc/hosts");
+      expect(result).toContain("/var/log/syslog");
+    });
+
+    test("does not flag absolute path within CWD", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "cat /projects/my-app/src/index.ts",
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+  });
+
+  describe("home-relative paths", () => {
+    test("detects ~/path outside CWD", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "cat ~/documents/secret.txt",
+        cwd,
+      );
+      expect(result).toContain("/mock/home/documents/secret.txt");
+    });
+
+    test("does not flag ~/path that resolves within CWD", () => {
+      // CWD is under /mock/home for this test
+      const result = extractExternalPathsFromBashCommand(
+        "cat ~/myproject/file.ts",
+        "/mock/home/myproject",
+      );
+      expect(result).toHaveLength(0);
+    });
+  });
+
+  describe("dot-dot relative paths", () => {
+    test("detects ../ path that resolves outside CWD", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "cat ../../other-project/secrets.env",
+        cwd,
+      );
+      expect(result).toContain("/other-project/secrets.env");
+    });
+
+    test("does not flag ../ path that stays within CWD", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "cat src/../lib/utils.ts",
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+  });
+
+  describe("commands within CWD only", () => {
+    test("returns empty for relative paths within CWD", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "cat src/index.ts",
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+
+    test("returns empty for bare command with no path arguments", () => {
+      const result = extractExternalPathsFromBashCommand("git status", cwd);
+      expect(result).toHaveLength(0);
+    });
+  });
+
+  describe("flags are skipped", () => {
+    test("does not treat flags as paths", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "ls -la --color=auto",
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+
+    test("detects path after flags", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "ls -la /etc/passwd",
+        cwd,
+      );
+      expect(result).toContain("/etc/passwd");
+    });
+  });
+
+  describe("env assignments are skipped", () => {
+    test("does not treat FOO=/bar as a path", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "FOO=/usr/local/bin command",
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+  });
+
+  describe("shell metacharacters split correctly", () => {
+    test("detects path after pipe", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "echo hello | tee /tmp/output.txt",
+        cwd,
+      );
+      expect(result).toContain("/tmp/output.txt");
+    });
+
+    test("detects path after semicolon", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "echo done; cat /etc/hosts",
+        cwd,
+      );
+      expect(result).toContain("/etc/hosts");
+    });
+
+    test("detects path after &&", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "true && cat /etc/hosts",
+        cwd,
+      );
+      expect(result).toContain("/etc/hosts");
+    });
+
+    test("detects path in redirect target", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "echo hello > /tmp/out.txt",
+        cwd,
+      );
+      expect(result).toContain("/tmp/out.txt");
+    });
+  });
+
+  describe("URLs are skipped", () => {
+    test("does not treat http:// URL as a path", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "curl http://example.com/path",
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+
+    test("does not treat https:// URL as a path", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "curl https://example.com/etc/hosts",
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+  });
+
+  describe("@scope/package patterns are skipped", () => {
+    test("does not treat @scope/package as a path", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "npm install @types/node",
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+  });
+
+  describe("quoted strings are ignored", () => {
+    test("does not flag path inside double-quoted string", () => {
+      const result = extractExternalPathsFromBashCommand(
+        'git commit -m "fix: update /etc/hosts handler"',
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+
+    test("does not flag path inside single-quoted string", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "echo 'see /usr/local/docs for info'",
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+
+    test("still flags unquoted path alongside quoted content", () => {
+      const result = extractExternalPathsFromBashCommand(
+        'cat /etc/hosts && echo "done"',
+        cwd,
+      );
+      expect(result).toContain("/etc/hosts");
+    });
+
+    test.fails("escaped quotes inside strings cause false positive (known limitation)", () => {
+      // The regex-based quote stripping can't handle escaped quotes
+      const result = extractExternalPathsFromBashCommand(
+        'echo "path is "/etc/hosts""',
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+  });
+
+  describe("deduplication", () => {
+    test("returns deduplicated paths", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "cat /etc/hosts; grep foo /etc/hosts",
+        cwd,
+      );
+      const etcHostsCount = result.filter((p) => p === "/etc/hosts").length;
+      expect(etcHostsCount).toBe(1);
+    });
+  });
+});
+
+describe("formatBashExternalDirectoryAskPrompt", () => {
+  test("includes command, external paths, and CWD", () => {
+    const result = formatBashExternalDirectoryAskPrompt(
+      "cat /etc/hosts",
+      ["/etc/hosts"],
+      "/projects/my-app",
+    );
+    expect(result).toContain("cat /etc/hosts");
+    expect(result).toContain("/etc/hosts");
+    expect(result).toContain("/projects/my-app");
+  });
+
+  test("includes agent name when provided", () => {
+    const result = formatBashExternalDirectoryAskPrompt(
+      "cat /etc/hosts",
+      ["/etc/hosts"],
+      "/projects/my-app",
+      "my-agent",
+    );
+    expect(result).toContain("my-agent");
+  });
+
+  test("shows multiple external paths", () => {
+    const result = formatBashExternalDirectoryAskPrompt(
+      "diff /etc/hosts /var/log/syslog",
+      ["/etc/hosts", "/var/log/syslog"],
+      "/projects/my-app",
+    );
+    expect(result).toContain("/etc/hosts");
+    expect(result).toContain("/var/log/syslog");
+  });
+});
+
+describe("formatBashExternalDirectoryDenyReason", () => {
+  test("includes command, external paths, and CWD", () => {
+    const result = formatBashExternalDirectoryDenyReason(
+      "cat /etc/hosts",
+      ["/etc/hosts"],
+      "/projects/my-app",
+    );
+    expect(result).toContain("cat /etc/hosts");
+    expect(result).toContain("/etc/hosts");
+    expect(result).toContain("/projects/my-app");
+  });
+
+  test("includes hard stop hint", () => {
+    const result = formatBashExternalDirectoryDenyReason(
+      "cat /etc/hosts",
+      ["/etc/hosts"],
+      "/projects/my-app",
+    );
+    expect(result).toContain("Hard stop");
+  });
+
+  test("includes agent name when provided", () => {
+    const result = formatBashExternalDirectoryDenyReason(
+      "cat /etc/hosts",
+      ["/etc/hosts"],
+      "/projects/my-app",
+      "my-agent",
+    );
+    expect(result).toContain("my-agent");
+  });
+});

package/tests/permission-system.test.ts

@@ -2313,6 +2313,162 @@ test("tool_call skips external_directory checks for optional path tools without
   }
 });
 
+// --- bash external_directory integration tests (#39) ---
+
+test("tool_call blocks bash command with external path when external_directory is denied", async () => {
+  const harness = createToolCallHarness(
+    {
+      defaultPolicy: {
+        tools: "allow",
+        bash: "allow",
+        mcp: "allow",
+        skills: "allow",
+        special: "ask",
+      },
+      special: { external_directory: "deny" },
+    },
+    ["bash"],
+  );
+
+  try {
+    const result = await runToolCall(harness, {
+      toolName: "bash",
+      toolCallId: "bash-external-deny",
+      input: { command: "cat /etc/hosts" },
+    });
+
+    assert.equal(result.block, true);
+    assert.match(
+      String(result.reason),
+      /external directory permission denial/i,
+    );
+    assert.match(String(result.reason), /\/etc\/hosts/);
+  } finally {
+    await harness.cleanup();
+  }
+});
+
+test("tool_call allows bash command with only internal paths when external_directory is denied", async () => {
+  const harness = createToolCallHarness(
+    {
+      defaultPolicy: {
+        tools: "allow",
+        bash: "allow",
+        mcp: "allow",
+        skills: "allow",
+        special: "ask",
+      },
+      special: { external_directory: "deny" },
+    },
+    ["bash"],
+  );
+
+  try {
+    const result = await runToolCall(harness, {
+      toolName: "bash",
+      toolCallId: "bash-internal-allow",
+      input: { command: "cat src/index.ts" },
+    });
+
+    assert.deepEqual(result, {});
+  } finally {
+    await harness.cleanup();
+  }
+});
+
+test("tool_call prompts for bash command with external path when external_directory is ask", async () => {
+  const harness = createToolCallHarness(
+    {
+      defaultPolicy: {
+        tools: "allow",
+        bash: "allow",
+        mcp: "allow",
+        skills: "allow",
+        special: "ask",
+      },
+      special: { external_directory: "ask" },
+    },
+    ["bash"],
+  );
+
+  try {
+    const result = await runToolCall(harness, {
+      toolName: "bash",
+      toolCallId: "bash-external-ask-no-ui",
+      input: { command: "cat /etc/hosts" },
+    });
+
+    // No UI available in default harness, so it should block
+    assert.equal(result.block, true);
+    assert.match(
+      String(result.reason),
+      /requires approval.*no interactive UI/i,
+    );
+  } finally {
+    await harness.cleanup();
+  }
+});
+
+test("tool_call allows bash command with external path when external_directory is allow", async () => {
+  const harness = createToolCallHarness(
+    {
+      defaultPolicy: {
+        tools: "allow",
+        bash: "allow",
+        mcp: "allow",
+        skills: "allow",
+        special: "ask",
+      },
+      special: { external_directory: "allow" },
+    },
+    ["bash"],
+  );
+
+  try {
+    const result = await runToolCall(harness, {
+      toolName: "bash",
+      toolCallId: "bash-external-allow",
+      input: { command: "cat /etc/hosts" },
+    });
+
+    // Should pass through to normal bash permission (which is also allow)
+    assert.deepEqual(result, {});
+  } finally {
+    await harness.cleanup();
+  }
+});
+
+test("tool_call applies bash pattern permissions after external_directory allow", async () => {
+  const harness = createToolCallHarness(
+    {
+      defaultPolicy: {
+        tools: "allow",
+        bash: "allow",
+        mcp: "allow",
+        skills: "allow",
+        special: "ask",
+      },
+      special: { external_directory: "allow" },
+      bash: { "cat *": "deny" },
+    },
+    ["bash"],
+  );
+
+  try {
+    const result = await runToolCall(harness, {
+      toolName: "bash",
+      toolCallId: "bash-pattern-deny-after-ext-allow",
+      input: { command: "cat /etc/hosts" },
+    });
+
+    // external_directory allows, but bash pattern denies
+    assert.equal(result.block, true);
+    assert.match(String(result.reason), /not permitted/i);
+  } finally {
+    await harness.cleanup();
+  }
+});
+
 test("generic ask prompts include serialized tool input for informed approval", async () => {
   const harness = createToolCallHarness(
     {