@gotgenes/pi-permission-system 16.0.2 → 16.1.0

package/CHANGELOG.md

@@ -5,6 +5,13 @@ 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).
 
+## [16.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v16.0.2...pi-permission-system-v16.1.0) (2026-06-26)
+
+
+### Features
+
+* **pi-permission-system:** introduce AccessPath value object ([c00d5c5](https://github.com/gotgenes/pi-packages/commit/c00d5c580a828234fafd7946be4e81313665d25d)), closes [#476](https://github.com/gotgenes/pi-packages/issues/476)
+
 ## [16.0.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v16.0.1...pi-permission-system-v16.0.2) (2026-06-25)
 
 

package/package.json

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

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

@@ -0,0 +1,88 @@
+import {
+  canonicalNormalizePathForComparison,
+  getPathPolicyValues,
+  normalizePathForComparison,
+} from "#src/path-utils";
+
+/**
+ * A path's two representations held behind type-distinct accessors.
+ *
+ * A single `string` carrying both meanings was the root cause of [#418]:
+ * both external-directory gates matched config patterns against the
+ * symlink-resolved (canonical) path instead of the typed (lexical) path,
+ * defeating a configured `/tmp/*` allow.
+ *
+ * `AccessPath` makes the misuse a compile error:
+ * - {@link matchValues} returns `string[]` — the lexical alias union ∪ canonical,
+ *   for `external_directory` pattern matching.
+ * - {@link boundaryValue} returns `string` — the canonical form, for
+ *   outside-CWD containment and infra-read checks.
+ * - {@link value} returns `string` — the lexical absolute form, for display,
+ *   approval patterns, decision values, and logs.
+ *
+ * Construct via {@link forExternalDirectory}; the constructor is private.
+ */
+export class AccessPath {
+  private constructor(
+    private readonly lexical: string,
+    private readonly matchAliases: readonly string[],
+    private readonly canonical: string,
+  ) {}
+
+  /**
+   * Pattern-match values for the `external_directory` surface: the lexical
+   * alias union plus the canonical alias, so a config pattern on either the
+   * typed form (`/tmp/*`) or the symlink-resolved form (`/private/tmp/*`)
+   * matches (#418).
+   *
+   * Collapses to the lexical aliases when the canonical equals one of them
+   * (e.g. when the path is not a symlink).
+   */
+  matchValues(): string[] {
+    return this.canonical
+      ? [...new Set([...this.matchAliases, this.canonical])]
+      : [...this.matchAliases];
+  }
+
+  /**
+   * Canonical (symlink-resolved, win32-lowercased) form, for the outside-CWD
+   * boundary decision and Pi infrastructure-read containment checks.
+   *
+   * Returns `""` when the path could not be resolved (empty input).
+   */
+  boundaryValue(): string {
+    return this.canonical;
+  }
+
+  /**
+   * Lexical (as-typed, normalized but not symlink-resolved) form, for display,
+   * approval patterns, decision values, and log messages.
+   *
+   * Returns `""` for empty input.
+   */
+  value(): string {
+    return this.lexical;
+  }
+
+  /**
+   * Build an `AccessPath` for a tool-input or bash-token path resolved against
+   * `cwd`.
+   *
+   * - `matchValues()` returns the same set as the former
+   *   `getExternalDirectoryPolicyValues(pathValue, cwd)` — the lexical alias
+   *   union from `getPathPolicyValues` plus the canonical alias from
+   *   `canonicalNormalizePathForComparison` (#418).
+   * - `boundaryValue()` returns `canonicalNormalizePathForComparison(pathValue, cwd)`,
+   *   which is win32-lowercased (#382) — do not substitute a raw
+   *   `canonicalizePath` output here.
+   * - `value()` returns `normalizePathForComparison(pathValue, cwd)`, the
+   *   absolute lexical form.
+   */
+  static forExternalDirectory(pathValue: string, cwd: string): AccessPath {
+    return new AccessPath(
+      normalizePathForComparison(pathValue, cwd),
+      getPathPolicyValues(pathValue, { cwd }),
+      canonicalNormalizePathForComparison(pathValue, cwd),
+    );
+  }
+}

package/src/access-intent/bash/cwd-projection.ts

@@ -1,4 +1,5 @@
 import { isAbsolute, join, resolve } from "node:path";
+import { AccessPath } from "#src/access-intent/access-path";
 import {
   ARG_NODE_TYPES,
   SKIP_SUBTREE_TYPES,
@@ -409,11 +410,11 @@ function getPolicyValuesForRuleCandidate(
 export function projectExternalPaths(
   candidates: readonly PathCandidate[],
   cwd: string,
-): string[] {
+): AccessPath[] {
   const normalizedCwd = canonicalizePath(normalizePathForComparison(cwd, cwd));
 
   const seen = new Set<string>();
-  const externalPaths: string[] = [];
+  const externalPaths: AccessPath[] = [];
 
   for (const { token, base } of candidates) {
     const candidate = classifyTokenAsPathCandidate(token);
@@ -432,7 +433,9 @@ export function projectExternalPaths(
         !seen.has(canonical)
       ) {
         seen.add(canonical);
-        externalPaths.push(lexical);
+        // The factory recomputes the canonical via canonicalNormalizePathForComparison
+        // (win32-lowercased, #382) rather than reusing the raw canonicalizePath output.
+        externalPaths.push(AccessPath.forExternalDirectory(lexical, cwd));
       }
       continue;
     }
@@ -452,7 +455,9 @@ export function projectExternalPaths(
       !seen.has(canonical)
     ) {
       seen.add(canonical);
-      externalPaths.push(lexical);
+      // The factory recomputes the canonical via canonicalNormalizePathForComparison
+      // (win32-lowercased, #382) rather than reusing the raw canonicalizePath output.
+      externalPaths.push(AccessPath.forExternalDirectory(lexical, cwd));
     }
   }
 

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

@@ -1,3 +1,4 @@
+import type { AccessPath } from "#src/access-intent/access-path";
 import {
   type BashCommand,
   collectCommands,
@@ -25,7 +26,7 @@ export type { BashCommand, BashPathRuleCandidate };
 export class BashProgram {
   private constructor(
     private readonly commandUnits: readonly BashCommand[],
-    private readonly resolvedExternalPaths: readonly string[],
+    private readonly resolvedExternalPaths: readonly AccessPath[],
     private readonly resolvedRuleCandidates: readonly BashPathRuleCandidate[],
   ) {}
 
@@ -73,16 +74,15 @@ export class BashProgram {
   }
 
   /**
-   * Deduplicated paths that resolve outside `cwd`, in their lexical (as-typed,
-   * normalized but not symlink-resolved) form.
+   * Deduplicated paths that resolve outside `cwd`, as {@link AccessPath} value
+   * objects holding both the lexical (as-typed) and canonical (symlink-resolved)
+   * forms behind distinct accessors.
    *
    * Resolved eagerly at parse time against the `cwd` supplied to `parse()`.
-   * The outside-`cwd` decision and the dedup identity use the canonical
-   * (symlink-resolved) form, but the returned value is the lexical form so
-   * `external_directory` config patterns match the path as the user typed it
-   * (#418); the gate re-derives the canonical alias for matching.
+   * Use `.matchValues()` for `external_directory` pattern matching and
+   * `.boundaryValue()` for containment checks; `.value()` for display and logs.
    */
-  externalPaths(): string[] {
+  externalPaths(): AccessPath[] {
     return [...this.resolvedExternalPaths];
   }
 

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

@@ -1,13 +1,11 @@
 import type { BashProgram } from "#src/access-intent/bash/program";
 import { getNonEmptyString, toRecord } from "#src/common";
-import { getExternalDirectoryPolicyValues } 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 { PermissionCheckResult } from "#src/types";
-import { pickMostRestrictive } from "./candidate-check";
 import type { GateResult } from "./descriptor";
 import { formatBashExternalDirectoryAskPrompt } from "./external-directory-messages";
+import { selectUncoveredExternalPaths } from "./external-directory-policy";
 import type { ToolCallContext } from "./types";
 
 /**
@@ -34,27 +32,17 @@ export function describeBashExternalDirectoryGate(
   const externalPaths = bashProgram.externalPaths();
   if (externalPaths.length === 0) return null;
 
-  // Collect paths whose resolved state is not already "allow".
-  // Checking state (not source) ensures config-level allow rules (source: "special")
-  // suppress the prompt just as session-level allow rules (source: "session") do.
-  const uncoveredEntries: Array<{
-    path: string;
-    check: PermissionCheckResult;
-  }> = [];
-  for (const p of externalPaths) {
-    // Match each path against both its typed and symlink-resolved aliases on
-    // the external_directory surface, so a config pattern on either form
-    // applies (#418).
-    const check = resolver.resolvePathPolicy(
-      getExternalDirectoryPolicyValues(p, tcc.cwd),
+  // Resolve every external path on the external_directory surface and keep the
+  // ones not already allowed (config-level allows suppress the prompt just as
+  // session-level allows do); the shared helper single-sources the #418 alias
+  // matching and the worst-uncovered selection.
+  const { uncovered: uncoveredEntries, worstCheck } =
+    selectUncoveredExternalPaths(
+      externalPaths,
+      resolver,
       tcc.agentName ?? undefined,
-      "external_directory",
     );
-    if (check.state !== "allow") {
-      uncoveredEntries.push({ path: p, check });
-    }
-  }
-  const uncoveredPaths = uncoveredEntries.map(({ path }) => path);
+  const uncoveredPaths = uncoveredEntries.map(({ path }) => path.value());
 
   if (uncoveredPaths.length === 0) {
     return {
@@ -67,19 +55,17 @@ export function describeBashExternalDirectoryGate(
           toolName: tcc.toolName,
           agentName: tcc.agentName,
           command,
-          externalPaths,
+          externalPaths: externalPaths.map((p) => p.value()),
           resolution: "session_approved",
         },
       },
     };
   }
 
-  // Use the most restrictive check among uncovered paths as the pre-check result.
-  // This ensures a config-level "deny" rule is not downgraded to "ask" by the
-  // generic "*" catch-all that the old path-less checkPermission call returned.
-  const worstCheck =
-    pickMostRestrictive(uncoveredEntries.map(({ check }) => check)) ??
-    uncoveredEntries[0].check;
+  // After the early bypass, at least one path is uncovered, so worstCheck is
+  // defined; the fallback keeps TypeScript happy across the early return. A
+  // config-level "deny" is preserved (not downgraded to the catch-all "ask").
+  const preCheck = worstCheck ?? uncoveredEntries[0].check;
 
   const bashExtMessage = formatBashExternalDirectoryAskPrompt(
     command,
@@ -122,6 +108,6 @@ export function describeBashExternalDirectoryGate(
       surface: "external_directory",
       value: command,
     },
-    preCheck: worstCheck,
+    preCheck,
   };
 }

package/src/handlers/gates/bash-path-extractor.ts

@@ -4,12 +4,18 @@ import { BashProgram } from "#src/access-intent/bash/program";
  * Extract paths from a bash command string that resolve outside CWD.
  *
  * Thin facade over {@link BashProgram.externalPaths}; parses the command and
- * returns the cd-aware external paths. See `BashProgram` for the parsing and
- * resolution semantics.
+ * returns the cd-aware external paths in their lexical (as-typed) string form.
+ * See `BashProgram` for the parsing and resolution semantics.
+ *
+ * Returns `string[]` (not `AccessPath[]`) so the large projection-correctness
+ * test suite in `bash-external-directory.test.ts` can assert path values
+ * without migrating every call site.
  */
 export async function extractExternalPathsFromBashCommand(
   command: string,
   cwd: string,
 ): Promise<string[]> {
-  return (await BashProgram.parse(command, cwd)).externalPaths();
+  return (await BashProgram.parse(command, cwd))
+    .externalPaths()
+    .map((p) => p.value());
 }

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

@@ -0,0 +1,65 @@
+import type { AccessPath } from "#src/access-intent/access-path";
+import type { ScopedPermissionResolver } from "#src/permission-resolver";
+import type { PermissionCheckResult } from "#src/types";
+import { pickMostRestrictive } from "./candidate-check";
+
+/** An external path whose resolved `external_directory` state is not "allow". */
+export interface UncoveredExternalPath {
+  path: AccessPath;
+  check: PermissionCheckResult;
+}
+
+/** The uncovered external paths plus the most restrictive check among them. */
+export interface UncoveredExternalPaths {
+  uncovered: UncoveredExternalPath[];
+  /** Worst check among uncovered paths; `undefined` only when none are uncovered. */
+  worstCheck: PermissionCheckResult | undefined;
+}
+
+/**
+ * Resolve one external path's policy on the `external_directory` surface.
+ *
+ * Matches against the typed and symlink-resolved aliases
+ * ({@link AccessPath.matchValues}) so a config pattern on either form applies
+ * (#418). This is the single source for the alias-derivation plus
+ * surface-tagged resolve that the two external-directory gates previously
+ * duplicated.
+ */
+export function resolveExternalDirectoryPolicy(
+  path: AccessPath,
+  resolver: ScopedPermissionResolver,
+  agentName: string | undefined,
+): PermissionCheckResult {
+  return resolver.resolvePathPolicy(
+    path.matchValues(),
+    agentName,
+    "external_directory",
+  );
+}
+
+/**
+ * Resolve a set of external paths and select those not already allowed.
+ *
+ * Each path is resolved via {@link resolveExternalDirectoryPolicy}; entries
+ * whose state is not "allow" are collected (filtering on state, not source, so
+ * config-level allow rules suppress the prompt just as session-level allow
+ * rules do), and the most restrictive uncovered check is returned so a config
+ * "deny" is not downgraded to the catch-all "ask".
+ */
+export function selectUncoveredExternalPaths(
+  paths: readonly AccessPath[],
+  resolver: ScopedPermissionResolver,
+  agentName: string | undefined,
+): UncoveredExternalPaths {
+  const uncovered: UncoveredExternalPath[] = [];
+  for (const path of paths) {
+    const check = resolveExternalDirectoryPolicy(path, resolver, agentName);
+    if (check.state !== "allow") {
+      uncovered.push({ path, check });
+    }
+  }
+  return {
+    uncovered,
+    worstCheck: pickMostRestrictive(uncovered.map(({ check }) => check)),
+  };
+}

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

@@ -1,6 +1,5 @@
+import { AccessPath } from "#src/access-intent/access-path";
 import {
-  canonicalNormalizePathForComparison,
-  getExternalDirectoryPolicyValues,
   getToolInputPath,
   isPathOutsideWorkingDirectory,
   isPiInfrastructureRead,
@@ -12,6 +11,7 @@ import { deriveApprovalPattern } from "#src/session-rules";
 import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
 import type { GateResult } from "./descriptor";
 import { formatExternalDirectoryAskPrompt } from "./external-directory-messages";
+import { resolveExternalDirectoryPolicy } from "./external-directory-policy";
 import type { ToolCallContext } from "./types";
 
 /**
@@ -42,10 +42,11 @@ export function describeExternalDirectoryGate(
   // 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 canonicalExtPath = canonicalNormalizePathForComparison(
+  const accessPath = AccessPath.forExternalDirectory(
     externalDirectoryPath,
     tcc.cwd,
   );
+  const canonicalExtPath = accessPath.boundaryValue();
 
   // ── Pi infrastructure read bypass ──────────────────────────────────────
   if (
@@ -83,13 +84,11 @@ export function describeExternalDirectoryGate(
     tcc.agentName ?? undefined,
   );
 
-  // Match against both the typed and symlink-resolved aliases on the
-  // external_directory surface, so a config pattern on either form applies
-  // (#418). The runner consumes this preCheck and skips its own resolve.
-  const preCheck = resolver.resolvePathPolicy(
-    getExternalDirectoryPolicyValues(externalDirectoryPath, tcc.cwd),
+  // The runner consumes this preCheck and skips its own resolve.
+  const preCheck = resolveExternalDirectoryPolicy(
+    accessPath,
+    resolver,
     tcc.agentName ?? undefined,
-    "external_directory",
   );
   const pattern = deriveApprovalPattern(
     normalizePathForComparison(externalDirectoryPath, tcc.cwd),

package/src/path-utils.ts

@@ -112,26 +112,6 @@ export function getPathPolicyValues(
   ];
 }
 
-/**
- * Equivalent `external_directory` policy-match values for a path: the lexical
- * (as-typed) alias list plus the canonical (symlink-resolved) absolute path.
- *
- * The outside-CWD boundary decision uses the canonical form separately; this
- * helper exists only for pattern matching, so a user's pattern on the typed
- * path (`/tmp/*`) and on the resolved path (`/private/tmp/*`) both match under
- * the last-match-wins alias evaluation. On systems where the path is not a
- * symlink the canonical form equals the lexical absolute alias and the `Set`
- * collapses it, leaving today's behavior unchanged.
- */
-export function getExternalDirectoryPolicyValues(
-  pathValue: string,
-  cwd: string,
-): string[] {
-  const lexical = getPathPolicyValues(pathValue, { cwd });
-  const canonical = canonicalNormalizePathForComparison(pathValue, cwd);
-  return canonical ? [...new Set([...lexical, canonical])] : lexical;
-}
-
 function getAbsolutePathPolicyValues(
   pathValue: string,
   options: PathPolicyValueOptions,

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

@@ -0,0 +1,107 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+// Mock node:os so tilde-expansion is deterministic across platforms.
+vi.mock("node:os", () => {
+  const homedir = vi.fn(() => "/mock/home");
+  return {
+    homedir,
+    default: { homedir },
+  };
+});
+
+// Mock node:fs so realpathSync (used by canonicalizePath) is controllable.
+// Default implementation is identity — lexical tests are unaffected.
+const realpathSync = vi.hoisted(() =>
+  vi.fn<(path: string) => string>((p) => p),
+);
+vi.mock("node:fs", () => ({
+  realpathSync,
+  default: { realpathSync },
+}));
+
+import { AccessPath } from "#src/access-intent/access-path";
+
+describe("AccessPath.forExternalDirectory", () => {
+  const cwd = "/projects/my-app";
+
+  beforeEach(() => {
+    realpathSync.mockReset();
+    realpathSync.mockImplementation((p: string) => p);
+  });
+
+  describe("matchValues()", () => {
+    test("adds the symlink-resolved alias alongside the typed path", () => {
+      // /tmp -> /private/tmp (the macOS symlink from the bug report, #418).
+      realpathSync.mockImplementation((p: string) =>
+        p.startsWith("/tmp") ? `/private${p}` : p,
+      );
+      expect(
+        AccessPath.forExternalDirectory("/tmp/x", cwd).matchValues(),
+      ).toEqual(["/tmp/x", "/private/tmp/x"]);
+    });
+
+    test("deduplicates when the canonical form equals the lexical form", () => {
+      expect(
+        AccessPath.forExternalDirectory("/etc/hosts", cwd).matchValues(),
+      ).toEqual(["/etc/hosts"]);
+    });
+
+    test("keeps the relative aliases for an in-cwd token without duplicating", () => {
+      expect(
+        AccessPath.forExternalDirectory("src/foo.ts", cwd).matchValues(),
+      ).toEqual(["/projects/my-app/src/foo.ts", "src/foo.ts"]);
+    });
+
+    test("includes only the lexical aliases when canonical is empty", () => {
+      // Force canonicalizePath to return the original (no-op symlink resolution
+      // effectively means canonical === lexical, handled by dedup).
+      expect(
+        AccessPath.forExternalDirectory("/etc/hosts", cwd).matchValues(),
+      ).not.toHaveLength(0);
+    });
+  });
+
+  describe("boundaryValue()", () => {
+    test("returns the canonical (symlink-resolved) form", () => {
+      realpathSync.mockImplementation((p: string) =>
+        p.startsWith("/tmp") ? `/private${p}` : p,
+      );
+      expect(
+        AccessPath.forExternalDirectory("/tmp/x", cwd).boundaryValue(),
+      ).toBe("/private/tmp/x");
+    });
+
+    test("returns the lexical form when path has no symlinks", () => {
+      expect(
+        AccessPath.forExternalDirectory("/etc/hosts", cwd).boundaryValue(),
+      ).toBe("/etc/hosts");
+    });
+
+    test("returns empty string for empty input", () => {
+      expect(AccessPath.forExternalDirectory("", cwd).boundaryValue()).toBe("");
+    });
+  });
+
+  describe("value()", () => {
+    test("returns the lexical (as-typed, normalized) form", () => {
+      realpathSync.mockImplementation((p: string) =>
+        p.startsWith("/tmp") ? `/private${p}` : p,
+      );
+      // Even when the path resolves to a different canonical, value() stays lexical.
+      expect(AccessPath.forExternalDirectory("/tmp/x", cwd).value()).toBe(
+        "/tmp/x",
+      );
+    });
+
+    test("normalizes the path against cwd", () => {
+      // A relative path becomes an absolute lexical value.
+      expect(AccessPath.forExternalDirectory("src/foo.ts", cwd).value()).toBe(
+        "/projects/my-app/src/foo.ts",
+      );
+    });
+
+    test("returns empty string for empty input", () => {
+      expect(AccessPath.forExternalDirectory("", cwd).value()).toBe("");
+    });
+  });
+});

package/test/access-intent/bash/program.test.ts

@@ -70,7 +70,9 @@ describe("BashProgram", () => {
     it("returns absolute paths resolving outside cwd", async () => {
       const program = await BashProgram.parse("cat /etc/hosts", cwd);
       // Subset matcher: the path is normalized before comparison.
-      expect(program.externalPaths()).toContain("/etc/hosts");
+      expect(program.externalPaths().map((p) => p.value())).toContain(
+        "/etc/hosts",
+      );
     });
 
     it("excludes paths within cwd", async () => {
@@ -95,7 +97,9 @@ describe("BashProgram", () => {
           "cd nested/deep && cd .. && cat ../../etc/passwd",
           cwd,
         );
-        expect(program.externalPaths()).toContain("/projects/etc/passwd");
+        expect(program.externalPaths().map((p) => p.value())).toContain(
+          "/projects/etc/passwd",
+        );
       });
 
       it("folds a cd that is not the first command", async () => {
@@ -112,13 +116,17 @@ describe("BashProgram", () => {
         // `cd a &` runs in a subshell, so it must not update the running
         // directory; ../b resolves against cwd and escapes.
         const program = await BashProgram.parse("cd a & cat ../b", cwd);
-        expect(program.externalPaths()).toContain("/projects/b");
+        expect(program.externalPaths().map((p) => p.value())).toContain(
+          "/projects/b",
+        );
       });
 
       it("does not fold a cd inside a pipeline", async () => {
         // Pipeline members run in subshells; the cd must not leak.
         const program = await BashProgram.parse("cd nested | cat ../b", cwd);
-        expect(program.externalPaths()).toContain("/projects/b");
+        expect(program.externalPaths().map((p) => p.value())).toContain(
+          "/projects/b",
+        );
       });
 
       it("folds a cd inside a subshell for paths within that subshell", async () => {
@@ -130,7 +138,9 @@ describe("BashProgram", () => {
       it("does not leak a subshell cd to following commands", async () => {
         // The subshell cd resets on exit, so ../y resolves against cwd.
         const program = await BashProgram.parse("( cd sub ) && cat ../y", cwd);
-        expect(program.externalPaths()).toContain("/projects/y");
+        expect(program.externalPaths().map((p) => p.value())).toContain(
+          "/projects/y",
+        );
       });
 
       it("persists a cd inside a brace group to later commands in the group", async () => {
@@ -152,14 +162,18 @@ describe("BashProgram", () => {
           "echo $(cd q && cat ../r)",
           cwd,
         );
-        expect(program.externalPaths()).toContain("/projects/r");
+        expect(program.externalPaths().map((p) => p.value())).toContain(
+          "/projects/r",
+        );
       });
 
       it("flags relative paths conservatively after a non-literal cd", async () => {
         // cd "$DIR" makes the effective dir unknowable; ../x could be anywhere,
         // so it is flagged (least-privilege).
         const program = await BashProgram.parse('cd "$DIR" && cat ../x', cwd);
-        expect(program.externalPaths()).toContain("/projects/x");
+        expect(program.externalPaths().map((p) => p.value())).toContain(
+          "/projects/x",
+        );
       });
 
       it("flags even a within-cwd relative path after a non-literal cd", async () => {
@@ -169,7 +183,7 @@ describe("BashProgram", () => {
           'cd "$DIR" && cat src/../within.txt',
           cwd,
         );
-        expect(program.externalPaths()).toContain(
+        expect(program.externalPaths().map((p) => p.value())).toContain(
           "/projects/my-app/within.txt",
         );
       });
@@ -186,7 +200,9 @@ describe("BashProgram", () => {
 
       it("treats `cd -` as an unknown effective directory", async () => {
         const program = await BashProgram.parse("cd - && cat ../x", cwd);
-        expect(program.externalPaths()).toContain("/projects/x");
+        expect(program.externalPaths().map((p) => p.value())).toContain(
+          "/projects/x",
+        );
       });
 
       it("recovers a known base when a later cd is absolute", async () => {
@@ -233,7 +249,9 @@ describe("BashProgram", () => {
           "cd a && cd b 2>&1 | tail ; cat ../../x",
           cwd,
         );
-        expect(program.externalPaths()).toContain("/projects/x");
+        expect(program.externalPaths().map((p) => p.value())).toContain(
+          "/projects/x",
+        );
       });
 
       it("resolves a downstream pipe stage against the folded base", async () => {
@@ -262,7 +280,7 @@ describe("BashProgram", () => {
         "cat /projects/my-app/link/hosts",
         cwd,
       );
-      const external = program.externalPaths();
+      const external = program.externalPaths().map((p) => p.value());
       expect(external).toContain("/projects/my-app/link/hosts");
       expect(external).not.toContain("/etc/hosts");
     });
@@ -426,7 +444,7 @@ describe("BashProgram", () => {
       ".env",
       "/etc/hosts",
     ]);
-    const external = program.externalPaths();
+    const external = program.externalPaths().map((p) => p.value());
     expect(external).toContain("/etc/hosts");
     expect(external).not.toContain(".env");
   });

package/test/handlers/gates/external-directory-policy.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it } from "vitest";
+import { AccessPath } from "#src/access-intent/access-path";
+import {
+  resolveExternalDirectoryPolicy,
+  selectUncoveredExternalPaths,
+} from "#src/handlers/gates/external-directory-policy";
+import type { PermissionCheckResult } from "#src/types";
+
+import { makeResolver } from "#test/helpers/gate-fixtures";
+
+const cwd = "/test/project";
+
+function makeCheckResult(
+  state: "allow" | "deny" | "ask",
+  overrides: Partial<PermissionCheckResult> = {},
+): PermissionCheckResult {
+  return {
+    state,
+    toolName: "external_directory",
+    source: "special",
+    origin: "builtin",
+    ...overrides,
+  };
+}
+
+describe("resolveExternalDirectoryPolicy", () => {
+  it("resolves the path's match aliases on the external_directory surface (#418)", () => {
+    const path = AccessPath.forExternalDirectory("/outside/a.ts", cwd);
+    const resolver = makeResolver(makeCheckResult("ask"));
+
+    const result = resolveExternalDirectoryPolicy(path, resolver, undefined);
+
+    expect(resolver.resolvePathPolicy).toHaveBeenCalledWith(
+      path.matchValues(),
+      undefined,
+      "external_directory",
+    );
+    expect(result).toEqual(makeCheckResult("ask"));
+  });
+
+  it("threads the agent name through to the resolver", () => {
+    const path = AccessPath.forExternalDirectory("/outside/a.ts", cwd);
+    const resolver = makeResolver(makeCheckResult("allow"));
+
+    resolveExternalDirectoryPolicy(path, resolver, "reviewer");
+
+    expect(resolver.resolvePathPolicy).toHaveBeenCalledWith(
+      path.matchValues(),
+      "reviewer",
+      "external_directory",
+    );
+  });
+});
+
+describe("selectUncoveredExternalPaths", () => {
+  it("returns no uncovered paths when every path resolves to allow", () => {
+    const paths = [
+      AccessPath.forExternalDirectory("/outside/a.ts", cwd),
+      AccessPath.forExternalDirectory("/outside/b.ts", cwd),
+    ];
+    const resolver = makeResolver(makeCheckResult("allow"));
+
+    const { uncovered, worstCheck } = selectUncoveredExternalPaths(
+      paths,
+      resolver,
+      undefined,
+    );
+
+    expect(uncovered).toEqual([]);
+    expect(worstCheck).toBeUndefined();
+  });
+
+  it("collects only paths whose resolved state is not allow", () => {
+    const allowed = AccessPath.forExternalDirectory("/outside/ok.ts", cwd);
+    const asked = AccessPath.forExternalDirectory("/outside/ask.ts", cwd);
+    const resolver = makeResolver();
+    resolver.resolvePathPolicy.mockImplementation(
+      (values: readonly string[]) =>
+        values.includes("/outside/ok.ts")
+          ? makeCheckResult("allow")
+          : makeCheckResult("ask"),
+    );
+
+    const { uncovered } = selectUncoveredExternalPaths(
+      [allowed, asked],
+      resolver,
+      undefined,
+    );
+
+    expect(uncovered.map(({ path }) => path.value())).toEqual([asked.value()]);
+  });
+
+  it("returns the most restrictive uncovered check as worstCheck (deny > ask)", () => {
+    const asked = AccessPath.forExternalDirectory("/outside/ask.ts", cwd);
+    const denied = AccessPath.forExternalDirectory("/outside/deny.ts", cwd);
+    const resolver = makeResolver();
+    resolver.resolvePathPolicy.mockImplementation(
+      (values: readonly string[]) =>
+        values.includes("/outside/deny.ts")
+          ? makeCheckResult("deny")
+          : makeCheckResult("ask"),
+    );
+
+    const { worstCheck } = selectUncoveredExternalPaths(
+      [asked, denied],
+      resolver,
+      undefined,
+    );
+
+    expect(worstCheck?.state).toBe("deny");
+  });
+});

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

@@ -1,5 +1,6 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
+import type { AccessPath } from "#src/access-intent/access-path";
 import { ToolCallGatePipeline } from "#src/handlers/gates/tool-call-gate-pipeline";
 
 import {
@@ -24,7 +25,7 @@ function makeMockBashProgram() {
   return {
     commands: vi.fn<() => []>(() => []),
     pathRuleCandidates: vi.fn<() => []>(() => []),
-    externalPaths: vi.fn<() => []>(() => []),
+    externalPaths: vi.fn<() => AccessPath[]>(() => []),
   };
 }
 

package/test/path-utils.test.ts

@@ -22,7 +22,6 @@ vi.mock("node:fs", () => ({
 
 import {
   canonicalNormalizePathForComparison,
-  getExternalDirectoryPolicyValues,
   getPathBearingToolPath,
   getPathPolicyValues,
   getToolInputPath,
@@ -615,36 +614,3 @@ describe("getPathPolicyValues", () => {
     expect(getPathPolicyValues("   ", { cwd })).toEqual([]);
   });
 });
-
-describe("getExternalDirectoryPolicyValues", () => {
-  const cwd = "/projects/my-app";
-
-  beforeEach(() => {
-    realpathSync.mockReset();
-    realpathSync.mockImplementation((p: string) => p);
-  });
-
-  test("adds the symlink-resolved alias alongside the typed path", () => {
-    // /tmp -> /private/tmp (the macOS symlink from the bug report).
-    realpathSync.mockImplementation((p: string) =>
-      p.startsWith("/tmp") ? `/private${p}` : p,
-    );
-    expect(getExternalDirectoryPolicyValues("/tmp/x", cwd)).toEqual([
-      "/tmp/x",
-      "/private/tmp/x",
-    ]);
-  });
-
-  test("dedups when the canonical form equals the lexical form", () => {
-    expect(getExternalDirectoryPolicyValues("/etc/hosts", cwd)).toEqual([
-      "/etc/hosts",
-    ]);
-  });
-
-  test("keeps the relative aliases for an in-cwd token without duplicating", () => {
-    expect(getExternalDirectoryPolicyValues("src/foo.ts", cwd)).toEqual([
-      "/projects/my-app/src/foo.ts",
-      "src/foo.ts",
-    ]);
-  });
-});