@gotgenes/pi-permission-system 38.0.1 → 39.0.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** a path rule applies to the file a built-in tool opens, however the path is spelled ([33579c5](https://github.com/gotgenes/pi-packages/commit/33579c56f085ed982189e0f75764f60abb183f1e)), closes [#997](https://github.com/gotgenes/pi-packages/issues/997)
+* **pi-permission-system:** an outside file spelled as a file URL still asks for external-directory access ([1d7df71](https://github.com/gotgenes/pi-packages/commit/1d7df71d590c32a2b3fee5f28462058d3775d662)), closes [#997](https://github.com/gotgenes/pi-packages/issues/997)
+* **pi-permission-system:** a permissions-service path query sees the file the tool would open ([9d4f0f3](https://github.com/gotgenes/pi-packages/commit/9d4f0f3e29ff1224a50321c95ed0ddc65b6f1c20)), closes [#997](https://github.com/gotgenes/pi-packages/issues/997)
+* **pi-permission-system:** a path prompt shows the file a rewritten spelling resolves to ([3e47dd3](https://github.com/gotgenes/pi-packages/commit/3e47dd32c32bb9e9b13b1469a983244ad6f01250)), closes [#997](https://github.com/gotgenes/pi-packages/issues/997)
+
+### Documentation
+
+* **pi-permission-system:** document that built-in tool paths are gated as the file Pi opens ([81b3eb1](https://github.com/gotgenes/pi-packages/commit/81b3eb1e2150100ab49cef9c6e759f000b2720e0)), closes [#997](https://github.com/gotgenes/pi-packages/issues/997)
+* **pi-permission-system:** scope the $HOME expansion note to bash and extension tool paths ([8a31bf2](https://github.com/gotgenes/pi-packages/commit/8a31bf26e31ad2d1dacb5286bb576d3033687699)), closes [#997](https://github.com/gotgenes/pi-packages/issues/997)
+
 ## [38.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v38.0.0...pi-permission-system-v38.0.1) (2026-10-02)
 
 

package/README.md

@@ -75,6 +75,7 @@ See [docs/configuration.md](docs/configuration.md#inline-permission-dialog-tui)
 The `path` surface is a cross-cutting gate that applies to **all** file access — Pi tools, bash commands, MCP calls, and extension tools alike.
 Extension and MCP tools that operate on paths (via `input.path`, MCP's `input.arguments.path`, or a registered access extractor) are gated by default, so a `path` deny cannot be overridden by a per-tool allow — making it the right place to protect sensitive files like `.env` or `~/.ssh/*` from every tool at once.
 A `path` pattern matches both the path as the agent references it and its canonical (symlink-resolved) form, so a deny still fires when a symlink aliases a sensitive target.
+For Pi's built-in file tools, "the path as the agent references it" is the file the tool actually opens: Pi's resolver decodes a `file://` URL, turns Unicode spaces into spaces, and for `read` falls back to macOS's curly-quote and screenshot spellings, so a deny on the file on disk fires however the path was spelled.
 
 For per-tool path patterns (`read`, `write`, `edit`, `find`, `grep`, `ls`), patterns are matched against the file path from `input.path`.
 This lets you express rules like "allow reads but deny `.env` files" at the individual tool level.
@@ -221,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

@@ -687,6 +687,12 @@ If it denies, the command is blocked without reaching subsequent gates — no wa
 
 Path patterns match both the path **as the agent references it** and its canonical (symlink-resolved) form, so a deny on a sensitive spelling cannot be evaded through a symlink alias (see Symlinked paths below).
 
+For Pi's built-in file tools (`read`, `write`, `edit`, `ls`, `find`, `grep`), the path the agent references is the file the tool opens, not the literal argument.
+Pi resolves that argument itself before touching the disk: it decodes a `file://` URL, turns Unicode spaces into ordinary spaces, translates a Git Bash, Cygwin, or WSL drive path (`/c/…`, `/cygdrive/c/…`, `/mnt/c/…`) on Windows, and for `read` alone falls back to the macOS screenshot (`\u202FPM`), NFD, and curly-quote (`’`) spellings of a name that does not exist.
+The gates match the file that resolution names, so a deny keyed on the file on disk fires however it was spelled, and an ask shows the file under "resolves to" when the spelling was rewritten.
+Pi does not expand `$HOME` or strip quotes from a tool's path, so neither do these gates: `read $HOME/.ssh/config` names `<cwd>/$HOME/.ssh/config`, the file the tool would open.
+Extension and MCP tool paths keep their literal spelling.
+
 For bash commands, the extension extracts path-candidate tokens from the command (dot-files like `.env`, relative paths like `src/foo.ts`, and absolute paths) and evaluates each against the path rules.
 The most restrictive result across all tokens determines the outcome.
 When the current working directory is known, relative bash tokens are matched with cwd-normalized policy values, resolved against the effective directory after literal `cd` commands; a token after a non-literal `cd` (e.g. `cd "$DIR"`) stays conservative and matches only its literal form.
@@ -825,7 +831,7 @@ The governing record is [ADR 0009](https://github.com/gotgenes/pi-packages/blob/
 
 #### Symlinked paths
 
-A `path`, `external_directory`, or per-tool file-pattern rule (`read`/`write`/`edit`/`grep`/`find`/`ls`) matches the path **as the agent references it** and the OS-resolved (symlink-followed) path.
+A `path`, `external_directory`, or per-tool file-pattern rule (`read`/`write`/`edit`/`grep`/`find`/`ls`) matches the path **as the agent references it** (for a built-in file tool, the file Pi opens) and the OS-resolved (symlink-followed) path.
 This matters on macOS, where `/tmp` is a symlink to `/private/tmp`: a rule keyed on `/tmp/*` allows access via `/tmp` even though the access resolves to `/private/tmp`, and a rule keyed on `/private/tmp/*` works too.
 
 ```jsonc
@@ -844,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:
+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.
 
-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`
+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.
 
@@ -1100,8 +1113,9 @@ A prefix is recognized only when it stands alone or precedes a separator, so a l
 
 The pattern is stored and displayed as written (e.g. `~/development/*`) in logs and approval dialogs.
 
-Path **values** supplied by tool calls and bash commands are expanded the same way.
-This means `~/...`, `$HOME/...`, `${HOME}/...`, and the fully-expanded absolute form all match a single home-anchored pattern: a `read` tool called with path `~/.ssh/config`, `$HOME/.ssh/config`, `${HOME}/.ssh/config`, or `/Users/me/.ssh/config` is all caught by a `"~/.ssh/*": "deny"` rule.
+Path **values** supplied by bash commands and extension tools are expanded the same way.
+This means `~/...`, `$HOME/...`, `${HOME}/...`, and the fully-expanded absolute form all match a single home-anchored pattern: `cat ~/.ssh/config`, `cat $HOME/.ssh/config`, or `cat /Users/me/.ssh/config` is caught by a `"~/.ssh/*": "deny"` rule.
+Pi's built-in file tools expand only `~`, as Pi itself does: a `read` of `~/.ssh/config` or `/Users/me/.ssh/config` is caught, while a `read` of `$HOME/.ssh/config` opens `<cwd>/$HOME/.ssh/config` and is matched as that file.
 
 ---
 

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.1",
+  "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/access-intent/access-path.ts

@@ -1,7 +1,10 @@
+import { canonicalizePath } from "#src/path/canonicalize-path";
+import type { NativeToolTarget } from "#src/path/native-tool-target";
 import type { PathFlavor } from "#src/path/path-flavor";
 
 import {
   canonicalNormalizePathForComparison,
+  cwdRelativePolicyValues,
   getPathPolicyValues,
   normalizePathForComparison,
 } from "./path-normalization";
@@ -25,7 +28,8 @@ import {
  *   only when it names a location distinct from the lexical form, for
  *   disclosing a symlink target in a prompt or denial message.
  *
- * Construct via {@link forPath} (resolved, with optional cd-folded base) or
+ * Construct via {@link forPath} (resolved, with optional cd-folded base),
+ * {@link forNativeTarget} (the file a built-in Pi tool opens), or
  * {@link forLiteral} (literal-only, for an unknown base); the constructor is
  * private.
  */
@@ -34,6 +38,7 @@ export class AccessPath {
     private readonly lexical: string,
     private readonly matchAliases: readonly string[],
     private readonly canonical: string,
+    private readonly rewritten = false,
   ) {}
 
   /**
@@ -72,16 +77,17 @@ export class AccessPath {
   }
 
   /**
-   * The canonical (symlink-resolved) form when it names a location distinct
-   * from the lexical form — for disclosing the resolved target in a prompt or
-   * denial message. `undefined` when the path is not a symlink (canonical
-   * equals lexical) or has no canonical (literal-only / empty input).
+   * The location the access reaches when it differs from what was typed — for
+   * disclosing it in a prompt or denial message: the canonical
+   * (symlink-resolved) form when it is distinct from the lexical form, else the
+   * lexical form itself when a built-in tool's resolver rewrote the typed
+   * spelling ({@link forNativeTarget}). `undefined` otherwise.
    */
   resolvedAlias(): string | undefined {
-    if (!this.canonical || this.canonical === this.lexical) {
-      return undefined;
+    if (this.canonical && this.canonical !== this.lexical) {
+      return this.canonical;
     }
-    return this.canonical;
+    return this.rewritten ? this.lexical : undefined;
   }
 
   /**
@@ -115,6 +121,38 @@ export class AccessPath {
     );
   }
 
+  /**
+   * Build an `AccessPath` for the file a built-in Pi file tool opens, from its
+   * already-resolved {@link NativeToolTarget}.
+   *
+   * The target is taken as the tool will open it: no literal cleanup (trim,
+   * quote strip, `$HOME`), since Pi's resolver applies none. `matchValues()`
+   * is the target, its cwd-relative alias, and the tool's relative spelling,
+   * plus the canonical form — the same array {@link forPath} builds for a
+   * relative or already-normalized spelling the tool does not rewrite. An
+   * absolute spelling with `..` or doubled separators keeps no as-typed alias:
+   * `/tmp/../etc/passwd` matches as `/etc/passwd`, the file opened, so a rule
+   * on `/tmp/*` no longer covers it.
+   */
+  static forNativeTarget(
+    native: NativeToolTarget,
+    options: { cwd: string; flavor: PathFlavor },
+  ): AccessPath {
+    const { cwd, flavor } = options;
+    const lexical = flavor.comparable(native.target, cwd);
+    const aliases = [
+      lexical,
+      ...cwdRelativePolicyValues(lexical, cwd, flavor),
+      ...(native.relativeSpelling ? [native.relativeSpelling] : []),
+    ];
+    return new AccessPath(
+      lexical,
+      [...new Set(aliases)],
+      flavor.fold(canonicalizePath(lexical, flavor)),
+      native.rewritten,
+    );
+  }
+
   /**
    * Build a literal-only `AccessPath` for a path whose effective base is
    * unknown (a relative bash token after a non-literal `cd`).

package/src/access-intent/input-normalizer.ts

@@ -21,7 +21,8 @@ import { classifyToolKind } from "./tool-kind";
  * For a path-shaped surface (`path`, `external_directory`, or a path-bearing
  * tool) carrying a non-empty value, it builds an `AccessPath` and emits an
  * `access-path` intent, so the resolver matches the lexical aliases ∪ canonical
- * (symlink-resolved) set — at parity with the gates (#486, #502). An `mcp`
+ * (symlink-resolved) set — at parity with the gates (#486, #502); a built-in
+ * tool surface resolves the value to the file that tool would open. An `mcp`
  * query carrying a value evaluates that value as-is: an MCP target is already
  * a candidate name, and rebuilding proxy input from it would derive only the
  * status probe `mcp_status`. Every other surface, and any value-less
@@ -39,7 +40,7 @@ export function buildAccessIntentForSurface(
     return {
       kind: "access-path",
       surface,
-      path: normalizer.forPath(pathValue),
+      path: normalizer.forToolPath(surface, pathValue),
       agentName,
     };
   }

package/src/access-intent/path-normalization.ts

@@ -83,17 +83,22 @@ function getAbsolutePathPolicyValues(
 
   return [
     absolute,
-    ...getCwdRelativePathPolicyValues(absolute, options.cwd, flavor),
+    ...(options.cwd
+      ? cwdRelativePolicyValues(absolute, options.cwd, flavor)
+      : []),
   ];
 }
 
-function getCwdRelativePathPolicyValues(
+/**
+ * The project-relative alias of an already-absolute comparison value: `[rel]`
+ * when `absolute` lies strictly inside `cwd`, otherwise `[]`. Lets a relative
+ * rule (`src/*`) match a path however it was spelled.
+ */
+export function cwdRelativePolicyValues(
   absolute: string,
-  cwd: string | undefined,
+  cwd: string,
   flavor: PathFlavor,
 ): string[] {
-  if (!cwd) return [];
-
   const normalizedCwd = normalizePathForComparison(cwd, cwd, flavor);
   if (!normalizedCwd) return [];
   if (absolute !== normalizedCwd && !flavor.isWithin(absolute, normalizedCwd)) {

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,
@@ -36,17 +39,38 @@ export function describeExternalDirectoryGate(
   );
   if (!externalDirectoryPath) return null;
 
-  if (!normalizer.isOutsideWorkingDirectory(externalDirectoryPath)) {
+  // The boundary decision and the infrastructure-read containment check use
+  // the canonical, symlink-resolved path; pattern matching uses the typed and
+  // resolved aliases (#418). A built-in tool's path is the file Pi's resolver
+  // opens, so a `file://` spelling of an outside file is judged outside.
+  const accessPath = normalizer.forToolPath(
+    tcc.toolName,
+    externalDirectoryPath,
+  );
+  if (
+    !normalizer.isBoundaryOutsideWorkingDirectory(accessPath.boundaryValue())
+  ) {
     return null;
   }
 
-  // The boundary decision (above) and the infrastructure-read containment
-  // check (below) use the canonical, symlink-resolved path; pattern matching
-  // uses the typed and resolved aliases (#418).
-  const accessPath = normalizer.forPath(externalDirectoryPath);
+  // 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.
@@ -73,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({
@@ -115,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/path.ts

@@ -41,8 +41,9 @@ export function describePathGate(
 
   // Emit an access-path intent so the resolver matches the lexical aliases
   // *and* the canonical (symlink-resolved) form, the same set
-  // `external_directory` matches (#418, #486).
-  const accessPath = normalizer.forPath(filePath);
+  // `external_directory` matches (#418, #486). A built-in tool's path is the
+  // file Pi's resolver opens, not the spelling the model typed.
+  const accessPath = normalizer.forToolPath(tcc.toolName, filePath);
   const check = resolver.resolve({
     kind: "access-path",
     surface,
@@ -64,6 +65,7 @@ export function describePathGate(
   const payload = buildPathAskPayload({
     toolName: tcc.toolName,
     pathValue: filePath,
+    resolvedPath: accessPath.resolvedAlias(),
     agentName: tcc.agentName,
     matchedPattern: check.matchedPattern,
     surface,

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,
@@ -205,7 +206,7 @@ export class ToolCallGatePipeline {
 
     const filePath = getPathBearingToolPath(tcc.toolName, tcc.input);
     if (filePath !== null) {
-      const accessPath = normalizer.forPath(filePath);
+      const accessPath = normalizer.forToolPath(tcc.toolName, filePath);
       return {
         pathAccess: {
           path: accessPath,

package/src/path/native-tool-target.ts

@@ -0,0 +1,137 @@
+import { homedir } from "node:os";
+
+import type { PathFlavor } from "./path-flavor";
+
+/**
+ * The file one of Pi's built-in file tools (`read`, `write`, `edit`, `ls`,
+ * `find`, `grep`) opens for a `path` argument.
+ *
+ * Pi resolves that argument through its own resolver before touching the disk
+ * (`core/tools/path-utils.ts` `resolveToCwd`, plus `resolveReadPath` for
+ * `read`), and the resolver rewrites some spellings. A gate that matched the
+ * typed spelling would check one file while the tool opened another, so the
+ * path gates evaluate this target instead.
+ */
+export interface NativeToolTarget {
+  /** Absolute path the built-in tool opens. */
+  readonly target: string;
+  /**
+   * True when Pi's resolver changed the spelling in a way the typed path does
+   * not show: a Unicode space, a win32 drive mount, a `file://` URL, or a
+   * `read` fallback. `@`, `~`, and cwd resolution are not rewrites.
+   */
+  readonly rewritten: boolean;
+  /**
+   * The normalized spelling before cwd resolution, when it is relative and no
+   * read fallback fired, so a relative rule keeps matching it.
+   */
+  readonly relativeSpelling?: string;
+}
+
+/** What {@link resolveNativeToolTarget} needs besides the typed path. */
+export interface NativeToolTargetOptions {
+  cwd: string;
+  flavor: PathFlavor;
+  /** Whether the tool also tries `read`'s variant spellings. */
+  readFallbacks: boolean;
+  /** Existence probe, following symlinks like Pi's `access(F_OK)`. */
+  exists: (absolutePath: string) => boolean;
+}
+
+/**
+ * Mirror Pi's built-in tool path resolution, in Pi's order: Unicode spaces,
+ * one leading `@`, the win32 drive mount, `~`, a `file://` URL, cwd
+ * resolution, then (for `read`) the variant spellings Pi tries when the
+ * resolved path does not exist.
+ */
+export function resolveNativeToolTarget(
+  rawPath: string,
+  options: NativeToolTargetOptions,
+): NativeToolTarget {
+  const { cwd, flavor } = options;
+  const spelling = normalizeToolPathSpelling(rawPath, flavor);
+  const resolved = flavor.impl.resolve(cwd, spelling.value);
+  const fallback = options.readFallbacks
+    ? findReadVariant(resolved, options.exists)
+    : undefined;
+  if (fallback !== undefined) {
+    return { target: fallback, rewritten: true };
+  }
+  return {
+    target: resolved,
+    rewritten: spelling.rewritten,
+    ...(flavor.impl.isAbsolute(spelling.value)
+      ? {}
+      : { relativeSpelling: spelling.value }),
+  };
+}
+
+/** Pi's `normalizeUnicodeSpaces` class. */
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+
+const NARROW_NO_BREAK_SPACE = "\u202F";
+
+interface NormalizedSpelling {
+  value: string;
+  rewritten: boolean;
+}
+
+/** Pi's `normalizePath` with `normalizeUnicodeSpaces` and `stripAtPrefix`. */
+function normalizeToolPathSpelling(
+  rawPath: string,
+  flavor: PathFlavor,
+): NormalizedSpelling {
+  const spaced = rawPath.replace(UNICODE_SPACES, " ");
+  const unprefixed = spaced.startsWith("@") ? spaced.slice(1) : spaced;
+  const driveMapped = flavor.toolShellPath(unprefixed);
+  const rewritten = spaced !== rawPath || driveMapped !== unprefixed;
+
+  const home = expandToolHome(driveMapped, flavor);
+  if (home !== undefined) return { value: home, rewritten };
+
+  if (driveMapped.startsWith("file://")) {
+    try {
+      return { value: flavor.fileUrlToPath(driveMapped), rewritten: true };
+    } catch {
+      // Pi's tool throws here and opens nothing; keep the spelling as typed.
+    }
+  }
+  return { value: driveMapped, rewritten };
+}
+
+/**
+ * Pi's tilde expansion: `~` alone, `~/`, and on win32 `~\`. Unlike
+ * `expandHomePath`, it leaves `$HOME` and `${HOME}` literal.
+ */
+function expandToolHome(value: string, flavor: PathFlavor): string | undefined {
+  if (value === "~") return homedir();
+  const separators = flavor.hasPathSeparator("\\") ? ["~/", "~\\"] : ["~/"];
+  if (separators.some((prefix) => value.startsWith(prefix))) {
+    return flavor.impl.join(homedir(), value.slice(2));
+  }
+  return undefined;
+}
+
+/**
+ * Pi's `resolveReadPath` fallbacks: the first existing of the macOS AM/PM,
+ * NFD, curly-quote, and NFD + curly-quote variants, tried only when the
+ * resolved path itself does not exist. `undefined` when none applies.
+ */
+function findReadVariant(
+  resolved: string,
+  exists: (absolutePath: string) => boolean,
+): string | undefined {
+  if (exists(resolved)) return undefined;
+  const nfd = resolved.normalize("NFD");
+  const variants = [
+    resolved.replace(/ (AM|PM)\./gi, `${NARROW_NO_BREAK_SPACE}$1.`),
+    nfd,
+    toCurlyQuotes(resolved),
+    toCurlyQuotes(nfd),
+  ];
+  return variants.find((variant) => variant !== resolved && exists(variant));
+}
+
+function toCurlyQuotes(value: string): string {
+  return value.replace(/'/g, "\u2019");
+}

package/src/path/path-containment.ts

@@ -5,7 +5,7 @@ import { isSafeSystemPath } from "./safe-system-paths";
  * Pure geometry: is `canonicalPath` outside `canonicalCwd`?
  *
  * Both operands must already be canonical (symlink-resolved, win32-lowercased)
- * — the caller prepares them (see {@link PathNormalizer.isOutsideWorkingDirectory}).
+ * — the caller prepares them (see {@link PathNormalizer.isBoundaryOutsideWorkingDirectory}).
  * This predicate touches no filesystem and does no derivation; the containment
  * geometry lives on {@link PathFlavor.isWithin}.
  */

package/src/path/path-flavor.ts

@@ -1,5 +1,6 @@
 import type { PlatformPath } from "node:path";
 import { posix as posixPath, win32 as winPath } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import {
   type BashTokenShape,
@@ -66,6 +67,20 @@ export interface PathFlavor {
    * every token is an ordinary path, so the shape is always `{ kind: "plain" }`.
    */
   bashTokenShape(token: string): BashTokenShape;
+  /**
+   * The drive translation Pi's built-in file tools apply to their `path`
+   * argument: on win32, a Git Bash / MSYS / Cygwin / WSL drive path (`/c/x`,
+   * `/mnt/c/x`, `/cygdrive/c/x`) becomes `C:\x`; on POSIX the value is
+   * unchanged. Mirrors Pi's `normalizeWindowsShellPath`, which recognizes more
+   * mount spellings than a bash token's {@link bashTokenShape}.
+   */
+  toolShellPath(value: string): string;
+  /**
+   * Decode a `file://` URL into this platform's path, as Pi's built-in file
+   * tools do. Throws like Node's `fileURLToPath` for a URL the platform
+   * cannot express (a POSIX URL naming a host).
+   */
+  fileUrlToPath(url: string): string;
 }
 
 class PlatformPathFlavor implements PathFlavor {
@@ -87,6 +102,14 @@ class PlatformPathFlavor implements PathFlavor {
     return this.windows ? value.toLowerCase() : value;
   }
 
+  toolShellPath(value: string): string {
+    return this.windows ? toWindowsDrivePath(value) : value;
+  }
+
+  fileUrlToPath(url: string): string {
+    return fileURLToPath(url, { windows: this.windows });
+  }
+
   comparable(pathValue: string, base: string): string {
     return this.fold(this.impl.normalize(this.impl.resolve(base, pathValue)));
   }
@@ -132,3 +155,26 @@ export const win32PathFlavor: PathFlavor = new PlatformPathFlavor(
 export function pathFlavorForPlatform(platform: NodeJS.Platform): PathFlavor {
   return platform === "win32" ? win32PathFlavor : posixPathFlavor;
 }
+
+/** A drive path as Pi's file tools spell it: optional WSL/Cygwin mount, a letter, an optional tail. */
+const TOOL_DRIVE_PATH_PATTERN = /^\/(?:mnt\/|cygdrive\/)?([a-z])(?:\/(.*))?$/i;
+
+/**
+ * Pi's `normalizeWindowsShellPath`: a UNC (`//…`) or backslashed value is
+ * already native and passes through, as does anything not shaped like a drive.
+ */
+function toWindowsDrivePath(value: string): string {
+  if (
+    !value.startsWith("/") ||
+    value.startsWith("//") ||
+    value.includes("\\")
+  ) {
+    return value;
+  }
+  const match = TOOL_DRIVE_PATH_PATTERN.exec(value);
+  if (!match) return value;
+  const [, letter] = match;
+  // The tail group is optional, so it is absent for a bare drive (`/c`).
+  const tail = match.at(2) ?? "";
+  return `${letter.toUpperCase()}:\\${tail.replaceAll("/", "\\")}`;
+}

package/src/path/path-normalizer.ts

@@ -1,14 +1,19 @@
-import { lstatSync } from "node:fs";
+import { existsSync, lstatSync } from "node:fs";
 import { AccessPath } from "#src/access-intent/access-path";
 import {
   canonicalNormalizePathForComparison,
   normalizePathForComparison,
   normalizePathPolicyLiteral,
 } from "#src/access-intent/path-normalization";
+import { classifyToolKind } from "#src/access-intent/tool-kind";
 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
@@ -60,6 +65,33 @@ export class PathNormalizer {
     });
   }
 
+  /**
+   * Build an AccessPath for a tool call's path argument.
+   *
+   * A built-in file tool (`read`/`write`/`edit`/`ls`/`find`/`grep`) resolves
+   * the argument through Pi's own resolver, which rewrites some spellings and,
+   * for `read`, tries variant spellings that exist; the AccessPath is the file
+   * the tool opens ({@link resolveNativeToolTarget}). Every other tool's path
+   * is its own to interpret, so it keeps {@link forPath}.
+   *
+   * The variant probe is `existsSync` (`access(F_OK)`, following symlinks),
+   * matching Pi's; unlike {@link entryExists}'s `lstat`, a dangling symlink
+   * at the typed spelling does not count, so Pi tries the variants and so do we.
+   */
+  forToolPath(toolName: string, rawPath: string): AccessPath {
+    if (classifyToolKind(toolName) !== "path") return this.forPath(rawPath);
+    const native = resolveNativeToolTarget(rawPath, {
+      cwd: this.cwd,
+      flavor: this.flavor,
+      readFallbacks: toolName.trim() === "read",
+      exists: (absolutePath) => existsSync(absolutePath),
+    });
+    return AccessPath.forNativeTarget(native, {
+      cwd: this.cwd,
+      flavor: this.flavor,
+    });
+  }
+
   /** Build a literal-only AccessPath (unknown base after a non-literal `cd`). */
   forLiteral(literal: string): AccessPath {
     return AccessPath.forLiteral(literal);
@@ -157,28 +189,13 @@ export class PathNormalizer {
     return this.flavor.isWithin(pathValue, directory);
   }
 
-  /** Canonical (symlink-resolved) outside-cwd test against the baked cwd. */
-  isOutsideWorkingDirectory(pathValue: string): boolean {
-    const canonicalPath = canonicalNormalizePathForComparison(
-      pathValue,
-      this.cwd,
-      this.flavor,
-    );
-    return isPathOutsideWorkingDirectory(
-      canonicalPath,
-      this.canonicalCwd,
-      this.flavor,
-    );
-  }
-
   /**
    * Outside-cwd test for an already-canonical boundary value (from
    * {@link AccessPath.boundaryValue}), against the baked cwd.
    *
-   * Unlike {@link isOutsideWorkingDirectory}, it does not re-derive the
-   * canonical form — the caller passes a value the {@link AccessPath} already
-   * canonicalized, so a device's preserved `/dev/null` reaches the pure check's
-   * `isSafeSystemPath` exclusion intact.
+   * It does not re-derive the canonical form — the caller passes a value the
+   * {@link AccessPath} already canonicalized, so a device's preserved
+   * `/dev/null` reaches the pure check's `isSafeSystemPath` exclusion intact.
    */
   isBoundaryOutsideWorkingDirectory(canonicalPath: string): boolean {
     return isPathOutsideWorkingDirectory(
@@ -205,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/presentation/path-ask-payload.ts

@@ -14,6 +14,12 @@ interface PathAskFacts {
   toolName: string;
   /** The path as the caller typed it — what the user recognizes. */
   pathValue: string;
+  /**
+   * Where the typed path lands when that is somewhere else: its symlink
+   * target, or the file a built-in tool's resolver opens for a rewritten
+   * spelling.
+   */
+  resolvedPath?: string;
   agentName: string | null;
   matchedPattern?: string;
   /**
@@ -26,13 +32,11 @@ interface PathAskFacts {
 
 /** A tool ask gated by an explicit `path`-family rule. */
 export function buildPathAskPayload(facts: PathAskFacts): PromptPayload {
-  return pathPayload("path", facts, []);
+  return pathPayload("path", facts, resolvedAliasEvidence(facts.resolvedPath));
 }
 
-/** The facts the external-directory gate adds: the boundary and the alias. */
+/** The facts the external-directory gate adds: the boundary. */
 interface ExternalDirectoryAskFacts extends PathAskFacts {
-  /** The canonical location, when it names somewhere other than the typed path. */
-  resolvedPath?: string;
   /** The working directory the path escapes. */
   cwd: string;
 }

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,
+    };
   }
 
   /**