@gotgenes/pi-permission-system 18.0.0 → 18.0.2

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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).
 
+## [18.0.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v18.0.1...pi-permission-system-v18.0.2) (2026-07-01)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** add AccessPath.resolvedAlias() for symlink-target disclosure ([cf6e25c](https://github.com/gotgenes/pi-packages/commit/cf6e25c8a5b672fbab4b41a21240af8ca818971b))
+* **pi-permission-system:** disclose resolved symlink target in tool external-directory messages ([1225e2b](https://github.com/gotgenes/pi-packages/commit/1225e2bcface907a0a4407aadcd744c2398edc19))
+* **pi-permission-system:** disclose resolved symlink targets in bash external-directory messages ([f9fab42](https://github.com/gotgenes/pi-packages/commit/f9fab42b758dd106e67b83a0e3c95fe6fc216687))
+
+## [18.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v18.0.0...pi-permission-system-v18.0.1) (2026-06-30)
+
+
+### Documentation
+
+* **pi-permission-system:** name the path-values boundary contract and guard it ([#506](https://github.com/gotgenes/pi-packages/issues/506)) ([a47648c](https://github.com/gotgenes/pi-packages/commit/a47648c1fcff3226b6ea3269392f9d8548654ee1))
+
 ## [18.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v17.1.1...pi-permission-system-v18.0.0) (2026-06-29)
 
 

package/package.json

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

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

@@ -20,6 +20,10 @@ export interface ToolAccessIntent {
  * Not gate-emitted: the resolver produces it internally by unwrapping an
  * `access-path` intent via `matchValues()`, keeping the low-level manager
  * string-based (it never imports `AccessPath`). See {@link ResolvedAccessIntent}.
+ *
+ * This string seam is a deliberate, formalized boundary — not transitional
+ * scaffolding to collapse into the manager (ADR-0002,
+ * `docs/decisions/0002-path-values-string-boundary.md`).
  */
 export interface PathValuesAccessIntent {
   kind: "path-values";
@@ -53,6 +57,9 @@ export type AccessIntent = ToolAccessIntent | AccessPathAccessIntent;
  * What the manager consumes — the `access-path` variant has already been
  * unwrapped to `path-values` by the resolver via `path.matchValues()`.
  *
- * The manager stays string-based and never imports `AccessPath`.
+ * The manager stays string-based and never imports `AccessPath`: this is the
+ * deliberate boundary formalized in ADR-0002
+ * (`docs/decisions/0002-path-values-string-boundary.md`), guarded by a
+ * `no-restricted-imports` lint rule on `permission-manager.ts`.
  */
 export type ResolvedAccessIntent = ToolAccessIntent | PathValuesAccessIntent;

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

@@ -2,7 +2,7 @@ import {
   canonicalNormalizePathForComparison,
   getPathPolicyValues,
   normalizePathForComparison,
-} from "#src/path-utils";
+} from "./path-normalization";
 
 /**
  * A path's two representations held behind type-distinct accessors.
@@ -19,6 +19,9 @@ import {
  *   outside-CWD containment and infra-read checks.
  * - {@link value} returns `string` — the lexical absolute form, for display,
  *   approval patterns, decision values, and logs.
+ * - {@link resolvedAlias} returns `string | undefined` — the canonical form
+ *   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
  * {@link forLiteral} (literal-only, for an unknown base); the constructor is
@@ -66,6 +69,19 @@ export class AccessPath {
     return this.lexical;
   }
 
+  /**
+   * 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).
+   */
+  resolvedAlias(): string | undefined {
+    if (!this.canonical || this.canonical === this.lexical) {
+      return undefined;
+    }
+    return this.canonical;
+  }
+
   /**
    * Build an `AccessPath` for a tool-input or bash-token path, resolved against
    * `resolveBase` (the cd-folded effective directory; defaults to `cwd`).

package/src/access-intent/bash/bash-path-resolver.ts

@@ -14,8 +14,9 @@ import {
   collectRedirectTokens,
   extractCommandName,
 } from "#src/access-intent/bash/token-collection";
+import { normalizePathPolicyLiteral } from "#src/access-intent/path-normalization";
 import type { PathNormalizer } from "#src/path-normalizer";
-import { isSafeSystemPath, normalizePathPolicyLiteral } from "#src/path-utils";
+import { isSafeSystemPath } from "#src/safe-system-paths";
 
 // ── Internal types ───────────────────────────────────────────────────────────
 

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

@@ -0,0 +1,139 @@
+import { posix as posixPath, win32 as winPath } from "node:path";
+
+import { canonicalizePath } from "#src/canonicalize-path";
+import { expandHomePath } from "#src/expand-home";
+import { isPathWithinDirectory } from "#src/path-containment";
+
+/**
+ * Representation derivation backing {@link AccessPath}: turn an accessed path
+ * into the lexical / canonical / policy-value forms the resolver matches
+ * against rules. Pure (no filesystem access except `canonicalizePath`'s
+ * best-effort symlink resolution); the `platform` is injected, never read
+ * ambiently.
+ */
+export function normalizePathForComparison(
+  pathValue: string,
+  cwd: string,
+  platform: NodeJS.Platform,
+): string {
+  const trimmed = pathValue.trim().replace(/^['"]|['"]$/g, "");
+  if (!trimmed) {
+    return "";
+  }
+
+  let normalizedPath = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed;
+  normalizedPath = expandHomePath(normalizedPath);
+
+  const impl = platform === "win32" ? winPath : posixPath;
+  const absolutePath = impl.resolve(cwd, normalizedPath);
+  const normalizedAbsolutePath = impl.normalize(absolutePath);
+  return platform === "win32"
+    ? normalizedAbsolutePath.toLowerCase()
+    : normalizedAbsolutePath;
+}
+
+export interface PathPolicyValueOptions {
+  /**
+   * Current Pi working directory. When provided, returned values include a
+   * project-relative alias for paths that resolve inside this directory.
+   */
+  cwd?: string;
+  /**
+   * Directory used to resolve `pathValue` into an absolute policy value.
+   * Defaults to `cwd`. Bash uses this for tokens seen after a literal `cd`.
+   */
+  resolveBase?: string;
+}
+
+/**
+ * Normalize a single path-like lookup value without resolving it against CWD.
+ *
+ * Preserves compatibility with existing relative path rules (`src/*`, `*.env`)
+ * while applying the same lexical cleanup as
+ * {@link normalizePathForComparison}: trim, strip simple wrapping quotes,
+ * strip the OpenCode-style leading `@`, and expand `~` / `$HOME`.
+ */
+export function normalizePathPolicyLiteral(pathValue: string): string {
+  const trimmed = pathValue.trim().replace(/^['"]|['"]$/g, "");
+  if (!trimmed) return "";
+  const unprefixed = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed;
+  return expandHomePath(unprefixed);
+}
+
+/**
+ * Return equivalent lookup values for path-policy matching.
+ *
+ * The first value is the cwd/effective-base normalized absolute path when a
+ * base is available. The later values preserve project-relative and raw
+ * relative forms so existing rules like `src/*` and `*.env` continue to match.
+ */
+export function getPathPolicyValues(
+  pathValue: string,
+  options: PathPolicyValueOptions,
+  platform: NodeJS.Platform,
+): string[] {
+  const literal = normalizePathPolicyLiteral(pathValue);
+  if (!literal) return [];
+  if (literal === "*") return ["*"];
+
+  return [
+    ...new Set([
+      ...getAbsolutePathPolicyValues(pathValue, options, platform),
+      literal,
+    ]),
+  ];
+}
+
+function getAbsolutePathPolicyValues(
+  pathValue: string,
+  options: PathPolicyValueOptions,
+  platform: NodeJS.Platform,
+): string[] {
+  const resolveBase = options.resolveBase ?? options.cwd;
+  if (!resolveBase) return [];
+
+  const absolute = normalizePathForComparison(pathValue, resolveBase, platform);
+  if (!absolute) return [];
+
+  return [
+    absolute,
+    ...getCwdRelativePathPolicyValues(absolute, options.cwd, platform),
+  ];
+}
+
+function getCwdRelativePathPolicyValues(
+  absolute: string,
+  cwd: string | undefined,
+  platform: NodeJS.Platform,
+): string[] {
+  if (!cwd) return [];
+
+  const normalizedCwd = normalizePathForComparison(cwd, cwd, platform);
+  if (!normalizedCwd) return [];
+  if (
+    absolute !== normalizedCwd &&
+    !isPathWithinDirectory(absolute, normalizedCwd, platform)
+  ) {
+    return [];
+  }
+
+  const impl = platform === "win32" ? winPath : posixPath;
+  const relativeValue = impl.relative(normalizedCwd, absolute);
+  return relativeValue ? [relativeValue] : [];
+}
+
+/**
+ * Like {@link normalizePathForComparison} but also resolves symlinks via
+ * `realpathSync` (best-effort). Use this for containment decisions where the
+ * OS-followed path matters, not for pattern matching.
+ */
+export function canonicalNormalizePathForComparison(
+  pathValue: string,
+  cwd: string,
+  platform: NodeJS.Platform,
+): string {
+  const lexical = normalizePathForComparison(pathValue, cwd, platform);
+  if (!lexical) return "";
+  const canonical = canonicalizePath(lexical, platform);
+  return platform === "win32" ? canonical.toLowerCase() : canonical;
+}

package/src/denial-messages.ts

@@ -5,6 +5,21 @@ import type { BashCommandContext, PermissionCheckResult } from "./types";
 
 export const EXTENSION_TAG = `[${EXTENSION_ID}]`;
 
+// ── External-path resolved-target disclosure ────────────────────────────────
+
+/** A displayed external path paired with its resolved target, when distinct. */
+export interface ExternalPathDisclosure {
+  /** The path as displayed (typed for tools, lexical-absolute for bash). */
+  path: string;
+  /** The canonical symlink-resolved target; present only when it differs. */
+  resolvedPath?: string;
+}
+
+/** ` (resolves to '<canonical>')` when a distinct target exists, else `""`. */
+export function resolvesToSuffix(resolvedPath?: string): string {
+  return resolvedPath ? ` (resolves to '${resolvedPath}')` : "";
+}
+
 // ── Denial context discriminated union ─────────────────────────────────────
 
 export type DenialContext =
@@ -24,13 +39,14 @@ export type DenialContext =
       kind: "external_directory";
       toolName: string;
       pathValue: string;
+      resolvedPath?: string;
       cwd: string;
       agentName?: string;
     }
   | {
       kind: "bash_external_directory";
       command: string;
-      externalPaths: string[];
+      externalPaths: ExternalPathDisclosure[];
       cwd: string;
       agentName?: string;
     }
@@ -89,9 +105,9 @@ function buildDenyBody(ctx: DenialContext): string {
     case "path":
       return `${subject(ctx.agentName)} is not permitted to access path '${ctx.pathValue}' via tool '${ctx.toolName}'.`;
     case "external_directory":
-      return `${subject(ctx.agentName)} is not permitted to run tool '${ctx.toolName}' for path '${ctx.pathValue}' outside working directory '${ctx.cwd}'.`;
+      return `${subject(ctx.agentName)} is not permitted to run tool '${ctx.toolName}' for path '${ctx.pathValue}'${resolvesToSuffix(ctx.resolvedPath)} outside working directory '${ctx.cwd}'.`;
     case "bash_external_directory":
-      return `${subject(ctx.agentName)} is not permitted to run bash command '${ctx.command}' which references path(s) outside working directory '${ctx.cwd}': ${ctx.externalPaths.join(", ")}.`;
+      return `${subject(ctx.agentName)} is not permitted to run bash command '${ctx.command}' which references path(s) outside working directory '${ctx.cwd}': ${formatExternalPathList(ctx.externalPaths)}.`;
     case "bash_path":
       return `${subject(ctx.agentName)} is not permitted to access path '${ctx.pathValue}' via tool 'bash'.`;
     case "skill_read":
@@ -185,7 +201,7 @@ function buildUnavailableBody(ctx: DenialContext): string {
     case "path":
       return `Accessing '${ctx.pathValue}' requires approval, but no interactive UI is available.`;
     case "external_directory":
-      return `Accessing '${ctx.pathValue}' outside the working directory requires approval, but no interactive UI is available.`;
+      return `Accessing '${ctx.pathValue}'${resolvesToSuffix(ctx.resolvedPath)} outside the working directory requires approval, but no interactive UI is available.`;
     case "bash_external_directory":
       return `Bash command '${ctx.command}' references path(s) outside the working directory and requires approval, but no interactive UI is available.`;
     case "bash_path":
@@ -215,7 +231,7 @@ function buildUserDeniedBody(
     case "path":
       return `User denied access to path '${ctx.pathValue}'.${reasonSuffix(denialReason)}`;
     case "external_directory":
-      return `User denied external directory access for tool '${ctx.toolName}' path '${ctx.pathValue}'.${reasonSuffix(denialReason)}`;
+      return `User denied external directory access for tool '${ctx.toolName}' path '${ctx.pathValue}'${resolvesToSuffix(ctx.resolvedPath)}.${reasonSuffix(denialReason)}`;
     case "bash_external_directory":
       return `User denied external directory access for bash command '${ctx.command}'.${reasonSuffix(denialReason)}`;
     case "bash_path":
@@ -230,3 +246,10 @@ function buildUserDeniedBody(
 function isMcpCheck(check: PermissionCheckResult): boolean {
   return (check.source === "mcp" || check.toolName === "mcp") && !!check.target;
 }
+
+/** Render an external-path disclosure list for the bash deny body's path clause. */
+function formatExternalPathList(paths: ExternalPathDisclosure[]): string {
+  return paths
+    .map(({ path, resolvedPath }) => `${path}${resolvesToSuffix(resolvedPath)}`)
+    .join(", ");
+}

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

@@ -67,9 +67,14 @@ export function describeBashExternalDirectoryGate(
   // config-level "deny" is preserved (not downgraded to the catch-all "ask").
   const preCheck = worstCheck ?? uncoveredEntries[0].check;
 
+  const disclosures = uncoveredEntries.map(({ path }) => ({
+    path: path.value(),
+    resolvedPath: path.resolvedAlias(),
+  }));
+
   const bashExtMessage = formatBashExternalDirectoryAskPrompt(
     command,
-    uncoveredPaths,
+    disclosures,
     tcc.cwd,
     tcc.agentName ?? undefined,
   );
@@ -82,7 +87,7 @@ export function describeBashExternalDirectoryGate(
     denialContext: {
       kind: "bash_external_directory",
       command,
-      externalPaths: uncoveredPaths,
+      externalPaths: disclosures,
       cwd: tcc.cwd,
       agentName: tcc.agentName ?? undefined,
     },

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

@@ -1,20 +1,28 @@
+import {
+  type ExternalPathDisclosure,
+  resolvesToSuffix,
+} from "#src/denial-messages";
+
 export function formatExternalDirectoryAskPrompt(
   toolName: string,
   pathValue: string,
+  resolvedPath: string | undefined,
   cwd: string,
   agentName?: string,
 ): string {
   const subject = agentName ? `Agent '${agentName}'` : "Current agent";
-  return `${subject} requested tool '${toolName}' for path '${pathValue}' outside working directory '${cwd}'. Allow this external directory access?`;
+  return `${subject} requested tool '${toolName}' for path '${pathValue}'${resolvesToSuffix(resolvedPath)} outside working directory '${cwd}'. Allow this external directory access?`;
 }
 
 export function formatBashExternalDirectoryAskPrompt(
   command: string,
-  externalPaths: string[],
+  externalPaths: ExternalPathDisclosure[],
   cwd: string,
   agentName?: string,
 ): string {
   const subject = agentName ? `Agent '${agentName}'` : "Current agent";
-  const pathList = externalPaths.join(", ");
+  const pathList = externalPaths
+    .map(({ path, resolvedPath }) => `${path}${resolvesToSuffix(resolvedPath)}`)
+    .join(", ");
   return `${subject} requested bash command '${command}' which references path(s) outside working directory '${cwd}': ${pathList}. Allow this external directory access?`;
 }

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

@@ -1,9 +1,9 @@
 import type { PathNormalizer } from "#src/path-normalizer";
-import { getToolInputPath } from "#src/path-utils";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
+import { getToolInputPath } from "#src/tool-input-path";
 import type { GateResult } from "./descriptor";
 import { formatExternalDirectoryAskPrompt } from "./external-directory-messages";
 import { resolveExternalDirectoryPolicy } from "./external-directory-policy";
@@ -67,9 +67,11 @@ export function describeExternalDirectoryGate(
   }
 
   // ── Build descriptor for permission check ───────────────────────────────
+  const resolvedAlias = accessPath.resolvedAlias();
   const extDirMessage = formatExternalDirectoryAskPrompt(
     tcc.toolName,
     externalDirectoryPath,
+    resolvedAlias,
     tcc.cwd,
     tcc.agentName ?? undefined,
   );
@@ -90,6 +92,7 @@ export function describeExternalDirectoryGate(
       kind: "external_directory",
       toolName: tcc.toolName,
       pathValue: externalDirectoryPath,
+      resolvedPath: resolvedAlias,
       cwd: tcc.cwd,
       agentName: tcc.agentName ?? undefined,
     },

package/src/handlers/gates/path.ts

@@ -1,9 +1,9 @@
 import type { PathNormalizer } from "#src/path-normalizer";
-import { getToolInputPath } from "#src/path-utils";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
+import { getToolInputPath } from "#src/tool-input-path";
 import type { GateDescriptor, GateResult } from "./descriptor";
 import type { ToolCallContext } from "./types";
 

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

@@ -1,11 +1,11 @@
 import type { AccessPath } from "#src/access-intent/access-path";
 import { BashProgram } from "#src/access-intent/bash/program";
 import type { PathNormalizer } from "#src/path-normalizer";
-import { getPathBearingToolPath } from "#src/path-utils";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
 import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
 import type { ToolInputFormatterLookup } from "#src/tool-input-formatter-registry";
+import { getPathBearingToolPath } from "#src/tool-input-path";
 import {
   ToolPreviewFormatter,
   type ToolPreviewFormatterOptions,

package/src/handlers/gates/tool.ts

@@ -1,8 +1,9 @@
 import type { AccessPath } from "#src/access-intent/access-path";
-import { getPathBearingToolPath, PATH_BEARING_TOOLS } from "#src/path-utils";
+import { PATH_BEARING_TOOLS } from "#src/path-surfaces";
 import { suggestSessionPattern } from "#src/pattern-suggest";
 import { formatAskPrompt } from "#src/permission-prompts";
 import { SessionApproval } from "#src/session-approval";
+import { getPathBearingToolPath } from "#src/tool-input-path";
 import type { ToolPreviewFormatter } from "#src/tool-preview-formatter";
 import type { PermissionCheckResult } from "#src/types";
 import type { GateDescriptor } from "./descriptor";

package/src/input-normalizer.ts

@@ -2,7 +2,7 @@ import type { AccessIntent } from "./access-intent/access-intent";
 import { stripBashCommentLines } from "./bash-arity";
 import { createMcpPermissionTargets } from "./mcp-targets";
 import type { PathNormalizer } from "./path-normalizer";
-import { PATH_SURFACES } from "./path-utils";
+import { PATH_SURFACES } from "./path-surfaces";
 import { getNonEmptyString, toRecord } from "./value-guards";
 
 /**

package/src/path-containment.ts

@@ -0,0 +1,56 @@
+import { posix as posixPath, win32 as winPath } from "node:path";
+
+import { isSafeSystemPath } from "./safe-system-paths";
+
+/**
+ * Returns true when `pathValue` is `directory` itself or nested inside it.
+ *
+ * Containment is decided with Node's platform-native `path.relative` rather
+ * than a hand-rolled prefix check: on `win32` the comparison folds case (and
+ * tolerates either separator), matching the case-insensitive filesystem.
+ * `platform` is injected from the composition root so Windows behavior is
+ * testable on a POSIX CI.
+ */
+export function isPathWithinDirectory(
+  pathValue: string,
+  directory: string,
+  platform: NodeJS.Platform,
+): boolean {
+  if (!pathValue || !directory) {
+    return false;
+  }
+
+  if (pathValue === directory) {
+    return true;
+  }
+
+  const impl = platform === "win32" ? winPath : posixPath;
+  const rel = impl.relative(directory, pathValue);
+  return (
+    rel !== "" &&
+    rel !== ".." &&
+    !rel.startsWith(`..${impl.sep}`) &&
+    !impl.isAbsolute(rel)
+  );
+}
+
+/**
+ * Pure geometry: is `canonicalPath` outside `canonicalCwd`?
+ *
+ * Both operands must already be canonical (symlink-resolved, win32-lowercased)
+ * — the caller prepares them (see {@link PathNormalizer.isOutsideWorkingDirectory}).
+ * This predicate touches no filesystem and does no derivation.
+ */
+export function isPathOutsideWorkingDirectory(
+  canonicalPath: string,
+  canonicalCwd: string,
+  platform: NodeJS.Platform,
+): boolean {
+  if (!canonicalCwd || !canonicalPath) {
+    return false;
+  }
+  if (isSafeSystemPath(canonicalPath)) {
+    return false;
+  }
+  return !isPathWithinDirectory(canonicalPath, canonicalCwd, platform);
+}

package/src/path-normalizer.ts

@@ -1,12 +1,15 @@
 import { posix as posixPath, win32 as winPath } from "node:path";
 
 import { AccessPath } from "./access-intent/access-path";
+import {
+  canonicalNormalizePathForComparison,
+  normalizePathForComparison,
+} from "./access-intent/path-normalization";
 import {
   isPathOutsideWorkingDirectory,
   isPathWithinDirectory,
-  isPiInfrastructureRead,
-  normalizePathForComparison,
-} from "./path-utils";
+} from "./path-containment";
+import { isPiInfrastructureRead } from "./pi-infrastructure-read";
 
 /**
  * Path-interpretation collaborator, constructed once at the session edge with
@@ -19,16 +22,19 @@ import {
  * prepared {@link AccessPath} values, instead of reading `process.platform`
  * ambiently or threading `cwd` through every call. Internally it selects the
  * `win32`/`posix` path flavor once and delegates to the platform-parameterized
- * `path-utils` / `AccessPath` primitives.
+ * `path-containment` / `path-normalization` / `AccessPath` primitives.
  */
 export class PathNormalizer {
   private readonly impl: typeof posixPath;
+  /** Canonical form of the baked cwd, resolved once (the symlink target is stable per session). */
+  private readonly canonicalCwd: string;
 
   constructor(
     private readonly platform: NodeJS.Platform,
     private readonly cwd: string,
   ) {
     this.impl = platform === "win32" ? winPath : posixPath;
+    this.canonicalCwd = canonicalNormalizePathForComparison(cwd, cwd, platform);
   }
 
   /** Build an AccessPath for a token, resolved against `resolveBase` (default cwd). */
@@ -67,7 +73,16 @@ export class PathNormalizer {
 
   /** Canonical (symlink-resolved) outside-cwd test against the baked cwd. */
   isOutsideWorkingDirectory(pathValue: string): boolean {
-    return isPathOutsideWorkingDirectory(pathValue, this.cwd, this.platform);
+    const canonicalPath = canonicalNormalizePathForComparison(
+      pathValue,
+      this.cwd,
+      this.platform,
+    );
+    return isPathOutsideWorkingDirectory(
+      canonicalPath,
+      this.canonicalCwd,
+      this.platform,
+    );
   }
 
   /**

package/src/path-surfaces.ts

@@ -0,0 +1,30 @@
+/**
+ * File tools that only read — never write — the filesystem.
+ * Only these tools are eligible for the Pi infrastructure auto-allow.
+ */
+export const READ_ONLY_PATH_BEARING_TOOLS: ReadonlySet<string> = new Set([
+  "read",
+  "find",
+  "grep",
+  "ls",
+]);
+
+export const PATH_BEARING_TOOLS = new Set([
+  "read",
+  "write",
+  "edit",
+  "find",
+  "grep",
+  "ls",
+]);
+
+/**
+ * Surfaces whose patterns are matched against filesystem paths and therefore
+ * fold case (and separators) on Windows: the path-bearing tools plus the
+ * cross-cutting `path` gate and the `external_directory` boundary gate.
+ */
+export const PATH_SURFACES: ReadonlySet<string> = new Set([
+  ...PATH_BEARING_TOOLS,
+  "external_directory",
+  "path",
+]);

package/src/pattern-suggest.ts

@@ -1,5 +1,5 @@
 import { prefix, stripBashCommentLines } from "./bash-arity";
-import { PATH_BEARING_TOOLS } from "./path-utils";
+import { PATH_BEARING_TOOLS } from "./path-surfaces";
 import { deriveApprovalPattern } from "./session-rules";
 
 /** The suggestion returned for a "Yes, for this session" dialog option. */

package/src/permission-manager.ts

@@ -7,7 +7,7 @@ import {
 } from "./config-paths";
 import { normalizeInput } from "./input-normalizer";
 import { normalizeFlatConfig } from "./normalize";
-import { PATH_SURFACES } from "./path-utils";
+import { PATH_SURFACES } from "./path-surfaces";
 import {
   FilePolicyLoader,
   type PolicyLoader,
@@ -249,6 +249,12 @@ export class PermissionManager implements ScopedPermissionManager {
    * extension surfaces). Path-bearing surfaces arrive as `"path-values"` via
    * the access-path gate (#502) or service/RPC builder (#503).
    * `"path-values"` → evaluates the precomputed values directly.
+   *
+   * The manager stays string-based by design: it consumes `ResolvedAccessIntent`
+   * (`tool | path-values`) and never imports `AccessPath`. This deliberate
+   * boundary is formalized in ADR-0002
+   * (`docs/decisions/0002-path-values-string-boundary.md`) and guarded by a
+   * `no-restricted-imports` lint rule on this file.
    */
   check(
     intent: ResolvedAccessIntent,

package/src/permission-resolver.ts

@@ -26,6 +26,11 @@ export interface ScopedPermissionResolver {
  *
  * Tell-Don't-Ask: the resolver asks an `AccessPath` for its `matchValues()`,
  * so the low-level manager never imports the value object.
+ *
+ * This is the sole `matchValues()` unwrap site — the single place the lexical ∪
+ * canonical alias set (#418) is derived. Keeping it here (not in the manager)
+ * is the deliberate boundary formalized in ADR-0002
+ * (`docs/decisions/0002-path-values-string-boundary.md`).
  */
 function toResolvedIntent(intent: AccessIntent): ResolvedAccessIntent {
   if (intent.kind === "access-path") {