@gotgenes/pi-permission-system 4.8.0 → 4.9.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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).
 
+## [4.9.0](https://github.com/gotgenes/pi-permission-system/compare/v4.8.0...v4.9.0) (2026-05-05)
+
+
+### Features
+
+* bypass external_directory gate for Pi infrastructure reads ([229a352](https://github.com/gotgenes/pi-permission-system/commit/229a35222dd47f1d0c079f0bcd34760569e912f3))
+
+
+### Bug Fixes
+
+* skip regex patterns in bash external-directory path extraction ([9fe4ba6](https://github.com/gotgenes/pi-permission-system/commit/9fe4ba6d259c25aa0a9e3a5508884d26a303cac3))
+
+
+### Documentation
+
+* document piInfrastructureReadPaths config and infrastructure auto-allow ([65e0ac8](https://github.com/gotgenes/pi-permission-system/commit/65e0ac8ef8a4973c261628e026c3772faa0849ab))
+* plan auto-allow reads from Pi infrastructure directories ([#48](https://github.com/gotgenes/pi-permission-system/issues/48)) ([06b8d44](https://github.com/gotgenes/pi-permission-system/commit/06b8d441d569b1c2893f5c434357eb8b2fc9180f))
+* **retro:** add retro notes for issue [#53](https://github.com/gotgenes/pi-permission-system/issues/53) ([1988d7a](https://github.com/gotgenes/pi-permission-system/commit/1988d7ab09432df09825c560ba377233e0d3ab33))
+
 ## [4.8.0](https://github.com/gotgenes/pi-permission-system/compare/v4.7.0...v4.8.0) (2026-05-05)
 
 

package/README.md

@@ -118,6 +118,7 @@ The config file combines runtime knobs and permission policy in one object:
   "debugLog": false,
   "permissionReviewLog": true,
   "yoloMode": false,
+  "piInfrastructureReadPaths": [],  // extra dirs to auto-allow for reads
 
   // Flat permission policy
   "permission": {
@@ -134,11 +135,12 @@ The config file combines runtime knobs and permission policy in one object:
 
 #### Runtime knobs
 
-| Key                   | Default | Description                                                                                             |
-| --------------------- | ------- | ------------------------------------------------------------------------------------------------------- |
-| `debugLog`            | `false` | Enables verbose diagnostic logging to `logs/pi-permission-system-debug.jsonl`                           |
-| `permissionReviewLog` | `true`  | Enables the permission request/denial review log at `logs/pi-permission-system-permission-review.jsonl` |
-| `yoloMode`            | `false` | Auto-approves `ask` results instead of prompting when yolo mode is enabled                              |
+| Key                          | Default | Description                                                                                             |
+| ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------- |
+| `debugLog`                   | `false` | Enables verbose diagnostic logging to `logs/pi-permission-system-debug.jsonl`                           |
+| `permissionReviewLog`        | `true`  | Enables the permission request/denial review log at `logs/pi-permission-system-permission-review.jsonl` |
+| `yoloMode`                   | `false` | Auto-approves `ask` results instead of prompting when yolo mode is enabled                              |
+| `piInfrastructureReadPaths`  | `[]`    | Extra directories to auto-allow for reads, bypassing the `external_directory` gate (supports `~`)       |
 
 Both logs write to `~/.pi/agent/extensions/pi-permission-system/logs/`.
 No debug output is printed to the terminal.
@@ -372,6 +374,17 @@ Quoted strings are stripped first to reduce false positives.
 This is a best-effort heuristic — variable expansion, subshells, and escaped quotes are not parsed.
 OS device paths (`/dev/null`, `/dev/stdin`, `/dev/stdout`, `/dev/stderr`) are always excluded.
 
+**Pi infrastructure read auto-allow** — Read-only tools (`read`, `find`, `grep`, `ls`) targeting Pi infrastructure directories are automatically allowed without triggering the gate, even when `external_directory` is `ask` or `deny`.
+Infrastructure directories include:
+
+1. The agent config directory (`~/.pi/agent/` or `$PI_CODING_AGENT_DIR`)
+2. Git-cloned global packages (`<agentDir>/git/`)
+3. The global `node_modules` root (auto-discovered from the extension's own install path — works for npm, pnpm, bun, Homebrew)
+4. Project-local Pi packages (`<cwd>/.pi/npm/` and `<cwd>/.pi/git/`)
+5. Any paths listed in `piInfrastructureReadPaths`
+
+Write tools (`write`, `edit`) to infrastructure paths are **not** auto-allowed and still go through the gate.
+
 ---
 
 ## Common Recipes

package/config/config.example.json

@@ -5,6 +5,8 @@
   "permissionReviewLog": true,
   "yoloMode": false,
 
+  "piInfrastructureReadPaths": [],
+
   "permission": {
     "*": "ask",
     "read": "allow",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "files": [

package/schemas/permissions.schema.json

@@ -29,6 +29,16 @@
       "type": "boolean",
       "default": false
     },
+    "piInfrastructureReadPaths": {
+      "description": "Additional directories to auto-allow for reads as Pi infrastructure, bypassing the external_directory gate. Supports ~ expansion. Directory prefixes only (no globs).",
+      "markdownDescription": "Additional directories to auto-allow for reads as Pi infrastructure, bypassing the `external_directory` gate.\n\nThe extension auto-discovers the global node_modules root, `agentDir`, `agentDir/git`, and project-local `.pi/npm/` and `.pi/git/`. Add entries here for edge cases where auto-discovery is insufficient.\n\nSupports `~` expansion. Directory prefixes only — no glob patterns.",
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "default": []
+    },
     "permission": {
       "description": "Flat permission policy. Each key is a surface name; values are a PermissionState string (catch-all) or a pattern→action map.",
       "markdownDescription": "Flat permission policy.\n\nEach top-level key is a surface name:\n- `\"*\"` — universal fallback (replaces `defaultPolicy.tools` from the legacy format)\n- Tool names (`read`, `write`, `bash`, `mcp`, `skill`, `external_directory`, etc.)\n\nA **string** value is shorthand for `{ \"*\": action }` (surface-level catch-all).\nAn **object** value maps wildcard patterns to actions — last matching pattern wins.\n\n**Merge order (lowest → highest precedence):** global → project → per-agent frontmatter.",

package/src/extension-config.ts

@@ -17,6 +17,8 @@ export interface PermissionSystemExtensionConfig {
   debugLog: boolean;
   permissionReviewLog: boolean;
   yoloMode: boolean;
+  /** Additional directories to auto-allow for reads as Pi infrastructure. */
+  piInfrastructureReadPaths?: string[];
 }
 
 export interface PermissionSystemConfigLoadResult {
@@ -81,11 +83,21 @@ export function normalizePermissionSystemConfig(
   raw: unknown,
 ): PermissionSystemExtensionConfig {
   const record = toRecord(raw);
-  return {
+  const rawPaths = record.piInfrastructureReadPaths;
+  const piInfrastructureReadPaths: string[] | undefined =
+    Array.isArray(rawPaths) &&
+    rawPaths.every((p): p is string => typeof p === "string")
+      ? rawPaths
+      : undefined;
+  const result: PermissionSystemExtensionConfig = {
     debugLog: record.debugLog === true,
     permissionReviewLog: record.permissionReviewLog !== false,
     yoloMode: record.yoloMode === true,
   };
+  if (piInfrastructureReadPaths !== undefined) {
+    result.piInfrastructureReadPaths = piInfrastructureReadPaths;
+  }
+  return result;
 }
 
 function ensureConfigDirectory(configPath: string): void {

package/src/external-directory.ts

@@ -1,9 +1,38 @@
 import { createRequire } from "node:module";
 import { homedir } from "node:os";
-import { join, normalize, resolve, sep } from "node:path";
+import { basename, dirname, join, normalize, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import { getNonEmptyString, toRecord } from "./common";
 
+/**
+ * Discover the global node_modules root by walking up from the given file URL
+ * (defaults to this module's own `import.meta.url`).
+ *
+ * Works regardless of package manager (npm, pnpm, bun, Homebrew) because the
+ * extension itself is installed inside the directory we want to find.
+ * Returns `null` when the file is not inside any node_modules tree, or when
+ * the URL cannot be parsed — callers must degrade gracefully.
+ */
+export function discoverGlobalNodeModulesRoot(
+  fromUrl = import.meta.url,
+): string | null {
+  try {
+    const thisFile = fileURLToPath(fromUrl);
+    let dir = dirname(thisFile);
+    // Walk up until we find a directory named "node_modules" or hit the root.
+    while (dir !== dirname(dir)) {
+      if (basename(dir) === "node_modules") {
+        return dir;
+      }
+      dir = dirname(dir);
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Paths that are universally safe and should never trigger external-directory checks.
  * These are OS device files: read returns EOF or process streams, write discards or goes to process streams.
@@ -23,6 +52,60 @@ export function isSafeSystemPath(normalizedPath: string): boolean {
   return SAFE_SYSTEM_PATHS.has(normalizedPath);
 }
 
+/**
+ * Returns true if the given tool + normalized path combination qualifies for
+ * automatic allow as a Pi infrastructure read.
+ *
+ * A path qualifies when:
+ * 1. The tool is read-only (in READ_ONLY_PATH_BEARING_TOOLS).
+ * 2. The normalized path is within one of the provided `infrastructureDirs`
+ *    OR within the project-local Pi package directories
+ *    (`<cwd>/.pi/npm/` or `<cwd>/.pi/git/`).
+ *
+ * `infrastructureDirs` should contain pre-expanded absolute paths (no `~`).
+ * Project-local paths are computed fresh from `cwd` on each call so they
+ * follow working-directory changes without a runtime rebuild.
+ */
+export function isPiInfrastructureRead(
+  toolName: string,
+  normalizedPath: string,
+  infrastructureDirs: readonly string[],
+  cwd: string,
+): boolean {
+  if (!READ_ONLY_PATH_BEARING_TOOLS.has(toolName)) {
+    return false;
+  }
+
+  for (const dir of infrastructureDirs) {
+    if (isPathWithinDirectory(normalizedPath, dir)) {
+      return true;
+    }
+  }
+
+  // Project-local Pi packages — checked fresh every call so CWD changes work.
+  const projectNpmDir = join(cwd, ".pi", "npm");
+  const projectGitDir = join(cwd, ".pi", "git");
+  if (isPathWithinDirectory(normalizedPath, projectNpmDir)) {
+    return true;
+  }
+  if (isPathWithinDirectory(normalizedPath, projectGitDir)) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * File tools that only read — never write — the filesystem.
+ * Only these tools are eligible for the Pi infrastructure auto-allow.
+ */
+export const READ_ONLY_PATH_BEARING_TOOLS: ReadonlySet<string> = new Set([
+  "read",
+  "find",
+  "grep",
+  "ls",
+]);
+
 export const PATH_BEARING_TOOLS = new Set([
   "read",
   "write",
@@ -352,6 +435,13 @@ function collectPathCandidateTokens(node: TSNode, tokens: string[]): void {
  */
 const URL_PATTERN = /^[a-z][a-z0-9+.-]*:\/\//i;
 
+/**
+ * Regex metacharacter sequences that are never found in real filesystem paths.
+ * If a token contains any of these, it is almost certainly a regex pattern
+ * (e.g. a grep argument) rather than a path.
+ */
+const REGEX_METACHAR_PATTERN = /\.\*|\.\+|\\\||\\\(|\\\)|\[.*?\]|\^\//;
+
 /**
  * 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.
@@ -380,6 +470,11 @@ function classifyTokenAsPathCandidate(token: string): string | null {
   // and are never meaningful path arguments in practice.
   if (/^\/+$/.test(token)) return null;
 
+  // Skip tokens that contain regex metacharacter sequences — these are almost
+  // certainly grep/sed/awk patterns, not filesystem paths.
+  // Matches: .*, .+, \|, \(, \), [...], or ^/ (anchored regex starting with /)
+  if (REGEX_METACHAR_PATTERN.test(token)) return null;
+
   // Must look like a path: starts with /, ~/, or contains ..
   if (token.startsWith("/")) return token;
   if (token.startsWith("~/")) return token;

package/src/handlers/tool-call.ts

@@ -15,6 +15,7 @@ import {
   formatExternalDirectoryUserDeniedReason,
   getPathBearingToolPath,
   isPathOutsideWorkingDirectory,
+  isPiInfrastructureRead,
   normalizePathForComparison,
   PATH_BEARING_TOOLS,
 } from "../external-directory";
@@ -170,82 +171,107 @@ export async function handleToolCall(
       externalDirectoryPath,
       ctx.cwd,
     );
-    const extCheck = deps.runtime.permissionManager.checkPermission(
-      "external_directory",
-      { path: normalizedExtPath },
-      agentName ?? undefined,
-      deps.runtime.sessionRules.getRuleset(),
-    );
 
-    if (extCheck.source === "session") {
-      deps.runtime.writeReviewLog("permission_request.session_approved", {
-        source: "tool_call",
-        toolCallId: (event as { toolCallId: string }).toolCallId,
-        toolName,
-        agentName,
-        path: externalDirectoryPath,
-        resolution: "session_approved",
-        sessionApprovalPattern: extCheck.matchedPattern,
-      });
-      // Fall through to normal permission check
+    // ── Pi infrastructure read bypass ──────────────────────────────────
+    // Auto-allow read-only tools targeting Pi infrastructure directories
+    // (agent dir, global node_modules, project-local .pi/npm|git, and
+    // any user-configured extras).  Writes are never bypassed.
+    const allInfraDirs = [
+      ...deps.runtime.piInfrastructureDirs,
+      ...(deps.runtime.config.piInfrastructureReadPaths ?? []),
+    ];
+    if (
+      isPiInfrastructureRead(toolName, normalizedExtPath, allInfraDirs, ctx.cwd)
+    ) {
+      deps.runtime.writeReviewLog(
+        "permission_request.infrastructure_auto_allowed",
+        {
+          source: "tool_call",
+          toolCallId: (event as { toolCallId: string }).toolCallId,
+          toolName,
+          agentName,
+          path: externalDirectoryPath,
+        },
+      );
+      // Fall through to normal tool-permission check.
     } else {
-      let extDirDecision: PermissionPromptDecision | null = null;
-      const extDirMessage = formatExternalDirectoryAskPrompt(
-        toolName,
-        externalDirectoryPath,
-        ctx.cwd,
+      const extCheck = deps.runtime.permissionManager.checkPermission(
+        "external_directory",
+        { path: normalizedExtPath },
         agentName ?? undefined,
+        deps.runtime.sessionRules.getRuleset(),
       );
-      const extDirGate = await applyPermissionGate({
-        state: extCheck.state,
-        canConfirm: deps.canRequestPermissionConfirmation(ctx),
-        promptForApproval: async () => {
-          const decision = await deps.promptPermission(ctx, {
-            requestId: (event as { toolCallId: string }).toolCallId,
-            source: "tool_call",
-            agentName,
-            message: extDirMessage,
-            toolCallId: (event as { toolCallId: string }).toolCallId,
-            toolName,
-            path: externalDirectoryPath,
-          });
-          extDirDecision = decision;
-          return decision;
-        },
-        writeLog: deps.runtime.writeReviewLog,
-        logContext: {
+
+      if (extCheck.source === "session") {
+        deps.runtime.writeReviewLog("permission_request.session_approved", {
           source: "tool_call",
           toolCallId: (event as { toolCallId: string }).toolCallId,
           toolName,
           agentName,
           path: externalDirectoryPath,
-          message: extDirMessage,
-        },
-        messages: {
-          denyReason: formatExternalDirectoryDenyReason(
+          resolution: "session_approved",
+          sessionApprovalPattern: extCheck.matchedPattern,
+        });
+        // Fall through to normal permission check
+      } else {
+        let extDirDecision: PermissionPromptDecision | null = null;
+        const extDirMessage = formatExternalDirectoryAskPrompt(
+          toolName,
+          externalDirectoryPath,
+          ctx.cwd,
+          agentName ?? undefined,
+        );
+        const extDirGate = await applyPermissionGate({
+          state: extCheck.state,
+          canConfirm: deps.canRequestPermissionConfirmation(ctx),
+          promptForApproval: async () => {
+            const decision = await deps.promptPermission(ctx, {
+              requestId: (event as { toolCallId: string }).toolCallId,
+              source: "tool_call",
+              agentName,
+              message: extDirMessage,
+              toolCallId: (event as { toolCallId: string }).toolCallId,
+              toolName,
+              path: externalDirectoryPath,
+            });
+            extDirDecision = decision;
+            return decision;
+          },
+          writeLog: deps.runtime.writeReviewLog,
+          logContext: {
+            source: "tool_call",
+            toolCallId: (event as { toolCallId: string }).toolCallId,
             toolName,
-            externalDirectoryPath,
-            ctx.cwd,
-            agentName ?? undefined,
-          ),
-          unavailableReason: `Accessing '${externalDirectoryPath}' outside the working directory requires approval, but no interactive UI is available.`,
-          userDeniedReason: (decision) =>
-            formatExternalDirectoryUserDeniedReason(
+            agentName,
+            path: externalDirectoryPath,
+            message: extDirMessage,
+          },
+          messages: {
+            denyReason: formatExternalDirectoryDenyReason(
               toolName,
               externalDirectoryPath,
-              decision.denialReason,
+              ctx.cwd,
+              agentName ?? undefined,
             ),
-        },
-      });
-      if (extDirGate.action === "block") {
-        return { block: true, reason: extDirGate.reason };
-      }
+            unavailableReason: `Accessing '${externalDirectoryPath}' outside the working directory requires approval, but no interactive UI is available.`,
+            userDeniedReason: (decision) =>
+              formatExternalDirectoryUserDeniedReason(
+                toolName,
+                externalDirectoryPath,
+                decision.denialReason,
+              ),
+          },
+        });
+        if (extDirGate.action === "block") {
+          return { block: true, reason: extDirGate.reason };
+        }
 
-      if (extDirDecision?.state === "approved_for_session") {
-        const pattern = deriveApprovalPattern(normalizedExtPath);
-        deps.runtime.sessionRules.approve("external_directory", pattern);
+        if (extDirDecision?.state === "approved_for_session") {
+          const pattern = deriveApprovalPattern(normalizedExtPath);
+          deps.runtime.sessionRules.approve("external_directory", pattern);
+        }
       }
-    }
+    } // end else (not Pi infrastructure read)
     // Fall through to normal permission check
   }
 

package/src/runtime.ts

@@ -34,6 +34,7 @@ import {
   normalizePermissionSystemConfig,
   type PermissionSystemExtensionConfig,
 } from "./extension-config";
+import { discoverGlobalNodeModulesRoot } from "./external-directory";
 import {
   type PermissionForwardingDeps,
   processForwardedPermissionRequests,
@@ -64,6 +65,14 @@ export interface ExtensionRuntime {
   readonly subagentSessionsDir: string;
   readonly forwardingDir: string;
   readonly globalLogsDir: string;
+  /**
+   * Static Pi infrastructure directories used for external-directory
+   * read auto-allow. Computed once at construction from `agentDir` and
+   * `discoverGlobalNodeModulesRoot()`. Config-based extras
+   * (`piInfrastructureReadPaths`) are read from `runtime.config` at
+   * call time in the handler so they pick up config reloads.
+   */
+  readonly piInfrastructureDirs: string[];
 
   // ── Mutable state ──────────────────────────────────────────────────────
   config: PermissionSystemExtensionConfig;
@@ -341,6 +350,13 @@ export function createExtensionRuntime(options?: {
   const forwardingDir = join(sessionsDir, "permission-forwarding");
   const globalLogsDir = getGlobalLogsDir(agentDir);
 
+  const globalNodeModulesRoot = discoverGlobalNodeModulesRoot();
+  const piInfrastructureDirs: string[] = [
+    agentDir,
+    join(agentDir, "git"),
+    ...(globalNodeModulesRoot ? [globalNodeModulesRoot] : []),
+  ];
+
   // Build a plain-object runtime first so the logger's `getConfig` closure
   // can reference `runtime.config` directly (always reads current value).
   const runtime: ExtensionRuntime = {
@@ -349,6 +365,7 @@ export function createExtensionRuntime(options?: {
     subagentSessionsDir,
     forwardingDir,
     globalLogsDir,
+    piInfrastructureDirs,
     config: { ...DEFAULT_EXTENSION_CONFIG },
     runtimeContext: null,
     permissionManager: createPermissionManagerForCwd(agentDir, undefined),

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

@@ -544,6 +544,56 @@ describe("extractExternalPathsFromBashCommand", () => {
       expect(etcHostsCount).toBe(1);
     });
   });
+
+  describe("regex patterns are not mistaken for paths", () => {
+    test("grep -v with //.*pattern is not flagged", async () => {
+      const result = await extractExternalPathsFromBashCommand(
+        'grep -n "glob" src/foo.ts 2>/dev/null | grep -v "//.*glob\\|globalConfig" | head -30',
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+
+    test("grep -v with //.*pattern without backslash-pipe is not flagged", async () => {
+      const result = await extractExternalPathsFromBashCommand(
+        'grep -v "//.*foo" file.txt',
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+
+    test("grep with backslash-pipe alternation is not flagged", async () => {
+      const result = await extractExternalPathsFromBashCommand(
+        'grep "foo\\|bar\\|baz" src/file.ts',
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+
+    test("grep -E with ^/ anchored regex is not flagged", async () => {
+      const result = await extractExternalPathsFromBashCommand(
+        'grep -E "^/usr/bin" file.txt',
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+
+    test("sed with regex containing slashes is not flagged", async () => {
+      const result = await extractExternalPathsFromBashCommand(
+        'sed "s/foo.*/bar/g" file.txt',
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+
+    test("real external paths are still detected alongside regex args", async () => {
+      const result = await extractExternalPathsFromBashCommand(
+        'grep -v "//.*pattern" /etc/hosts',
+        cwd,
+      );
+      expect(result).toContain("/etc/hosts");
+    });
+  });
 });
 
 describe("formatBashExternalDirectoryAskPrompt", () => {

package/tests/handlers/tool-call.test.ts

@@ -64,6 +64,7 @@ function makeRuntime(
     subagentSessionsDir: "/test/agent/subagent-sessions",
     forwardingDir: "/test/agent/sessions/permission-forwarding",
     globalLogsDir: "/test/agent/extensions/pi-permission-system/logs",
+    piInfrastructureDirs: ["/test/agent", "/test/agent/git"],
     config: { debugLog: false, permissionReviewLog: true, yoloMode: false },
     runtimeContext: null,
     permissionManager: {
@@ -395,6 +396,152 @@ describe("handleToolCall — external-directory gate", () => {
   });
 });
 
+// ── Pi infrastructure read bypass ───────────────────────────────────────────
+
+describe("handleToolCall — Pi infrastructure read bypass", () => {
+  const infraPath = "/test/agent/git/some-package/SKILL.md";
+
+  it("skips external-directory gate for read tool targeting an infra dir", async () => {
+    const deps = makeDeps({
+      runtime: makeRuntime({
+        permissionManager: {
+          checkPermission: vi
+            .fn()
+            .mockReturnValue(makePermissionResult("allow")),
+        } as unknown as ExtensionRuntime["permissionManager"],
+      }),
+      getAllTools: vi.fn().mockReturnValue([{ name: "read" }]),
+    });
+    const event = {
+      type: "tool_call",
+      toolCallId: "tc-infra-read",
+      name: "read",
+      input: { path: infraPath },
+    };
+    const result = await handleToolCall(deps, event, makeCtx());
+    expect(result).toEqual({});
+    // external_directory permission check must NOT have been called.
+    const checkPermission = deps.runtime.permissionManager
+      .checkPermission as ReturnType<typeof vi.fn>;
+    const calls = checkPermission.mock.calls as Array<[string, ...unknown[]]>;
+    const extDirCalls = calls.filter(
+      ([surface]) => surface === "external_directory",
+    );
+    expect(extDirCalls).toHaveLength(0);
+  });
+
+  it("does NOT skip gate for write tool targeting an infra dir", async () => {
+    const deps = makeDeps({
+      runtime: makeRuntime({
+        permissionManager: {
+          checkPermission: vi
+            .fn()
+            .mockReturnValue(makePermissionResult("deny")),
+        } as unknown as ExtensionRuntime["permissionManager"],
+      }),
+      getAllTools: vi.fn().mockReturnValue([{ name: "write" }]),
+    });
+    const event = {
+      type: "tool_call",
+      toolCallId: "tc-infra-write",
+      name: "write",
+      input: { path: infraPath },
+    };
+    const result = await handleToolCall(deps, event, makeCtx());
+    expect(result).toMatchObject({ block: true });
+    const checkPermission = deps.runtime.permissionManager
+      .checkPermission as ReturnType<typeof vi.fn>;
+    const calls = checkPermission.mock.calls as Array<[string, ...unknown[]]>;
+    const extDirCalls = calls.filter(
+      ([surface]) => surface === "external_directory",
+    );
+    expect(extDirCalls.length).toBeGreaterThan(0);
+  });
+
+  it("does NOT skip gate for read tool targeting a non-infra external path", async () => {
+    const deps = makeDeps({
+      runtime: makeRuntime({
+        permissionManager: {
+          checkPermission: vi
+            .fn()
+            .mockReturnValue(makePermissionResult("deny")),
+        } as unknown as ExtensionRuntime["permissionManager"],
+      }),
+      getAllTools: vi.fn().mockReturnValue([{ name: "read" }]),
+    });
+    const event = {
+      type: "tool_call",
+      toolCallId: "tc-non-infra",
+      name: "read",
+      input: { path: "/etc/passwd" },
+    };
+    const result = await handleToolCall(deps, event, makeCtx());
+    expect(result).toMatchObject({ block: true });
+    const checkPermission = deps.runtime.permissionManager
+      .checkPermission as ReturnType<typeof vi.fn>;
+    const calls = checkPermission.mock.calls as Array<[string, ...unknown[]]>;
+    const extDirCalls = calls.filter(
+      ([surface]) => surface === "external_directory",
+    );
+    expect(extDirCalls.length).toBeGreaterThan(0);
+  });
+
+  it("writes a review log entry when bypassing the gate", async () => {
+    const writeReviewLog = vi.fn();
+    const deps = makeDeps({
+      runtime: makeRuntime({ writeReviewLog }),
+      getAllTools: vi.fn().mockReturnValue([{ name: "read" }]),
+    });
+    const event = {
+      type: "tool_call",
+      toolCallId: "tc-infra-log",
+      name: "read",
+      input: { path: infraPath },
+    };
+    await handleToolCall(deps, event, makeCtx());
+    expect(writeReviewLog).toHaveBeenCalledWith(
+      "permission_request.infrastructure_auto_allowed",
+      expect.objectContaining({ toolName: "read", path: infraPath }),
+    );
+  });
+
+  it("respects config piInfrastructureReadPaths for bypass", async () => {
+    const customInfraPath = "/custom/infra/packages/SKILL.md";
+    const deps = makeDeps({
+      runtime: makeRuntime({
+        piInfrastructureDirs: [],
+        config: {
+          debugLog: false,
+          permissionReviewLog: true,
+          yoloMode: false,
+          piInfrastructureReadPaths: ["/custom/infra/packages"],
+        },
+        permissionManager: {
+          checkPermission: vi
+            .fn()
+            .mockReturnValue(makePermissionResult("allow")),
+        } as unknown as ExtensionRuntime["permissionManager"],
+      }),
+      getAllTools: vi.fn().mockReturnValue([{ name: "read" }]),
+    });
+    const event = {
+      type: "tool_call",
+      toolCallId: "tc-config-infra",
+      name: "read",
+      input: { path: customInfraPath },
+    };
+    const result = await handleToolCall(deps, event, makeCtx());
+    expect(result).toEqual({});
+    const checkPermission = deps.runtime.permissionManager
+      .checkPermission as ReturnType<typeof vi.fn>;
+    const calls = checkPermission.mock.calls as Array<[string, ...unknown[]]>;
+    const extDirCalls = calls.filter(
+      ([surface]) => surface === "external_directory",
+    );
+    expect(extDirCalls).toHaveLength(0);
+  });
+});
+
 // ── bash external-directory gate ──────────────────────────────────────────
 
 describe("handleToolCall — bash external-directory gate", () => {

package/tests/pi-infrastructure-read.test.ts

@@ -0,0 +1,245 @@
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+
+import {
+  discoverGlobalNodeModulesRoot,
+  isPiInfrastructureRead,
+} from "../src/external-directory";
+
+// ── discoverGlobalNodeModulesRoot ──────────────────────────────────────────
+
+describe("discoverGlobalNodeModulesRoot", () => {
+  test("returns the node_modules dir when the file is inside one", () => {
+    const url =
+      "file:///opt/homebrew/lib/node_modules/pi-permission-system/dist/external-directory.js";
+    expect(discoverGlobalNodeModulesRoot(url)).toBe(
+      "/opt/homebrew/lib/node_modules",
+    );
+  });
+
+  test("returns node_modules for a deeply nested file", () => {
+    const url =
+      "file:///home/user/.nvm/versions/node/v20/lib/node_modules/pi-permission-system/src/external-directory.js";
+    expect(discoverGlobalNodeModulesRoot(url)).toBe(
+      "/home/user/.nvm/versions/node/v20/lib/node_modules",
+    );
+  });
+
+  test("returns node_modules for a bun global install path", () => {
+    const url =
+      "file:///home/user/.bun/install/global/node_modules/pi-permission-system/dist/external-directory.js";
+    expect(discoverGlobalNodeModulesRoot(url)).toBe(
+      "/home/user/.bun/install/global/node_modules",
+    );
+  });
+
+  test("returns the innermost (closest-to-file) node_modules ancestor", () => {
+    // The walk-up algorithm stops at the first node_modules dir it encounters,
+    // which is the innermost one when the file is inside a nested install.
+    // In practice this never happens for a real global install — the extension
+    // is always directly at <global_root>/node_modules/pi-permission-system/…
+    const url =
+      "file:///opt/lib/node_modules/some-pkg/node_modules/pi-permission-system/dist/index.js";
+    expect(discoverGlobalNodeModulesRoot(url)).toBe(
+      "/opt/lib/node_modules/some-pkg/node_modules",
+    );
+  });
+
+  test("returns null when the file is not inside any node_modules directory", () => {
+    const url =
+      "file:///home/user/development/pi-permission-system/dist/external-directory.js";
+    expect(discoverGlobalNodeModulesRoot(url)).toBeNull();
+  });
+
+  test("returns null for a root-level file", () => {
+    const url = "file:///external-directory.js";
+    expect(discoverGlobalNodeModulesRoot(url)).toBeNull();
+  });
+
+  test("returns null for an invalid URL", () => {
+    expect(discoverGlobalNodeModulesRoot("not-a-url")).toBeNull();
+  });
+
+  test("works with the real import.meta.url of this extension (smoke test)", () => {
+    // The extension IS installed inside a node_modules tree when running in CI
+    // or global install. In a local dev checkout the result may be null — that's
+    // the documented graceful-degradation path.
+    const result = discoverGlobalNodeModulesRoot();
+    expect(result === null || result.endsWith("node_modules")).toBe(true);
+  });
+
+  test("the discovered path includes the pi-permission-system package directory", () => {
+    const url =
+      "file:///opt/homebrew/lib/node_modules/pi-permission-system/dist/external-directory.js";
+    const root = discoverGlobalNodeModulesRoot(url);
+    expect(root).not.toBeNull();
+    expect(join(root!, "pi-permission-system")).toBe(
+      "/opt/homebrew/lib/node_modules/pi-permission-system",
+    );
+  });
+});
+
+// ── isPiInfrastructureRead ─────────────────────────────────────────────────
+
+const INFRA_DIRS = [
+  "/home/user/.pi/agent",
+  "/home/user/.pi/agent/git",
+  "/opt/homebrew/lib/node_modules",
+];
+const CWD = "/home/user/project";
+
+describe("isPiInfrastructureRead", () => {
+  // ── read tools allowed for infra paths ──────────────────────────────────
+
+  test("allows 'read' tool for a file inside agentDir", () => {
+    expect(
+      isPiInfrastructureRead(
+        "read",
+        "/home/user/.pi/agent/extensions/pi-permission-system/config.json",
+        INFRA_DIRS,
+        CWD,
+      ),
+    ).toBe(true);
+  });
+
+  test("allows 'find' tool for a path inside node_modules infra dir", () => {
+    expect(
+      isPiInfrastructureRead(
+        "find",
+        "/opt/homebrew/lib/node_modules/pi-ask-user/skills",
+        INFRA_DIRS,
+        CWD,
+      ),
+    ).toBe(true);
+  });
+
+  test("allows 'grep' tool for a path inside agentDir/git", () => {
+    expect(
+      isPiInfrastructureRead(
+        "grep",
+        "/home/user/.pi/agent/git/some-package/README.md",
+        INFRA_DIRS,
+        CWD,
+      ),
+    ).toBe(true);
+  });
+
+  test("allows 'ls' tool for a path inside node_modules infra dir", () => {
+    expect(
+      isPiInfrastructureRead(
+        "ls",
+        "/opt/homebrew/lib/node_modules/pi-permission-system",
+        INFRA_DIRS,
+        CWD,
+      ),
+    ).toBe(true);
+  });
+
+  // ── write tools never allowed even for infra paths ───────────────────────
+
+  test("blocks 'write' tool for a file inside agentDir", () => {
+    expect(
+      isPiInfrastructureRead(
+        "write",
+        "/home/user/.pi/agent/extensions/pi-permission-system/config.json",
+        INFRA_DIRS,
+        CWD,
+      ),
+    ).toBe(false);
+  });
+
+  test("blocks 'edit' tool for a file inside node_modules", () => {
+    expect(
+      isPiInfrastructureRead(
+        "edit",
+        "/opt/homebrew/lib/node_modules/pi-ask-user/skills/ask-user/SKILL.md",
+        INFRA_DIRS,
+        CWD,
+      ),
+    ).toBe(false);
+  });
+
+  test("blocks 'bash' tool regardless of path", () => {
+    expect(
+      isPiInfrastructureRead(
+        "bash",
+        "/opt/homebrew/lib/node_modules/pi-ask-user/SKILL.md",
+        INFRA_DIRS,
+        CWD,
+      ),
+    ).toBe(false);
+  });
+
+  // ── non-infra paths not allowed ──────────────────────────────────────────
+
+  test("does not allow 'read' for a path outside all infra dirs", () => {
+    expect(isPiInfrastructureRead("read", "/etc/passwd", INFRA_DIRS, CWD)).toBe(
+      false,
+    );
+  });
+
+  test("does not allow 'read' for a path only partially matching an infra dir prefix", () => {
+    // /home/user/.pi/agent-other should not match /home/user/.pi/agent
+    expect(
+      isPiInfrastructureRead(
+        "read",
+        "/home/user/.pi/agent-other/config.json",
+        INFRA_DIRS,
+        CWD,
+      ),
+    ).toBe(false);
+  });
+
+  // ── project-local Pi packages (.pi/npm, .pi/git) ─────────────────────────
+
+  test("allows 'read' for a path inside project-local .pi/npm/", () => {
+    expect(
+      isPiInfrastructureRead(
+        "read",
+        `${CWD}/.pi/npm/node_modules/some-skill/SKILL.md`,
+        INFRA_DIRS,
+        CWD,
+      ),
+    ).toBe(true);
+  });
+
+  test("allows 'read' for a path inside project-local .pi/git/", () => {
+    expect(
+      isPiInfrastructureRead(
+        "read",
+        `${CWD}/.pi/git/github.com/org/skill-repo/SKILL.md`,
+        INFRA_DIRS,
+        CWD,
+      ),
+    ).toBe(true);
+  });
+
+  test("blocks 'write' for a path inside project-local .pi/npm/", () => {
+    expect(
+      isPiInfrastructureRead(
+        "write",
+        `${CWD}/.pi/npm/node_modules/some-skill/SKILL.md`,
+        INFRA_DIRS,
+        CWD,
+      ),
+    ).toBe(false);
+  });
+
+  // ── empty / edge cases ───────────────────────────────────────────────────
+
+  test("returns false when infrastructureDirs is empty and path is not project-local", () => {
+    expect(isPiInfrastructureRead("read", "/etc/passwd", [], CWD)).toBe(false);
+  });
+
+  test("returns false when infrastructureDirs is empty but path IS project-local .pi/npm", () => {
+    // Project-local paths are checked separately from the dirs array.
+    expect(
+      isPiInfrastructureRead(
+        "read",
+        `${CWD}/.pi/npm/node_modules/x/SKILL.md`,
+        [],
+        CWD,
+      ),
+    ).toBe(true);
+  });
+});

package/tests/runtime.test.ts

@@ -11,6 +11,7 @@ const {
   mockGetActiveAgentName,
   mockGetActiveAgentNameFromSystemPrompt,
   mockBuildResolvedConfigLogEntry,
+  mockDiscoverGlobalNodeModulesRoot,
 } = vi.hoisted(() => ({
   mockLoggerDebug:
     vi.fn<
@@ -27,6 +28,7 @@ const {
   mockGetActiveAgentNameFromSystemPrompt:
     vi.fn<(prompt?: string) => string | null>(),
   mockBuildResolvedConfigLogEntry: vi.fn(),
+  mockDiscoverGlobalNodeModulesRoot: vi.fn<() => string | null>(),
 }));
 
 vi.mock("../src/logging", () => ({
@@ -65,6 +67,10 @@ vi.mock("../src/subagent-context", () => ({
   isSubagentExecutionContext: vi.fn().mockReturnValue(false),
 }));
 
+vi.mock("../src/external-directory", () => ({
+  discoverGlobalNodeModulesRoot: mockDiscoverGlobalNodeModulesRoot,
+}));
+
 vi.mock("../src/session-rules", () => ({
   SessionRules: vi.fn(),
   deriveApprovalPattern: vi.fn(),
@@ -99,6 +105,10 @@ describe("createExtensionRuntime", () => {
       debug: mockLoggerDebug,
       review: mockLoggerReview,
     });
+    mockDiscoverGlobalNodeModulesRoot.mockReset();
+    mockDiscoverGlobalNodeModulesRoot.mockReturnValue(
+      "/mock/global/node_modules",
+    );
   });
 
   // ── Path derivation ──────────────────────────────────────────────────────
@@ -130,6 +140,41 @@ describe("createExtensionRuntime", () => {
     expect(runtime.globalLogsDir).toBe(getGlobalLogsDir("/test/agent"));
   });
 
+  // ── piInfrastructureDirs ─────────────────────────────────────────────────
+
+  it("includes agentDir in piInfrastructureDirs", () => {
+    const runtime = createExtensionRuntime({ agentDir: "/test/agent" });
+    expect(runtime.piInfrastructureDirs).toContain("/test/agent");
+  });
+
+  it("includes agentDir/git in piInfrastructureDirs", () => {
+    const runtime = createExtensionRuntime({ agentDir: "/test/agent" });
+    expect(runtime.piInfrastructureDirs).toContain("/test/agent/git");
+  });
+
+  it("includes discovered global node_modules root in piInfrastructureDirs", () => {
+    const runtime = createExtensionRuntime({ agentDir: "/test/agent" });
+    expect(runtime.piInfrastructureDirs).toContain("/mock/global/node_modules");
+  });
+
+  it("excludes null when discoverGlobalNodeModulesRoot returns null", () => {
+    mockDiscoverGlobalNodeModulesRoot.mockReturnValue(null);
+    const runtime = createExtensionRuntime({ agentDir: "/test/agent" });
+    for (const dir of runtime.piInfrastructureDirs) {
+      expect(dir).not.toBeNull();
+      expect(typeof dir).toBe("string");
+    }
+  });
+
+  it("omits global node_modules from piInfrastructureDirs when discovery returns null", () => {
+    mockDiscoverGlobalNodeModulesRoot.mockReturnValue(null);
+    const runtime = createExtensionRuntime({ agentDir: "/test/agent" });
+    // Only agentDir and agentDir/git should be present.
+    expect(runtime.piInfrastructureDirs).toHaveLength(2);
+    expect(runtime.piInfrastructureDirs).toContain("/test/agent");
+    expect(runtime.piInfrastructureDirs).toContain("/test/agent/git");
+  });
+
   // ── Default mutable state ────────────────────────────────────────────────
 
   it("initializes config to DEFAULT_EXTENSION_CONFIG", () => {