@gotgenes/pi-permission-system 38.0.2 → 39.0.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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).
 
+## [39.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v38.0.2...pi-permission-system-v39.0.0) (2026-10-03)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** **breaking:** a targeted external_directory deny now blocks a Pi infrastructure read ([5c9dc88](https://github.com/gotgenes/pi-packages/commit/5c9dc88f57a68fe87ade2da50ad613b9b9fdcb82)), closes [#955](https://github.com/gotgenes/pi-packages/issues/955)
+* **pi-permission-system:** **breaking:** the Pi infrastructure read bypass no longer covers the permission logs ([0ad3434](https://github.com/gotgenes/pi-packages/commit/0ad34344fb035211adc29317201d6f00cd8c7a76)), closes [#955](https://github.com/gotgenes/pi-packages/issues/955)
+* **pi-permission-system:** **breaking:** the Pi infrastructure read bypass covers only Pi's harness entries, not all of ~/.pi/agent ([7826794](https://github.com/gotgenes/pi-packages/commit/7826794820b0a93257597b4cd14cd36de4193e84)), closes [#955](https://github.com/gotgenes/pi-packages/issues/955)
+
+### Documentation
+
+* **pi-permission-system:** document the narrowed Pi infrastructure read bypass ([7cdfb8f](https://github.com/gotgenes/pi-packages/commit/7cdfb8fb9222bc8917aaa057cc0106d5c6806030)), closes [#955](https://github.com/gotgenes/pi-packages/issues/955)
+
 ## [38.0.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v38.0.1...pi-permission-system-v38.0.2) (2026-10-02)
 
 

package/README.md

@@ -222,23 +222,24 @@ Approve-and-steer, edit diffs, and risk explanations → a downstream package ov
 
 ## Documentation
 
-| Document                                                                                                                       | Contents                                                                                                             |
-| ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
-| [docs/configuration.md](docs/configuration.md)                                                                                 | Full policy reference, runtime knobs, per-agent overrides, recipes                                                   |
-| [docs/session-approvals.md](docs/session-approvals.md)                                                                         | Session-scoped rules, pattern suggestions, bash arity table                                                          |
-| [docs/cross-extension-api.md](docs/cross-extension-api.md)                                                                     | Cross-extension service accessor, event bus integration, prompt and decision broadcasts                              |
-| [docs/subagent-integration.md](docs/subagent-integration.md)                                                                   | The subagent adapter convention, permission forwarding, coexistence with subagent extensions                         |
-| [docs/guides/permission-frontmatter-for-subagent-extensions.md](docs/guides/permission-frontmatter-for-subagent-extensions.md) | Convention guide for subagent extension authors                                                                      |
-| [docs/opencode-compatibility.md](docs/opencode-compatibility.md)                                                               | OpenCode compatibility — shared concepts, divergences, porting guide                                                 |
-| [docs/troubleshooting.md](docs/troubleshooting.md)                                                                             | Common issues, diagnostic logging, threat model                                                                      |
-| [docs/migration/legacy-to-flat.md](docs/migration/legacy-to-flat.md)                                                           | Migration from pre-v2 config layout                                                                                  |
-| [docs/migration/strict-config-validation.md](docs/migration/strict-config-validation.md)                                       | Strict config validation (breaking) — rejected configs, and the cross-scope fail-closed clamp                        |
-| [docs/migration/0644-project-trust-gating.md](docs/migration/0644-project-trust-gating.md)                                     | Project-trust gating (breaking) — project config loads only after project trust                                      |
-| [docs/migration/0745-prompt-payload-contracts.md](docs/migration/0745-prompt-payload-contracts.md)                             | Prompt payload contracts (breaking) — the forwarded wire, the `ui_prompt` broadcast, and the deprecated preview caps |
-| [docs/migration/0746-review-log-fields.md](docs/migration/0746-review-log-fields.md)                                           | Review-log fields (breaking) — `message` replaced by request facts, and the `reviewLogFieldMaxWidth` bound           |
-| [docs/migration/0794-keyed-service-locator.md](docs/migration/0794-keyed-service-locator.md)                                   | Keyed service locator (breaking) — `getPermissionsService(sessionId)`, and the repeating ready event                 |
-| [docs/migration/0796-remove-process-root-slot.md](docs/migration/0796-remove-process-root-slot.md)                             | Process-root slot removed (breaking) — `getRootPermissionsService()` and its publish/unpublish pair are gone         |
-| [docs/migration/0810-per-pattern-approval-surfaces.md](docs/migration/0810-per-pattern-approval-surfaces.md)                   | Per-pattern approval surfaces (breaking) — `ForwardedSessionApproval.grants` replaces `surface` + `patterns`         |
+| Document                                                                                                                       | Contents                                                                                                                                    |
+| ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| [docs/configuration.md](docs/configuration.md)                                                                                 | Full policy reference, runtime knobs, per-agent overrides, recipes                                                                          |
+| [docs/session-approvals.md](docs/session-approvals.md)                                                                         | Session-scoped rules, pattern suggestions, bash arity table                                                                                 |
+| [docs/cross-extension-api.md](docs/cross-extension-api.md)                                                                     | Cross-extension service accessor, event bus integration, prompt and decision broadcasts                                                     |
+| [docs/subagent-integration.md](docs/subagent-integration.md)                                                                   | The subagent adapter convention, permission forwarding, coexistence with subagent extensions                                                |
+| [docs/guides/permission-frontmatter-for-subagent-extensions.md](docs/guides/permission-frontmatter-for-subagent-extensions.md) | Convention guide for subagent extension authors                                                                                             |
+| [docs/opencode-compatibility.md](docs/opencode-compatibility.md)                                                               | OpenCode compatibility — shared concepts, divergences, porting guide                                                                        |
+| [docs/troubleshooting.md](docs/troubleshooting.md)                                                                             | Common issues, diagnostic logging, threat model                                                                                             |
+| [docs/migration/legacy-to-flat.md](docs/migration/legacy-to-flat.md)                                                           | Migration from pre-v2 config layout                                                                                                         |
+| [docs/migration/strict-config-validation.md](docs/migration/strict-config-validation.md)                                       | Strict config validation (breaking) — rejected configs, and the cross-scope fail-closed clamp                                               |
+| [docs/migration/0644-project-trust-gating.md](docs/migration/0644-project-trust-gating.md)                                     | Project-trust gating (breaking) — project config loads only after project trust                                                             |
+| [docs/migration/0745-prompt-payload-contracts.md](docs/migration/0745-prompt-payload-contracts.md)                             | Prompt payload contracts (breaking) — the forwarded wire, the `ui_prompt` broadcast, and the deprecated preview caps                        |
+| [docs/migration/0746-review-log-fields.md](docs/migration/0746-review-log-fields.md)                                           | Review-log fields (breaking) — `message` replaced by request facts, and the `reviewLogFieldMaxWidth` bound                                  |
+| [docs/migration/0794-keyed-service-locator.md](docs/migration/0794-keyed-service-locator.md)                                   | Keyed service locator (breaking) — `getPermissionsService(sessionId)`, and the repeating ready event                                        |
+| [docs/migration/0796-remove-process-root-slot.md](docs/migration/0796-remove-process-root-slot.md)                             | Process-root slot removed (breaking) — `getRootPermissionsService()` and its publish/unpublish pair are gone                                |
+| [docs/migration/0810-per-pattern-approval-surfaces.md](docs/migration/0810-per-pattern-approval-surfaces.md)                   | Per-pattern approval surfaces (breaking) — `ForwardedSessionApproval.grants` replaces `surface` + `patterns`                                |
+| [docs/migration/0955-pi-infrastructure-read-narrowed.md](docs/migration/0955-pi-infrastructure-read-narrowed.md)               | Pi infrastructure reads narrowed (breaking): only Pi's harness entries under `~/.pi/agent/`, never the logs, and a targeted deny now blocks |
 
 ## Development
 

package/docs/configuration.md

@@ -850,15 +850,22 @@ For `external_directory`, the decision of whether a path is outside the working
 
 #### 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; falls back to `npm root -g` when running from a local development checkout)
-4. Pi's own install directory (auto-discovered via the coding-agent `getPackageDir()` API, so Pi's bundled docs and examples are readable regardless of install layout)
-5. Project-local Pi packages (`<cwd>/.pi/npm/` and `<cwd>/.pi/git/`)
-6. Any paths listed in `piInfrastructureReadPaths`
+Read-only tools (`read`, `find`, `grep`, `ls`) targeting Pi infrastructure paths are automatically allowed without triggering the gate, even when `external_directory` is `ask` or a catch-all `deny`.
+Infrastructure paths include:
+
+1. Pi's harness entries under the agent config directory (`~/.pi/agent/` or `$PI_CODING_AGENT_DIR`): the directories `agents/`, `extensions/`, `git/`, `npm/`, `prompts/`, `skills/`, and `themes/`, and the files `settings.json`, `SYSTEM.md`, `APPEND_SYSTEM.md`, and `AGENTS.md`
+2. The global `node_modules` root (auto-discovered from the extension's own install path; falls back to `npm root -g` when running from a local development checkout)
+3. Pi's own install directory (auto-discovered via the coding-agent `getPackageDir()` API, so Pi's bundled docs and examples are readable regardless of install layout)
+4. Project-local Pi packages (`<cwd>/.pi/npm/` and `<cwd>/.pi/git/`)
+5. Any paths listed in `piInfrastructureReadPaths`
+
+Everything else under the agent config directory, such as `auth.json`, `models.json`, `mcp-oauth/`, and `sessions/`, goes through the gate like any other outside path.
+This package's own logs directory (`extensions/pi-permission-system/logs/`) is never auto-allowed, even when a `piInfrastructureReadPaths` entry covers it.
+
+A deny rule on `external_directory` or `external_directory_read` whose pattern names an infrastructure path outranks the auto-allow and blocks the read.
+A catch-all `"*"` deny and the universal `permission["*"]` fallback do not, so a deny-by-default policy keeps its skill and package reads.
+Rules are last-match-wins, so write the catch-all before the targeted deny.
+See [the migration guide](migration/0955-pi-infrastructure-read-narrowed.md) for the change from earlier releases.
 
 Write tools (`write`, `edit`) to infrastructure paths are **not** auto-allowed and still go through the gate.
 

package/docs/migration/0955-pi-infrastructure-read-narrowed.md

@@ -0,0 +1,74 @@
+# Migration guide: the Pi infrastructure read bypass is narrowed
+
+Read-only tools (`read`, `find`, `grep`, `ls`) skip the `external_directory` gate for Pi infrastructure paths.
+Before this change, that bypass covered **everything** under `~/.pi/agent/` (or `$PI_CODING_AGENT_DIR`), including the credential store, and it ran before policy was consulted, so no `external_directory` rule could stop it.
+
+This is a **breaking change** in three ways, each taking effect on upgrade with no config edit.
+
+## What changes
+
+### Only Pi's harness entries stay auto-allowed
+
+The bypass now covers only these entries under `~/.pi/agent/`:
+
+- the directories `agents/`, `extensions/`, `git/`, `npm/`, `prompts/`, `skills/`, and `themes/`;
+- the files `settings.json`, `SYSTEM.md`, `APPEND_SYSTEM.md`, and `AGENTS.md`.
+
+Everything else there now goes through the `external_directory_read` gate like any other outside path.
+That includes `auth.json`, `models.json`, `mcp.json`, `mcp-oauth/`, `trust.json`, `sessions/`, `subagent-sessions/`, `bin/`, and crash logs.
+
+The global `node_modules` root, Pi's own install directory, project-local `.pi/npm/` and `.pi/git/`, and `piInfrastructureReadPaths` entries are unchanged.
+
+### This package's logs are never auto-allowed
+
+`~/.pi/agent/extensions/pi-permission-system/logs/` holds the review and debug logs, which record tool input.
+It sits inside `extensions/`, but the bypass now excludes it, even when a `piInfrastructureReadPaths` entry covers it.
+
+### A deny naming an infrastructure path now blocks
+
+Policy is resolved before the bypass.
+A deny from an `external_directory` or `external_directory_read` rule whose pattern names the path now blocks the read.
+A catch-all `"*"` deny, the universal `permission["*"]` fallback, and any `ask` still leave the bypass in place, so a deny-by-default policy keeps its skill and package reads.
+
+## Before and after
+
+Each row is a `read` of the named path under `~/.pi/agent/`.
+
+| Policy                                                                    | Path                       | Before  | After       |
+| ------------------------------------------------------------------------- | -------------------------- | ------- | ----------- |
+| `"external_directory_read": {"*": "deny"}`                                | `auth.json`                | allowed | **denied**  |
+| `"external_directory_read": {"*": "deny"}`                                | `sessions/<id>.jsonl`      | allowed | **denied**  |
+| `"external_directory_read": {"*": "ask"}`                                 | `sessions/<id>.jsonl`      | allowed | **asked**   |
+| `"external_directory_read": {"*": "deny"}`                                | `extensions/…/logs/…`      | allowed | **denied**  |
+| `"external_directory_read": {"*": "deny"}`                                | `skills/<name>/SKILL.md`   | allowed | allowed     |
+| `"external_directory_read": {"*": "deny"}`                                | `settings.json`            | allowed | allowed     |
+| `"external_directory_read": {"~/.pi/agent/git/x/SKILL.md": "deny"}`       | `git/x/SKILL.md`           | allowed | **denied**  |
+| `"external_directory": {"*": "deny"}`                                     | `git/x/SKILL.md`           | allowed | allowed     |
+
+## Restoring a read
+
+Grant the path on `external_directory_read`, where the grant is visible in your config:
+
+```jsonc
+"permission": {
+  "external_directory_read": { "~/.pi/agent/sessions/*": "allow" }
+}
+```
+
+A `piInfrastructureReadPaths` entry also restores the bypass for any path except this package's logs directory.
+For the logs, only an `external_directory_read` rule re-allows the read.
+
+## Writing a targeted deny
+
+Rules are last-match-wins, so put a catch-all first and the targeted deny after it:
+
+```jsonc
+"permission": {
+  "external_directory_read": {
+    "*": "ask",
+    "~/.pi/agent/skills/untrusted/*": "deny"
+  }
+}
+```
+
+Written the other way round, the catch-all is the matching rule, and a catch-all does not override the bypass.

package/package.json

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

package/schemas/permissions.schema.json

@@ -128,7 +128,7 @@
     },
     "piInfrastructureReadPaths": {
       "description": "Additional directories to auto-allow for reads as Pi infrastructure, bypassing the external_directory gate. Supports ~ expansion and wildcard patterns (* and ?).",
-      "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 (walks up from the extension's install path; falls back to `npm root -g` from a dev checkout), Pi's own install directory (via the coding-agent `getPackageDir()` API), `agentDir`, `agentDir/git`, and project-local `.pi/npm/` and `.pi/git/`. Add entries here for edge cases where auto-discovery is insufficient (e.g. custom `npmCommand` pointing to pnpm).\n\nSupports `~`/`$HOME` expansion. Entries may be plain directory prefixes or wildcard patterns using `*` (matches any characters, including `/`) and `?` (matches exactly one character). `**` and `*` are equivalent — both cross directory boundaries.\n\nOn Windows, matching is case-insensitive and tolerant of either path separator.",
+      "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 (walks up from the extension's install path; falls back to `npm root -g` from a dev checkout), Pi's own install directory (via the coding-agent `getPackageDir()` API), Pi's harness entries under `agentDir` (`agents/`, `extensions/`, `git/`, `npm/`, `prompts/`, `skills/`, `themes/`, `settings.json`, `SYSTEM.md`, `APPEND_SYSTEM.md`, `AGENTS.md`), and project-local `.pi/npm/` and `.pi/git/`. The package's own logs directory is never auto-allowed, even when an entry here covers it. Add entries here for edge cases where auto-discovery is insufficient (e.g. custom `npmCommand` pointing to pnpm).\n\nSupports `~`/`$HOME` expansion. Entries may be plain directory prefixes or wildcard patterns using `*` (matches any characters, including `/`) and `?` (matches exactly one character). `**` and `*` are equivalent — both cross directory boundaries.\n\nOn Windows, matching is case-insensitive and tolerant of either path separator.",
       "default": [],
       "type": "array",
       "items": {

package/src/config/config-schema.ts

@@ -427,7 +427,7 @@ export const unifiedConfigSchema = z
       description:
         "Additional directories to auto-allow for reads as Pi infrastructure, bypassing the external_directory gate. Supports ~ expansion and wildcard patterns (* and ?).",
       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 (walks up from the extension's install path; falls back to `npm root -g` from a dev checkout), Pi's own install directory (via the coding-agent `getPackageDir()` API), `agentDir`, `agentDir/git`, and project-local `.pi/npm/` and `.pi/git/`. Add entries here for edge cases where auto-discovery is insufficient (e.g. custom `npmCommand` pointing to pnpm).\n\nSupports `~`/`$HOME` expansion. Entries may be plain directory prefixes or wildcard patterns using `*` (matches any characters, including `/`) and `?` (matches exactly one character). `**` and `*` are equivalent — both cross directory boundaries.\n\nOn Windows, matching is case-insensitive and tolerant of either path separator.",
+        "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 (walks up from the extension's install path; falls back to `npm root -g` from a dev checkout), Pi's own install directory (via the coding-agent `getPackageDir()` API), Pi's harness entries under `agentDir` (`agents/`, `extensions/`, `git/`, `npm/`, `prompts/`, `skills/`, `themes/`, `settings.json`, `SYSTEM.md`, `APPEND_SYSTEM.md`, `AGENTS.md`), and project-local `.pi/npm/` and `.pi/git/`. The package's own logs directory is never auto-allowed, even when an entry here covers it. Add entries here for edge cases where auto-discovery is insufficient (e.g. custom `npmCommand` pointing to pnpm).\n\nSupports `~`/`$HOME` expansion. Entries may be plain directory prefixes or wildcard patterns using `*` (matches any characters, including `/`) and `?` (matches exactly one character). `**` and `*` are equivalent — both cross directory boundaries.\n\nOn Windows, matching is case-insensitive and tolerant of either path separator.",
       default: [],
     }),
     authorizerChain: z.array(z.string().min(1)).optional().meta({

package/src/config/extension-paths.ts

@@ -16,16 +16,44 @@ export interface ExtensionPaths {
   readonly forwardingDir: string;
   readonly globalLogsDir: string;
   /**
-   * Static Pi infrastructure directories used for external-directory
-   * read auto-allow. Computed once from `agentDir`,
+   * Static Pi infrastructure roots used for external-directory read
+   * auto-allow; an entry may be a directory or a single file. Computed once
+   * from `agentDir` (only Pi's harness entries, never `agentDir` itself),
    * `discoverGlobalNodeModulesRoot()`, and (when provided) Pi's own
    * install directory (`getPackageDir()`). 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[];
+  /**
+   * Directories never auto-allowed as infrastructure reads, even inside one of
+   * `piInfrastructureDirs` or a configured `piInfrastructureReadPaths` entry:
+   * this package's own logs directory, whose entries hold tool input.
+   */
+  readonly piInfrastructureExcludedDirs: readonly string[];
 }
 
+/**
+ * The entries under `agentDir` that Pi's harness reads: its resource roots
+ * (`skills`, `prompts`, `themes`, `extensions`, the system-prompt files, the
+ * global `AGENTS.md`), its package install roots (`npm`, `git`), settings, and
+ * subagent definitions. Everything else there (`auth.json`, `sessions/`,
+ * `mcp-oauth/`, and the like) stays behind the `external_directory` gate.
+ */
+const AGENT_DIR_INFRASTRUCTURE_ENTRIES = [
+  "agents",
+  "extensions",
+  "git",
+  "npm",
+  "prompts",
+  "skills",
+  "themes",
+  "settings.json",
+  "SYSTEM.md",
+  "APPEND_SYSTEM.md",
+  "AGENTS.md",
+] as const;
+
 /**
  * Compute all immutable path constants from `agentDir`.
  *
@@ -49,8 +77,7 @@ export function computeExtensionPaths(
 
   const globalNodeModulesRoot = discoverGlobalNodeModulesRoot();
   const piInfrastructureDirs: string[] = [
-    agentDir,
-    join(agentDir, "git"),
+    ...AGENT_DIR_INFRASTRUCTURE_ENTRIES.map((entry) => join(agentDir, entry)),
     ...(globalNodeModulesRoot ? [globalNodeModulesRoot] : []),
     ...(piPackageDir ? [piPackageDir] : []),
   ];
@@ -62,5 +89,6 @@ export function computeExtensionPaths(
     forwardingDir,
     globalLogsDir,
     piInfrastructureDirs,
+    piInfrastructureExcludedDirs: [globalLogsDir],
   };
 }

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

@@ -1,10 +1,12 @@
 import { capabilitySurfaceForTool } from "#src/access-intent/path-surfaces";
 import { getToolInputPath } from "#src/access-intent/tool-input-path";
 import type { PathNormalizer } from "#src/path/path-normalizer";
+import type { InfrastructureReadScope } from "#src/path/pi-infrastructure-read";
 import type { ScopedPermissionResolver } from "#src/policy/permission-resolver";
 import { buildExternalDirectoryAskPayload } from "#src/presentation/path-ask-payload";
 import { SessionApproval } from "#src/session/session-approval";
 import type { ToolAccessExtractorLookup } from "#src/tool-input/tool-access-extractor-registry";
+import type { PermissionCheckResult } from "#src/types";
 import type { GateResult } from "./descriptor";
 import { resolveExternalDirectoryPolicy } from "./external-directory-policy";
 import {
@@ -19,12 +21,13 @@ import type { ToolCallContext } from "./types";
  *
  * Returns `null` when the gate does not apply (no CWD, tool is not
  * path-bearing, or path is inside the working directory).
- * Returns a `GateBypass` for Pi infrastructure reads.
+ * Returns a `GateBypass` for Pi infrastructure reads, unless a deny rule
+ * naming the path outranks it.
  * Returns a `GateDescriptor` for external paths needing a permission check.
  */
 export function describeExternalDirectoryGate(
   tcc: ToolCallContext,
-  infraDirs: string[],
+  infraScope: InfrastructureReadScope,
   resolver: ScopedPermissionResolver,
   normalizer: PathNormalizer,
   extractors?: ToolAccessExtractorLookup,
@@ -50,8 +53,24 @@ export function describeExternalDirectoryGate(
     return null;
   }
 
+  // The narrowest `external_directory`-family surface this tool's identity
+  // proves; the bare family name folds both directions (ADR 0013 §10).
+  const surface = capabilitySurfaceForTool("external_directory", tcc.toolName);
+
+  // Resolved before the infrastructure bypass so a rule can be weighed against
+  // it; the runner consumes this preCheck and skips its own resolve.
+  const preCheck = resolveExternalDirectoryPolicy(
+    accessPath,
+    resolver,
+    surface,
+    tcc.agentName ?? undefined,
+  );
+
   // ── Pi infrastructure read bypass ──────────────────────────────────────
-  if (normalizer.isInfrastructureRead(tcc.toolName, accessPath, infraDirs)) {
+  if (
+    normalizer.isInfrastructureRead(tcc.toolName, accessPath, infraScope) &&
+    !isTargetedDeny(preCheck)
+  ) {
     return {
       action: "allow",
       // Containment allowed this, not a rule the operator wrote.
@@ -78,18 +97,6 @@ export function describeExternalDirectoryGate(
 
   // ── Build descriptor for permission check ───────────────────────────────
   const resolvedAlias = accessPath.resolvedAlias();
-
-  // The narrowest `external_directory`-family surface this tool's identity
-  // proves; the bare family name folds both directions (ADR 0013 §10).
-  const surface = capabilitySurfaceForTool("external_directory", tcc.toolName);
-
-  // The runner consumes this preCheck and skips its own resolve.
-  const preCheck = resolveExternalDirectoryPolicy(
-    accessPath,
-    resolver,
-    surface,
-    tcc.agentName ?? undefined,
-  );
   const pattern = normalizer.approvalPatternFor(accessPath);
 
   const payload = buildExternalDirectoryAskPayload({
@@ -120,3 +127,21 @@ export function describeExternalDirectoryGate(
     },
   };
 }
+
+/**
+ * True for a deny from a rule naming this path: not the family's catch-all
+ * (`"*"`, or `"**"`, which compiles identically), and not the universal
+ * fallback (no matched pattern). Only such a deny
+ * outranks the Pi infrastructure read bypass, so a deny-by-default policy keeps
+ * its skill and package reads.
+ */
+function isTargetedDeny(check: PermissionCheckResult): boolean {
+  return (
+    check.state === "deny" &&
+    check.matchedPattern !== undefined &&
+    !CATCH_ALL_PATTERN.test(check.matchedPattern)
+  );
+}
+
+/** A pattern of wildcards alone, which matches every path. */
+const CATCH_ALL_PATTERN = /^\*+$/;

package/src/handlers/gates/tool-call-gate-pipeline.ts

@@ -7,6 +7,7 @@ import {
 import type { ShellToolsConfig } from "#src/config/config-schema";
 import type { SkillPromptEntry } from "#src/exposure/skill-prompt-sanitizer";
 import type { PathNormalizer } from "#src/path/path-normalizer";
+import type { InfrastructureReadScope } from "#src/path/pi-infrastructure-read";
 import type { ScopedPermissionResolver } from "#src/policy/permission-resolver";
 import type { ToolAccessExtractorLookup } from "#src/tool-input/tool-access-extractor-registry";
 import type { ToolInputFormatterLookup } from "#src/tool-input/tool-input-formatter-registry";
@@ -39,8 +40,8 @@ import type { GateOutcome, ToolCallContext } from "./types";
 export interface ToolCallGateInputs {
   /** Active skill prompt entries for the skill-read gate. */
   getActiveSkillEntries(): SkillPromptEntry[];
-  /** Combined infrastructure read directories (static + config-derived). */
-  getInfrastructureReadDirs(): string[];
+  /** Where infrastructure reads are auto-allowed (static + config-derived). */
+  getInfrastructureReadScope(): InfrastructureReadScope;
   /** Resolved tool-preview formatter options from the current config. */
   getToolPreviewLimits(): ToolPreviewFormatterOptions;
   /** The session's path normalizer (platform + cwd baked in). */
@@ -60,7 +61,7 @@ export interface ToolCallGateInputs {
  * `PermissionGateHandler`. `evaluate(tcc, runner)` encapsulates:
  * - bash-command extraction and single `BashProgram.parse` (#308)
  * - `ToolPreviewFormatter` construction from `getToolPreviewLimits()`
- * - infrastructure-dir list from `getInfrastructureReadDirs()`
+ * - infrastructure-read scope from `getInfrastructureReadScope()`
  * - all six gate producers in their prescribed order
  * - the run loop, which runs an unconditionally denying gate ahead of the
  *   rest and returns the first block outcome, or allow
@@ -98,7 +99,7 @@ export class ToolCallGatePipeline {
       this.customFormatters,
     );
 
-    const infraDirs = this.inputs.getInfrastructureReadDirs();
+    const infraScope = this.inputs.getInfrastructureReadScope();
 
     const gateProducers: Array<() => GateResult | Promise<GateResult>> = [
       () =>
@@ -110,7 +111,7 @@ export class ToolCallGatePipeline {
       () =>
         describeExternalDirectoryGate(
           tcc,
-          infraDirs,
+          infraScope,
           this.resolver,
           normalizer,
           this.customExtractors,

package/src/path/path-normalizer.ts

@@ -10,7 +10,10 @@ import { deriveApprovalPattern } from "./approval-pattern";
 import { resolveNativeToolTarget } from "./native-tool-target";
 import { isPathOutsideWorkingDirectory } from "./path-containment";
 import type { PathFlavor } from "./path-flavor";
-import { isPiInfrastructureRead } from "./pi-infrastructure-read";
+import {
+  type InfrastructureReadScope,
+  isPiInfrastructureRead,
+} from "./pi-infrastructure-read";
 
 /**
  * The interpreted effect of a literal `cd` target on the effective base, under
@@ -219,14 +222,15 @@ export class PathNormalizer {
   isInfrastructureRead(
     toolName: string,
     accessPath: AccessPath,
-    infraDirs: readonly string[],
+    scope: InfrastructureReadScope,
   ): boolean {
     return isPiInfrastructureRead(
       toolName,
       accessPath.boundaryValue(),
-      infraDirs,
+      scope.dirs,
       this.cwd,
       this.flavor,
+      scope.excludedDirs,
     );
   }
 

package/src/path/pi-infrastructure-read.ts

@@ -4,6 +4,18 @@ import { wildcardMatch } from "#src/policy/wildcard-matcher";
 import { expandHomePath } from "./expand-home";
 import type { PathFlavor } from "./path-flavor";
 
+/**
+ * Where Pi infrastructure reads are auto-allowed: the roots a read-only tool
+ * may read without the `external_directory` gate, and the directories never
+ * auto-allowed even inside a root.
+ */
+export interface InfrastructureReadScope {
+  /** Roots (directories, files, or glob patterns) whose reads are auto-allowed. */
+  readonly dirs: readonly string[];
+  /** Directories never auto-allowed, even inside a root; wins over `dirs`. */
+  readonly excludedDirs: readonly string[];
+}
+
 function containsGlobChars(value: string): boolean {
   return value.includes("*") || value.includes("?");
 }
@@ -14,12 +26,15 @@ function containsGlobChars(value: string): boolean {
  *
  * 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`
+ * 2. The normalized path is not within any of `excludedDirs`.
+ * 3. 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` entries may be absolute paths or patterns containing
- * `~`/`$HOME` (expanded at call time) or glob characters (`*`, `?`).
+ * `infrastructureDirs` entries may be absolute paths (a directory, or a file,
+ * which admits only itself) or patterns containing `~`/`$HOME` (expanded at
+ * call time) or glob characters (`*`, `?`). `excludedDirs` entries are
+ * directory prefixes with the same `~`/`$HOME` expansion.
  * Project-local paths are computed fresh from `cwd` on each call so they
  * follow working-directory changes without a runtime rebuild.
  */
@@ -29,11 +44,16 @@ export function isPiInfrastructureRead(
   infrastructureDirs: readonly string[],
   cwd: string,
   flavor: PathFlavor,
+  excludedDirs: readonly string[] = [],
 ): boolean {
   if (!READ_ONLY_PATH_BEARING_TOOLS.has(toolName)) {
     return false;
   }
 
+  for (const dir of excludedDirs) {
+    if (flavor.isWithin(normalizedPath, expandHomePath(dir))) return false;
+  }
+
   // On Windows the path value is canonicalized + lowercased; the flavor's match
   // options fold case (and separators) so mixed-case infra dirs and glob
   // patterns still match.

package/src/session/permission-session.ts

@@ -15,6 +15,7 @@ import {
 import type { ToolCallGateInputs } from "#src/handlers/gates/tool-call-gate-pipeline";
 import type { PathFlavor } from "#src/path/path-flavor";
 import { PathNormalizer } from "#src/path/path-normalizer";
+import type { InfrastructureReadScope } from "#src/path/pi-infrastructure-read";
 import type { ScopedPermissionManager } from "#src/policy/permission-manager";
 import {
   resolveToolPreviewLimits,
@@ -237,14 +238,17 @@ export class PermissionSession implements ToolCallGateInputs {
   // ── Infrastructure paths ───────────────────────────────────────────────
 
   /**
-   * Combined infrastructure read directories: static paths from
-   * `ExtensionPaths` plus config-derived paths.
+   * Where infrastructure reads are auto-allowed: the static roots from
+   * `ExtensionPaths` plus the config-derived `piInfrastructureReadPaths`.
    */
-  getInfrastructureReadDirs(): string[] {
-    return [
-      ...this.paths.piInfrastructureDirs,
-      ...(this.config.piInfrastructureReadPaths ?? []),
-    ];
+  getInfrastructureReadScope(): InfrastructureReadScope {
+    return {
+      dirs: [
+        ...this.paths.piInfrastructureDirs,
+        ...(this.config.piInfrastructureReadPaths ?? []),
+      ],
+      excludedDirs: this.paths.piInfrastructureExcludedDirs,
+    };
   }
 
   /**