@gotgenes/pi-permission-system 5.6.2 → 5.7.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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).
 
+## [5.7.0](https://github.com/gotgenes/pi-permission-system/compare/v5.6.3...v5.7.0) (2026-05-08)
+
+
+### Features
+
+* extract ExtensionPaths value object ([#126](https://github.com/gotgenes/pi-permission-system/issues/126)) ([85bc347](https://github.com/gotgenes/pi-permission-system/commit/85bc347d3ed487210ffbed4c1c53616b5cf0d978))
+
+
+### Documentation
+
+* add handler decomposition plan ([#126](https://github.com/gotgenes/pi-permission-system/issues/126), [#127](https://github.com/gotgenes/pi-permission-system/issues/127), [#128](https://github.com/gotgenes/pi-permission-system/issues/128), [#129](https://github.com/gotgenes/pi-permission-system/issues/129), [#130](https://github.com/gotgenes/pi-permission-system/issues/130)) ([5a116a6](https://github.com/gotgenes/pi-permission-system/commit/5a116a6cf2f6ef29f5e6550821bb26b6e1c3a90f))
+* add structural design heuristics, design-review skill, and plan-issue hook ([d8e3233](https://github.com/gotgenes/pi-permission-system/commit/d8e32330baa25fa5a5abaf75f8e442ce650fe5a9))
+* extract code-style, testing, and markdown-conventions skills from AGENTS.md ([9d5ba7a](https://github.com/gotgenes/pi-permission-system/commit/9d5ba7a4a4a7a9e9fbdfe869fb42840238351b81))
+* plan ExtensionPaths value object extraction ([#126](https://github.com/gotgenes/pi-permission-system/issues/126)) ([d76e6cc](https://github.com/gotgenes/pi-permission-system/commit/d76e6cc255dc124a7a914e8d178113e5b7c8bddd))
+* rename target-architecture to architecture, strip progress indicators ([9776550](https://github.com/gotgenes/pi-permission-system/commit/9776550351f3b59f96bdad614cc5129a7be52a51))
+* **retro:** add retro notes for issue [#110](https://github.com/gotgenes/pi-permission-system/issues/110) ([5597de3](https://github.com/gotgenes/pi-permission-system/commit/5597de3c9c64c3d672a1fc77ba7910e952545824))
+
+## [5.6.3](https://github.com/gotgenes/pi-permission-system/compare/v5.6.2...v5.6.3) (2026-05-07)
+
+
+### Documentation
+
+* **retro:** add retro notes for issue [#109](https://github.com/gotgenes/pi-permission-system/issues/109) ([7d46cf4](https://github.com/gotgenes/pi-permission-system/commit/7d46cf4576d13d1d348355de88fb3dda6297be5a))
+* update architecture for external-directory split ([#110](https://github.com/gotgenes/pi-permission-system/issues/110)) ([2e86fe7](https://github.com/gotgenes/pi-permission-system/commit/2e86fe79bc5de8076f775949824adadd4d366d7c))
+* update plan for [#110](https://github.com/gotgenes/pi-permission-system/issues/110) after [#109](https://github.com/gotgenes/pi-permission-system/issues/109) landed ([3541d57](https://github.com/gotgenes/pi-permission-system/commit/3541d5739385b77ea8b21752595efd5cb75a6789))
+
 ## [5.6.2](https://github.com/gotgenes/pi-permission-system/compare/v5.6.1...v5.6.2) (2026-05-07)
 
 

package/package.json

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

package/src/extension-paths.ts

@@ -0,0 +1,55 @@
+import { join } from "node:path";
+import { getGlobalLogsDir } from "./config-paths";
+import { discoverGlobalNodeModulesRoot } from "./node-modules-discovery";
+
+/**
+ * Immutable path constants derived from `agentDir` at construction time.
+ *
+ * Computed once at startup in `computeExtensionPaths()` and embedded into
+ * `ExtensionRuntime`. Later refactorings (#129 PermissionSession, #130
+ * handler classes) consume this as a single dep instead of individual fields.
+ */
+export interface ExtensionPaths {
+  readonly agentDir: string;
+  readonly sessionsDir: string;
+  readonly subagentSessionsDir: string;
+  readonly forwardingDir: string;
+  readonly globalLogsDir: string;
+  /**
+   * Static Pi infrastructure directories used for external-directory
+   * read auto-allow. Computed once 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: readonly string[];
+}
+
+/**
+ * Compute all immutable path constants from `agentDir`.
+ *
+ * Calls `discoverGlobalNodeModulesRoot()` internally so the result is
+ * self-contained. Call this once at extension startup, not at module scope.
+ */
+export function computeExtensionPaths(agentDir: string): ExtensionPaths {
+  const sessionsDir = join(agentDir, "sessions");
+  const subagentSessionsDir = join(agentDir, "subagent-sessions");
+  const forwardingDir = join(sessionsDir, "permission-forwarding");
+  const globalLogsDir = getGlobalLogsDir(agentDir);
+
+  const globalNodeModulesRoot = discoverGlobalNodeModulesRoot();
+  const piInfrastructureDirs: string[] = [
+    agentDir,
+    join(agentDir, "git"),
+    ...(globalNodeModulesRoot ? [globalNodeModulesRoot] : []),
+  ];
+
+  return {
+    agentDir,
+    sessionsDir,
+    subagentSessionsDir,
+    forwardingDir,
+    globalLogsDir,
+    piInfrastructureDirs,
+  };
+}

package/src/handlers/gates/bash-external-directory.ts

@@ -1,14 +1,14 @@
 import { getNonEmptyString, toRecord } from "../../common";
-import {
-  extractExternalPathsFromBashCommand,
-  formatBashExternalDirectoryAskPrompt,
-  formatBashExternalDirectoryDenyReason,
-  formatExternalDirectoryHardStopHint,
-} from "../../external-directory";
 import type { Rule } from "../../rule";
 import { deriveApprovalPattern } from "../../session-rules";
 import type { PermissionCheckResult } from "../../types";
+import { extractExternalPathsFromBashCommand } from "./bash-path-extractor";
 import type { GateResult } from "./descriptor";
+import {
+  formatBashExternalDirectoryAskPrompt,
+  formatBashExternalDirectoryDenyReason,
+  formatExternalDirectoryHardStopHint,
+} from "./external-directory-messages";
 import type { ToolCallContext } from "./types";
 
 /** Function type for checkPermission used by the descriptor factory. */

package/src/{external-directory.ts → handlers/gates/bash-path-extractor.ts}

@@ -1,255 +1,10 @@
-import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
-import { basename, dirname, join, normalize, resolve, sep } from "node:path";
-import { fileURLToPath } from "node:url";
-
-import { getNonEmptyString, toRecord } from "./common";
-
-export {
-  isPathWithinDirectory,
-  normalizePathForComparison,
-} from "./path-utils";
+import { basename } from "node:path";
 
 import {
-  isPathWithinDirectory,
+  isPathOutsideWorkingDirectory,
   normalizePathForComparison,
-} from "./path-utils";
-
-/**
- * Walk up the directory tree from the given file URL until a directory
- * literally named `node_modules` is found.
- *
- * Returns the `node_modules` path, or `null` if the URL cannot be parsed or
- * no `node_modules` ancestor exists.
- */
-function walkUpToNodeModules(fromUrl: string): string | null {
-  try {
-    const thisFile = fileURLToPath(fromUrl);
-    let dir = dirname(thisFile);
-    while (dir !== dirname(dir)) {
-      if (basename(dir) === "node_modules") {
-        return dir;
-      }
-      dir = dirname(dir);
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Run `npm root -g` synchronously and return the trimmed output, or `null` on
- * any failure (non-zero exit, ENOENT, timeout, non-existent path).
- *
- * Only called when the walk-up-from-self strategy fails (i.e. the extension is
- * running from a local development checkout, not a global install).
- */
-function discoverGlobalNodeModulesViaSubprocess(): string | null {
-  try {
-    const result = spawnSync("npm", ["root", "-g"], {
-      encoding: "utf-8",
-      timeout: 5000,
-      stdio: ["ignore", "pipe", "ignore"],
-    });
-    const root = result.stdout?.trim();
-    if (result.status === 0 && root && existsSync(root)) {
-      return root;
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Discover the global node_modules root.
- *
- * Strategy 1 (zero-cost, covers all global installs): walk up from
- * `fromUrl` (defaults to this module's own `import.meta.url`) looking for a
- * directory named `node_modules`. This works whenever the extension is
- * installed inside a `node_modules` tree.
- *
- * Strategy 2 (subprocess fallback, dev checkout only): when Strategy 1 fails
- * because the extension is running from a local development checkout with no
- * `node_modules` ancestor, run `npm root -g` to discover the global root.
- * Pi installs skills and extensions via `npm` by default, so `npm root -g`
- * returns the correct root regardless of the user's own project package
- * manager.
- *
- * Returns `null` when both strategies fail — callers must degrade gracefully.
- */
-export function discoverGlobalNodeModulesRoot(
-  fromUrl = import.meta.url,
-): string | null {
-  const fromSelf = walkUpToNodeModules(fromUrl);
-  if (fromSelf) return fromSelf;
-  return discoverGlobalNodeModulesViaSubprocess();
-}
-
-/**
- * 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.
- */
-export const SAFE_SYSTEM_PATHS: ReadonlySet<string> = new Set([
-  "/dev/null",
-  "/dev/stdin",
-  "/dev/stdout",
-  "/dev/stderr",
-]);
-
-/**
- * Returns true if the given normalized path is a safe OS device file
- * that should never trigger external-directory checks.
- */
-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",
-  "edit",
-  "find",
-  "grep",
-  "ls",
-]);
-
-export function getPathBearingToolPath(
-  toolName: string,
-  input: unknown,
-): string | null {
-  if (!PATH_BEARING_TOOLS.has(toolName)) {
-    return null;
-  }
-
-  return getNonEmptyString(toRecord(input).path);
-}
-
-export function isPathOutsideWorkingDirectory(
-  pathValue: string,
-  cwd: string,
-): boolean {
-  const normalizedCwd = normalizePathForComparison(cwd, cwd);
-  const normalizedPath = normalizePathForComparison(pathValue, cwd);
-  if (!normalizedCwd || !normalizedPath) {
-    return false;
-  }
-  if (isSafeSystemPath(normalizedPath)) {
-    return false;
-  }
-  return !isPathWithinDirectory(normalizedPath, normalizedCwd);
-}
-
-export 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.";
-}
-
-export 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?`;
-}
-
-export 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()}`;
-}
-
-export 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()}`;
-}
-
-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()}`;
-}
+} from "../../path-utils";
 
 // ── tree-sitter-bash lazy parser ───────────────────────────────────────────
 

package/src/handlers/gates/external-directory-messages.ts

@@ -0,0 +1,54 @@
+export 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.";
+}
+
+export 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?`;
+}
+
+export 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()}`;
+}
+
+export 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()}`;
+}
+
+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()}`;
+}

package/src/handlers/gates/external-directory.ts

@@ -1,14 +1,16 @@
 import {
-  formatExternalDirectoryAskPrompt,
-  formatExternalDirectoryDenyReason,
-  formatExternalDirectoryUserDeniedReason,
   getPathBearingToolPath,
   isPathOutsideWorkingDirectory,
   isPiInfrastructureRead,
-} from "../../external-directory";
-import { normalizePathForComparison } from "../../path-utils";
+  normalizePathForComparison,
+} from "../../path-utils";
 import { deriveApprovalPattern } from "../../session-rules";
 import type { GateResult } from "./descriptor";
+import {
+  formatExternalDirectoryAskPrompt,
+  formatExternalDirectoryDenyReason,
+  formatExternalDirectoryUserDeniedReason,
+} from "./external-directory-messages";
 import type { ToolCallContext } from "./types";
 
 /**

package/src/handlers/gates/tool.ts

@@ -1,4 +1,4 @@
-import { PATH_BEARING_TOOLS } from "../../external-directory";
+import { PATH_BEARING_TOOLS } from "../../path-utils";
 import { suggestSessionPattern } from "../../pattern-suggest";
 import {
   formatAskPrompt,

package/src/handlers/types.ts

@@ -42,7 +42,7 @@ export interface HandlerDeps {
   writeReviewLog(event: string, details?: Record<string, unknown>): void;
 
   // ── Immutable infrastructure paths ───────────────────────────────────
-  readonly piInfrastructureDirs: string[];
+  readonly piInfrastructureDirs: readonly string[];
   /** Returns config-derived infrastructure read paths (current at call time). */
   getPiInfrastructureReadPaths(): string[];
 

package/src/node-modules-discovery.ts

@@ -0,0 +1,76 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { basename, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Walk up the directory tree from the given file URL until a directory
+ * literally named `node_modules` is found.
+ *
+ * Returns the `node_modules` path, or `null` if the URL cannot be parsed or
+ * no `node_modules` ancestor exists.
+ */
+function walkUpToNodeModules(fromUrl: string): string | null {
+  try {
+    const thisFile = fileURLToPath(fromUrl);
+    let dir = dirname(thisFile);
+    while (dir !== dirname(dir)) {
+      if (basename(dir) === "node_modules") {
+        return dir;
+      }
+      dir = dirname(dir);
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run `npm root -g` synchronously and return the trimmed output, or `null` on
+ * any failure (non-zero exit, ENOENT, timeout, non-existent path).
+ *
+ * Only called when the walk-up-from-self strategy fails (i.e. the extension is
+ * running from a local development checkout, not a global install).
+ */
+function discoverGlobalNodeModulesViaSubprocess(): string | null {
+  try {
+    const result = spawnSync("npm", ["root", "-g"], {
+      encoding: "utf-8",
+      timeout: 5000,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const root = result.stdout?.trim();
+    if (result.status === 0 && root && existsSync(root)) {
+      return root;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Discover the global node_modules root.
+ *
+ * Strategy 1 (zero-cost, covers all global installs): walk up from
+ * `fromUrl` (defaults to this module's own `import.meta.url`) looking for a
+ * directory named `node_modules`. This works whenever the extension is
+ * installed inside a `node_modules` tree.
+ *
+ * Strategy 2 (subprocess fallback, dev checkout only): when Strategy 1 fails
+ * because the extension is running from a local development checkout with no
+ * `node_modules` ancestor, run `npm root -g` to discover the global root.
+ * Pi installs skills and extensions via `npm` by default, so `npm root -g`
+ * returns the correct root regardless of the user's own project package
+ * manager.
+ *
+ * Returns `null` when both strategies fail — callers must degrade gracefully.
+ */
+export function discoverGlobalNodeModulesRoot(
+  fromUrl = import.meta.url,
+): string | null {
+  const fromSelf = walkUpToNodeModules(fromUrl);
+  if (fromSelf) return fromSelf;
+  return discoverGlobalNodeModulesViaSubprocess();
+}

package/src/path-utils.ts

@@ -1,6 +1,8 @@
 import { homedir } from "node:os";
 import { join, normalize, resolve, sep } from "node:path";
 
+import { getNonEmptyString, toRecord } from "./common";
+
 export function normalizePathForComparison(
   pathValue: string,
   cwd: string,
@@ -43,3 +45,111 @@ export function isPathWithinDirectory(
   const prefix = directory.endsWith(sep) ? directory : `${directory}${sep}`;
   return pathValue.startsWith(prefix);
 }
+
+/**
+ * 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.
+ */
+export const SAFE_SYSTEM_PATHS: ReadonlySet<string> = new Set([
+  "/dev/null",
+  "/dev/stdin",
+  "/dev/stdout",
+  "/dev/stderr",
+]);
+
+/**
+ * Returns true if the given normalized path is a safe OS device file
+ * that should never trigger external-directory checks.
+ */
+export function isSafeSystemPath(normalizedPath: string): boolean {
+  return SAFE_SYSTEM_PATHS.has(normalizedPath);
+}
+
+/**
+ * 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",
+  "edit",
+  "find",
+  "grep",
+  "ls",
+]);
+
+export function getPathBearingToolPath(
+  toolName: string,
+  input: unknown,
+): string | null {
+  if (!PATH_BEARING_TOOLS.has(toolName)) {
+    return null;
+  }
+
+  return getNonEmptyString(toRecord(input).path);
+}
+
+export function isPathOutsideWorkingDirectory(
+  pathValue: string,
+  cwd: string,
+): boolean {
+  const normalizedCwd = normalizePathForComparison(cwd, cwd);
+  const normalizedPath = normalizePathForComparison(pathValue, cwd);
+  if (!normalizedCwd || !normalizedPath) {
+    return false;
+  }
+  if (isSafeSystemPath(normalizedPath)) {
+    return false;
+  }
+  return !isPathWithinDirectory(normalizedPath, normalizedCwd);
+}
+
+/**
+ * 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;
+}