@gotgenes/pi-permission-system 38.0.0 → 38.0.2

package/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [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)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** tolerate a non-Pi before_agent_start payload ([#860](https://github.com/gotgenes/pi-packages/issues/860)) ([33f6a24](https://github.com/gotgenes/pi-packages/commit/33f6a24c820f23d43a56c9377245e804c2fd8ba2)), closes [#860](https://github.com/gotgenes/pi-packages/issues/860)
+
 ## [38.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v37.0.0...pi-permission-system-v38.0.0) (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.

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
@@ -1100,8 +1106,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/package.json

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

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/handlers/before-agent-start.ts

@@ -22,8 +22,8 @@ import type { TurnPreparation } from "./session-turn-prep";
 
 /** Minimal subset of BeforeAgentStartEvent used by this handler. */
 interface BeforeAgentStartPayload {
-  /** The prompt rendered from `systemPromptOptions` as it stands right now. */
-  readonly systemPrompt: string;
+  /** Pi renders a string; a host may supply ordered prompt fragments instead. */
+  readonly systemPrompt: string | readonly string[];
   /**
    * The mutable parts Pi renders the prompt from; later handlers, and Pi
    * itself, see what this handler writes here. `customPrompt` says whether Pi
@@ -32,7 +32,7 @@ interface BeforeAgentStartPayload {
    * renders from, and `sections` is where it is stated. `skills` is the
    * catalogue Pi renders, which policy narrows.
    */
-  systemPromptOptions: Pick<
+  systemPromptOptions?: Pick<
     NormalizedBuildSystemPromptOptions,
     "customPrompt" | "toolSnippets" | "promptGuidelines" | "sections" | "skills"
   >;
@@ -56,10 +56,12 @@ export function shouldExposeTool(
 /**
  * Handles the `before_agent_start` event: tool filtering + prompt sanitization.
  *
- * Every change to the prompt is stated through `event.systemPromptOptions`,
+ * When provided, prompt changes are stated through `event.systemPromptOptions`,
  * never as a returned `systemPrompt`: a returned prompt is frozen for the run,
  * so the sections an extension later in the chain adds (Pi's own
  * `<mcp_servers>` among them) would never reach the provider (#999).
+ * Without those options, only tool filtering and skill path resolution run;
+ * there is no mutable section or skill catalogue to narrow.
  *
  * Narrowing the active set is enough for a prompt Pi wrote: Pi renders its
  * `<tools>` and `<rules>` from the reconciled active set. A subagent child's
@@ -97,7 +99,12 @@ export class AgentPrepHandler {
   ): Promise<BeforeAgentStartEventResult> {
     this.turnPrep.prepare(ctx);
 
-    const agentName = this.session.resolveAgentName(ctx, event.systemPrompt);
+    // Normalize once at the boundary, before either prompt consumer reads it.
+    const systemPrompt =
+      typeof event.systemPrompt === "string"
+        ? event.systemPrompt
+        : event.systemPrompt.join("\n");
+    const agentName = this.session.resolveAgentName(ctx, systemPrompt);
     const registered = readRegisteredTools(this.toolRegistry.getAll());
     const surface = this.session.resolveExposedTools(
       this.observeToolSurface(registered),
@@ -118,7 +125,7 @@ export class AgentPrepHandler {
     }
 
     const options = event.systemPromptOptions;
-    if (this.isSubagentUnderCustomPrompt(event, ctx)) {
+    if (options && this.isSubagentUnderCustomPrompt(event, ctx)) {
       const sections = renderToolSurfaceSections({
         allowedTools,
         toolSnippets: options.toolSnippets,
@@ -134,12 +141,14 @@ export class AgentPrepHandler {
     // read before the skill list is narrowed.
     this.session.setActiveSkillEntries(
       visibleSkillPromptEntries(
-        event.systemPrompt,
+        systemPrompt,
         this.resolver,
         agentName,
         this.session.getPathNormalizer(),
       ),
     );
+    if (!options) return {};
+
     // Denials are judged on the list Pi renders `<skills>` from, not on the
     // rendered prompt: that prompt predates this turn's tool changes, and on
     // the turn `read`/`bash` return from a full denial it lists no catalogue.
@@ -181,5 +190,5 @@ export class AgentPrepHandler {
  * test, so an empty string reads here the way it reads there: as none.
  */
 function hasCustomPrompt(event: BeforeAgentStartPayload): boolean {
-  return Boolean(event.systemPromptOptions.customPrompt);
+  return Boolean(event.systemPromptOptions?.customPrompt);
 }

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

@@ -36,15 +36,20 @@ 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);
-
   // ── Pi infrastructure read bypass ──────────────────────────────────────
   if (normalizer.isInfrastructureRead(tcc.toolName, accessPath, infraDirs)) {
     return {

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

@@ -205,7 +205,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,11 +1,13 @@
-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";
@@ -60,6 +62,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 +186,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(

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;
 }