@gotgenes/pi-permission-system 16.2.1 → 17.0.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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).
 
+## [17.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v16.2.1...pi-permission-system-v17.0.0) (2026-06-27)
+
+
+### ⚠ BREAKING CHANGES
+
+* **pi-permission-system:** the path surface now also matches the canonical (symlink-resolved) form of bash path-rule tokens, so a path rule can fire on a symlink alias it previously missed, changing decisions on upgrade with no config edit.
+* **pi-permission-system:** the path surface now also matches the canonical (symlink-resolved) form of a tool's file path. A path rule that previously matched only the as-typed spelling now also matches when the path resolves through a symlink to a target the pattern covers, which can change allow/deny decisions on upgrade with no config edit.
+
+### Features
+
+* **pi-permission-system:** add AccessPath.forPath and forLiteral factories ([4323cae](https://github.com/gotgenes/pi-packages/commit/4323cae859907dd62d9cb401c194443717ab752c)), closes [#486](https://github.com/gotgenes/pi-packages/issues/486)
+* **pi-permission-system:** match the canonical form on the bash-path gate ([6ce0c06](https://github.com/gotgenes/pi-packages/commit/6ce0c06b35c12eca32ffce5d4fe974c2f2dee393))
+* **pi-permission-system:** match the canonical form on the path tool gate ([869ca76](https://github.com/gotgenes/pi-packages/commit/869ca761cf3d7a8367eb932106065a866d996ce4))
+
+
+### Documentation
+
+* **pi-permission-system:** document canonical path-surface matching ([9606dce](https://github.com/gotgenes/pi-packages/commit/9606dce744bc1f95bd8424d2bb115a376d9a1191)), closes [#486](https://github.com/gotgenes/pi-packages/issues/486)
+
 ## [16.2.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v16.2.0...pi-permission-system-v16.2.1) (2026-06-27)
 
 

package/README.md

@@ -17,7 +17,7 @@ Permission enforcement extension for the [Pi](https://pi.mariozechner.at/) codin
 - **Enforces allow / ask / deny** at tool-call time with UI confirmation dialogs
 - **Controls bash commands** with wildcard pattern matching (`git *: ask`, `rm -rf *: deny`)
 - **Gates MCP and skill access** at server, tool, and skill-name granularity
-- **Protects sensitive file patterns** — cross-cutting `path` rules deny `.env`, `~/.ssh/*`, etc. across all tools and bash at once
+- **Protects sensitive file patterns** — cross-cutting `path` rules deny `.env`, `~/.ssh/*`, etc. across all tools and bash at once, matching both the path as referenced and its symlink-resolved form so a deny cannot be evaded through a symlink alias
 - **Guards external paths** — prompts before file tools or bash commands reach outside `cwd`
 - **Fails closed** — an internal gate error blocks the tool (with a `gate_error` review-log entry), and an unparseable bash command — or an opaque `bash -c`/`eval` wrapper — prompts (`ask`) rather than passing silently
 - **Forwards prompts from subagents** — `ask` policies work even in non-UI execution contexts
@@ -69,6 +69,7 @@ See [docs/session-approvals.md](docs/session-approvals.md) for details on sessio
 
 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 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/package.json

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

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

@@ -17,8 +17,9 @@ export interface ToolAccessIntent {
 /**
  * Precomputed equivalent policy values for a path-shaped surface.
  *
- * Used by the bash-path gate (`path` surface), whose cd-resolved lexical
- * `string[]` carry no canonical-boundary notion.
+ * 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}.
  */
 export interface PathValuesAccessIntent {
   kind: "path-values";
@@ -31,9 +32,9 @@ export interface PathValuesAccessIntent {
 /**
  * An `AccessPath` value object for a path-shaped surface.
  *
- * Used by the external-directory gates; lets `AccessPath` flow into the
- * resolver as a first-class variant so the resolver — not the gate — asks it
- * for `matchValues()` (Tell-Don't-Ask).
+ * Emitted by every path gate (the `path` and `external_directory` surfaces);
+ * lets `AccessPath` flow into the resolver as a first-class variant so the
+ * resolver — not the gate — asks it for `matchValues()` (Tell-Don't-Ask).
  */
 export interface AccessPathAccessIntent {
   kind: "access-path";
@@ -42,11 +43,8 @@ export interface AccessPathAccessIntent {
   agentName?: string;
 }
 
-/** What a gate emits — the full three-variant union. */
-export type AccessIntent =
-  | ToolAccessIntent
-  | PathValuesAccessIntent
-  | AccessPathAccessIntent;
+/** What a gate emits — a raw tool input or an `AccessPath`. */
+export type AccessIntent = ToolAccessIntent | AccessPathAccessIntent;
 
 /**
  * What the manager consumes — the `access-path` variant has already been

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

@@ -20,7 +20,9 @@ import {
  * - {@link value} returns `string` — the lexical absolute form, for display,
  *   approval patterns, decision values, and logs.
  *
- * Construct via {@link forExternalDirectory}; the constructor is private.
+ * Construct via {@link forPath} (resolved, with optional cd-folded base) or
+ * {@link forLiteral} (literal-only, for an unknown base); the constructor is
+ * private.
  */
 export class AccessPath {
   private constructor(
@@ -65,24 +67,45 @@ export class AccessPath {
   }
 
   /**
-   * Build an `AccessPath` for a tool-input or bash-token path resolved against
-   * `cwd`.
+   * Build an `AccessPath` for a tool-input or bash-token path, resolved against
+   * `resolveBase` (the cd-folded effective directory; defaults to `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.
+   * Serves every path surface: the tool path gate, the tool external-directory
+   * gate, and the bash path/external-directory gates (which pass a cd-resolved
+   * `resolveBase`).
+   *
+   * - `matchValues()` returns the lexical alias union from `getPathPolicyValues`
+   *   plus the canonical alias from `canonicalNormalizePathForComparison`
+   *   (#418), so a config pattern on either the typed or symlink-resolved form
+   *   matches.
+   * - `boundaryValue()` returns
+   *   `canonicalNormalizePathForComparison(pathValue, resolveBase)`, which is
+   *   win32-lowercased (#382) — do not substitute a raw `canonicalizePath`
+   *   output here.
+   * - `value()` returns `normalizePathForComparison(pathValue, resolveBase)`,
+   *   the absolute lexical form.
    */
-  static forExternalDirectory(pathValue: string, cwd: string): AccessPath {
+  static forPath(
+    pathValue: string,
+    options: { cwd: string; resolveBase?: string },
+  ): AccessPath {
+    const { cwd, resolveBase = cwd } = options;
     return new AccessPath(
-      normalizePathForComparison(pathValue, cwd),
-      getPathPolicyValues(pathValue, { cwd }),
-      canonicalNormalizePathForComparison(pathValue, cwd),
+      normalizePathForComparison(pathValue, resolveBase),
+      getPathPolicyValues(pathValue, { cwd, resolveBase }),
+      canonicalNormalizePathForComparison(pathValue, resolveBase),
     );
   }
+
+  /**
+   * Build a literal-only `AccessPath` for a path whose effective base is
+   * unknown (a relative bash token after a non-literal `cd`).
+   *
+   * Carries no canonical alias and no absolute resolution — `matchValues()` is
+   * `[literal]` (or `[]` when empty) and `boundaryValue()` is `""` — so no
+   * spurious absolute or symlink-resolved rule can match (#393).
+   */
+  static forLiteral(literal: string): AccessPath {
+    return new AccessPath(literal, literal ? [literal] : [], "");
+  }
 }

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

@@ -17,7 +17,6 @@ import {
 } from "#src/access-intent/bash/token-collection";
 import { canonicalizePath } from "#src/canonicalize-path";
 import {
-  getPathPolicyValues,
   isPathWithinDirectory,
   isSafeSystemPath,
   normalizePathForComparison,
@@ -54,8 +53,8 @@ interface PathCandidate {
 export interface BashPathRuleCandidate {
   /** Raw path-like token shown in prompts, logs, and session approvals. */
   readonly token: string;
-  /** Equivalent values used for permission policy matching. */
-  readonly policyValues: readonly string[];
+  /** The path's lexical and canonical forms for permission policy matching. */
+  readonly path: AccessPath;
 }
 
 // ── Walk-time constants ──────────────────────────────────────────────────────
@@ -379,18 +378,20 @@ function isRelativeCandidate(candidate: string): boolean {
   return !candidate.startsWith("/") && !candidate.startsWith("~");
 }
 
-function getPolicyValuesForRuleCandidate(
+function buildRuleCandidatePath(
   candidate: string,
   base: EffectiveBase,
   cwd: string,
-): string[] {
+): AccessPath {
+  // An unknown base + relative candidate stays literal-only: a resolved
+  // absolute or canonical alias would resolve against the wrong directory and
+  // could spuriously match a rule (#393).
   if (base.kind === "unknown" && isRelativeCandidate(candidate)) {
-    const literal = normalizePathPolicyLiteral(candidate);
-    return literal ? [literal] : [];
+    return AccessPath.forLiteral(normalizePathPolicyLiteral(candidate));
   }
 
   const resolveBase = base.kind === "known" ? resolve(cwd, base.offset) : cwd;
-  return getPathPolicyValues(candidate, { cwd, resolveBase });
+  return AccessPath.forPath(candidate, { cwd, resolveBase });
 }
 
 // ── Projection functions ─────────────────────────────────────────────────────
@@ -435,7 +436,7 @@ export function projectExternalPaths(
         seen.add(canonical);
         // The factory recomputes the canonical via canonicalNormalizePathForComparison
         // (win32-lowercased, #382) rather than reusing the raw canonicalizePath output.
-        externalPaths.push(AccessPath.forExternalDirectory(lexical, cwd));
+        externalPaths.push(AccessPath.forPath(lexical, { cwd }));
       }
       continue;
     }
@@ -457,7 +458,7 @@ export function projectExternalPaths(
       seen.add(canonical);
       // The factory recomputes the canonical via canonicalNormalizePathForComparison
       // (win32-lowercased, #382) rather than reusing the raw canonicalizePath output.
-      externalPaths.push(AccessPath.forExternalDirectory(lexical, cwd));
+      externalPaths.push(AccessPath.forPath(lexical, { cwd }));
     }
   }
 
@@ -485,13 +486,14 @@ export function projectRuleCandidates(
     const candidate = classifyTokenAsRuleCandidate(token);
     if (!candidate) continue;
 
-    const policyValues = getPolicyValuesForRuleCandidate(candidate, base, cwd);
-    if (policyValues.length === 0) continue;
+    const path = buildRuleCandidatePath(candidate, base, cwd);
+    const matchValues = path.matchValues();
+    if (matchValues.length === 0) continue;
 
-    const key = policyValues.join("\0");
+    const key = matchValues.join("\0");
     if (seen.has(key)) continue;
     seen.add(key);
-    result.push({ token: candidate, policyValues });
+    result.push({ token: candidate, path });
   }
 
   return result;

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

@@ -1,3 +1,4 @@
+import type { AccessPath } from "#src/access-intent/access-path";
 import type { BashProgram } from "#src/access-intent/bash/program";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
@@ -41,20 +42,20 @@ export function describeBashPathGate(
   const tokens = candidates.map(({ token }) => token);
 
   // Tokens whose resolved state needs a check (deny/ask), paired with the raw
-  // token (prompt/decision display) and its policy values (the first of which
-  // is the canonical absolute path the approval pattern is derived from).
+  // token (prompt/decision display) and its `AccessPath` (whose `value()` is
+  // the lexical absolute path the approval pattern is derived from).
   const uncovered: Array<{
     token: string;
-    policyValues: readonly string[];
+    path: AccessPath;
     check: PermissionCheckResult;
   }> = [];
   let allSessionCovered = true;
 
-  for (const { token, policyValues } of candidates) {
+  for (const { token, path } of candidates) {
     const check = resolver.resolve({
-      kind: "path-values",
+      kind: "access-path",
       surface: "path",
-      values: policyValues,
+      path,
       agentName: tcc.agentName ?? undefined,
     });
 
@@ -71,11 +72,11 @@ export function describeBashPathGate(
     }
 
     if (check.state === "deny") {
-      uncovered.push({ token, policyValues, check });
+      uncovered.push({ token, path, check });
       break; // Short-circuit on deny.
     }
     if (check.state === "ask") {
-      uncovered.push({ token, policyValues, check });
+      uncovered.push({ token, path, check });
     }
   }
 
@@ -108,11 +109,10 @@ export function describeBashPathGate(
   // All tokens evaluate to allow — no restriction.
   if (!worstCheck || !worstToken || !worstEntry) return null;
 
-  // Derive the pattern from the canonical absolute policy value (the cd-aware
-  // resolved path), so it matches the values a later call produces. Falls back
-  // to the raw token only when no base was resolvable (no cwd / unknown cd).
-  const approvalBase = worstEntry.policyValues[0] ?? worstToken;
-  const pattern = deriveApprovalPattern(approvalBase);
+  // Derive the pattern from the lexical absolute form (the cd-aware resolved
+  // path), so it matches the values a later call produces. For an unknown base
+  // (`forLiteral`) `value()` is the raw token.
+  const pattern = deriveApprovalPattern(worstEntry.path.value());
   const askMessage = formatPathAskPrompt(
     tcc.toolName,
     worstToken,

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

@@ -42,10 +42,9 @@ 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 accessPath = AccessPath.forExternalDirectory(
-    externalDirectoryPath,
-    tcc.cwd,
-  );
+  const accessPath = AccessPath.forPath(externalDirectoryPath, {
+    cwd: tcc.cwd,
+  });
   const canonicalExtPath = accessPath.boundaryValue();
 
   // ── Pi infrastructure read bypass ──────────────────────────────────────

package/src/handlers/gates/path.ts

@@ -1,4 +1,5 @@
-import { getToolInputPath, normalizePathForComparison } from "#src/path-utils";
+import { AccessPath } from "#src/access-intent/access-path";
+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";
@@ -22,10 +23,14 @@ export function describePathGate(
   const filePath = getToolInputPath(tcc.toolName, tcc.input, extractors);
   if (!filePath) return null;
 
+  // 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 = AccessPath.forPath(filePath, { cwd: tcc.cwd });
   const check = resolver.resolve({
-    kind: "tool",
+    kind: "access-path",
     surface: "path",
-    input: { path: filePath },
+    path: accessPath,
     agentName: tcc.agentName ?? undefined,
   });
 
@@ -36,10 +41,9 @@ export function describePathGate(
   // "path" key should not trigger path-level prompts (#58).
   if (check.matchedPattern === undefined) return null;
 
-  // Resolve to the canonical (cwd-anchored, absolute) path so the approval
-  // pattern matches the policy values a later call produces.
-  const approvalPath = normalizePathForComparison(filePath, tcc.cwd);
-  const pattern = deriveApprovalPattern(approvalPath);
+  // Derive the approval pattern from the lexical absolute form so it matches
+  // the policy values a later call produces.
+  const pattern = deriveApprovalPattern(accessPath.value());
 
   const descriptor: GateDescriptor = {
     surface: "path",

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

@@ -21,7 +21,7 @@ vi.mock("node:fs", () => ({
 
 import { AccessPath } from "#src/access-intent/access-path";
 
-describe("AccessPath.forExternalDirectory", () => {
+describe("AccessPath.forPath", () => {
   const cwd = "/projects/my-app";
 
   beforeEach(() => {
@@ -35,30 +35,59 @@ describe("AccessPath.forExternalDirectory", () => {
       realpathSync.mockImplementation((p: string) =>
         p.startsWith("/tmp") ? `/private${p}` : p,
       );
-      expect(
-        AccessPath.forExternalDirectory("/tmp/x", cwd).matchValues(),
-      ).toEqual(["/tmp/x", "/private/tmp/x"]);
+      expect(AccessPath.forPath("/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"]);
+      expect(AccessPath.forPath("/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"]);
+      expect(AccessPath.forPath("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(),
+        AccessPath.forPath("/etc/hosts", { cwd }).matchValues(),
       ).not.toHaveLength(0);
     });
+
+    test("resolves a relative token against an explicit resolveBase", () => {
+      // The cd-folded effective base differs from cwd (the bash-path case).
+      expect(
+        AccessPath.forPath("foo.ts", {
+          cwd,
+          resolveBase: "/projects/my-app/sub",
+        }).matchValues(),
+      ).toEqual(["/projects/my-app/sub/foo.ts", "sub/foo.ts", "foo.ts"]);
+    });
+
+    test("adds the canonical alias resolved against resolveBase", () => {
+      realpathSync.mockImplementation((p: string) =>
+        p === "/projects/my-app/sub/foo.ts" ? "/real/foo.ts" : p,
+      );
+      expect(
+        AccessPath.forPath("foo.ts", {
+          cwd,
+          resolveBase: "/projects/my-app/sub",
+        }).matchValues(),
+      ).toEqual([
+        "/projects/my-app/sub/foo.ts",
+        "sub/foo.ts",
+        "foo.ts",
+        "/real/foo.ts",
+      ]);
+    });
   });
 
   describe("boundaryValue()", () => {
@@ -66,19 +95,19 @@ describe("AccessPath.forExternalDirectory", () => {
       realpathSync.mockImplementation((p: string) =>
         p.startsWith("/tmp") ? `/private${p}` : p,
       );
-      expect(
-        AccessPath.forExternalDirectory("/tmp/x", cwd).boundaryValue(),
-      ).toBe("/private/tmp/x");
+      expect(AccessPath.forPath("/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");
+      expect(AccessPath.forPath("/etc/hosts", { cwd }).boundaryValue()).toBe(
+        "/etc/hosts",
+      );
     });
 
     test("returns empty string for empty input", () => {
-      expect(AccessPath.forExternalDirectory("", cwd).boundaryValue()).toBe("");
+      expect(AccessPath.forPath("", { cwd }).boundaryValue()).toBe("");
     });
   });
 
@@ -88,20 +117,51 @@ describe("AccessPath.forExternalDirectory", () => {
         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",
-      );
+      expect(AccessPath.forPath("/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(
+      expect(AccessPath.forPath("src/foo.ts", { cwd }).value()).toBe(
         "/projects/my-app/src/foo.ts",
       );
     });
 
+    test("normalizes a relative path against an explicit resolveBase", () => {
+      expect(
+        AccessPath.forPath("foo.ts", {
+          cwd,
+          resolveBase: "/projects/my-app/sub",
+        }).value(),
+      ).toBe("/projects/my-app/sub/foo.ts");
+    });
+
     test("returns empty string for empty input", () => {
-      expect(AccessPath.forExternalDirectory("", cwd).value()).toBe("");
+      expect(AccessPath.forPath("", { cwd }).value()).toBe("");
     });
   });
 });
+
+describe("AccessPath.forLiteral", () => {
+  beforeEach(() => {
+    realpathSync.mockReset();
+    realpathSync.mockImplementation((p: string) => p);
+  });
+
+  test("matchValues() carries only the literal — no canonical, no absolute", () => {
+    expect(AccessPath.forLiteral("foo.ts").matchValues()).toEqual(["foo.ts"]);
+  });
+
+  test("boundaryValue() is empty (no outside-cwd notion for an unknown base)", () => {
+    expect(AccessPath.forLiteral("foo.ts").boundaryValue()).toBe("");
+  });
+
+  test("value() returns the literal", () => {
+    expect(AccessPath.forLiteral("foo.ts").value()).toBe("foo.ts");
+  });
+
+  test("an empty literal yields no match values", () => {
+    expect(AccessPath.forLiteral("").matchValues()).toEqual([]);
+    expect(AccessPath.forLiteral("").value()).toBe("");
+  });
+});

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

@@ -16,14 +16,20 @@ describe("BashProgram", () => {
   describe("pathRuleCandidates", () => {
     const cwd = "/projects/my-app";
 
+    beforeEach(() => {
+      realpathSync.mockReset();
+      realpathSync.mockImplementation((p: string) => p);
+    });
+
     it("adds absolute and relative policy values for relative tokens", async () => {
       const program = await BashProgram.parse("cat src/foo.ts", cwd);
-      expect(program.pathRuleCandidates()).toEqual([
-        {
-          token: "src/foo.ts",
-          policyValues: ["/projects/my-app/src/foo.ts", "src/foo.ts"],
-        },
+      const candidates = program.pathRuleCandidates();
+      expect(candidates.map(({ token }) => token)).toEqual(["src/foo.ts"]);
+      expect(candidates[0].path.matchValues()).toEqual([
+        "/projects/my-app/src/foo.ts",
+        "src/foo.ts",
       ]);
+      expect(candidates[0].path.value()).toBe("/projects/my-app/src/foo.ts");
     });
 
     it("resolves tokens after literal cd against the effective directory", async () => {
@@ -34,14 +40,28 @@ describe("BashProgram", () => {
       const fileCandidate = program
         .pathRuleCandidates()
         .find((candidate) => candidate.token === "src/file.txt");
-      expect(fileCandidate).toEqual({
-        token: "src/file.txt",
-        policyValues: [
-          "/projects/my-app/nested/src/file.txt",
-          "nested/src/file.txt",
-          "src/file.txt",
-        ],
-      });
+      expect(fileCandidate?.path.matchValues()).toEqual([
+        "/projects/my-app/nested/src/file.txt",
+        "nested/src/file.txt",
+        "src/file.txt",
+      ]);
+      expect(fileCandidate?.path.value()).toBe(
+        "/projects/my-app/nested/src/file.txt",
+      );
+    });
+
+    it("adds the canonical alias for a symlinked token (#486)", async () => {
+      // /projects/my-app/src/foo.ts is a symlink to /vault/foo.ts.
+      realpathSync.mockImplementation((p: string) =>
+        p === "/projects/my-app/src/foo.ts" ? "/vault/foo.ts" : p,
+      );
+      const program = await BashProgram.parse("cat src/foo.ts", cwd);
+      const candidate = program.pathRuleCandidates()[0];
+      expect(candidate.path.matchValues()).toEqual([
+        "/projects/my-app/src/foo.ts",
+        "src/foo.ts",
+        "/vault/foo.ts",
+      ]);
     });
 
     it("does not absolute-allow relative tokens after unknown cd", async () => {
@@ -52,10 +72,22 @@ describe("BashProgram", () => {
       const fileCandidate = program
         .pathRuleCandidates()
         .find((candidate) => candidate.token === "src/foo.ts");
-      expect(fileCandidate).toEqual({
-        token: "src/foo.ts",
-        policyValues: ["src/foo.ts"],
-      });
+      expect(fileCandidate?.path.matchValues()).toEqual(["src/foo.ts"]);
+      expect(fileCandidate?.path.value()).toBe("src/foo.ts");
+    });
+
+    it("keeps an unknown-cd token literal-only even when it would resolve a symlink (#393)", async () => {
+      // A canonical alias here would resolve against the wrong (unknown) base.
+      realpathSync.mockImplementation(() => "/somewhere/else");
+      const program = await BashProgram.parse(
+        'cd "$DIR" && cat src/foo.ts',
+        cwd,
+      );
+      const fileCandidate = program
+        .pathRuleCandidates()
+        .find((candidate) => candidate.token === "src/foo.ts");
+      expect(fileCandidate?.path.matchValues()).toEqual(["src/foo.ts"]);
+      expect(fileCandidate?.path.boundaryValue()).toBe("");
     });
   });
 

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

@@ -44,7 +44,6 @@ function makeCheckResult(
 /** Extract the policy match values a resolve(intent) call carries. */
 function intentValues(intent: AccessIntent): readonly string[] {
   if (intent.kind === "access-path") return intent.path.matchValues();
-  if (intent.kind === "path-values") return intent.values;
   return [];
 }
 

package/test/handlers/gates/bash-path.test.ts

@@ -9,6 +9,7 @@ vi.mock("node:os", () => {
   };
 });
 
+import { AccessPath } from "#src/access-intent/access-path";
 import { BashProgram } from "#src/access-intent/bash/program";
 import { describeBashPathGate } from "#src/handlers/gates/bash-path";
 import type {
@@ -229,13 +230,12 @@ describe("describeBashPathGate", () => {
     )) as GateDescriptor;
 
     expect(resolver.resolve).toHaveBeenCalledWith({
-      kind: "path-values",
+      kind: "access-path",
       surface: "path",
-      values: [
-        "/test/project/nested/src/file.txt",
-        "nested/src/file.txt",
-        "src/file.txt",
-      ],
+      path: AccessPath.forPath("src/file.txt", {
+        cwd: "/test/project",
+        resolveBase: "/test/project/nested",
+      }),
       agentName: undefined,
     });
     // The raw token drives the prompt, denial context, and session approval.
@@ -256,9 +256,9 @@ describe("describeBashPathGate", () => {
     );
 
     expect(resolver.resolve).toHaveBeenCalledWith({
-      kind: "path-values",
+      kind: "access-path",
       surface: "path",
-      values: ["src/foo.ts"],
+      path: AccessPath.forLiteral("src/foo.ts"),
       agentName: undefined,
     });
   });

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

@@ -25,7 +25,7 @@ function makeCheckResult(
 
 describe("resolveExternalDirectoryPolicy", () => {
   it("resolves the path's match aliases on the external_directory surface (#418)", () => {
-    const path = AccessPath.forExternalDirectory("/outside/a.ts", cwd);
+    const path = AccessPath.forPath("/outside/a.ts", { cwd });
     const resolver = makeResolver(makeCheckResult("ask"));
 
     const result = resolveExternalDirectoryPolicy(path, resolver, undefined);
@@ -40,7 +40,7 @@ describe("resolveExternalDirectoryPolicy", () => {
   });
 
   it("threads the agent name through to the resolver", () => {
-    const path = AccessPath.forExternalDirectory("/outside/a.ts", cwd);
+    const path = AccessPath.forPath("/outside/a.ts", { cwd });
     const resolver = makeResolver(makeCheckResult("allow"));
 
     resolveExternalDirectoryPolicy(path, resolver, "reviewer");
@@ -57,8 +57,8 @@ describe("resolveExternalDirectoryPolicy", () => {
 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),
+      AccessPath.forPath("/outside/a.ts", { cwd }),
+      AccessPath.forPath("/outside/b.ts", { cwd }),
     ];
     const resolver = makeResolver(makeCheckResult("allow"));
 
@@ -73,16 +73,12 @@ describe("selectUncoveredExternalPaths", () => {
   });
 
   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 allowed = AccessPath.forPath("/outside/ok.ts", { cwd });
+    const asked = AccessPath.forPath("/outside/ask.ts", { cwd });
     const resolver = makeResolver();
     resolver.resolve.mockImplementation((intent) => {
       const values =
-        intent.kind === "access-path"
-          ? intent.path.matchValues()
-          : intent.kind === "path-values"
-            ? intent.values
-            : [];
+        intent.kind === "access-path" ? intent.path.matchValues() : [];
       return values.includes("/outside/ok.ts")
         ? makeCheckResult("allow")
         : makeCheckResult("ask");
@@ -98,16 +94,12 @@ describe("selectUncoveredExternalPaths", () => {
   });
 
   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 asked = AccessPath.forPath("/outside/ask.ts", { cwd });
+    const denied = AccessPath.forPath("/outside/deny.ts", { cwd });
     const resolver = makeResolver();
     resolver.resolve.mockImplementation((intent) => {
       const values =
-        intent.kind === "access-path"
-          ? intent.path.matchValues()
-          : intent.kind === "path-values"
-            ? intent.values
-            : [];
+        intent.kind === "access-path" ? intent.path.matchValues() : [];
       return values.includes("/outside/deny.ts")
         ? makeCheckResult("deny")
         : makeCheckResult("ask");

package/test/handlers/gates/path.test.ts

@@ -1,5 +1,16 @@
-import { describe, expect, it } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 
+// 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";
 import type { GateDescriptor } from "#src/handlers/gates/descriptor";
 import { isGateDescriptor } from "#src/handlers/gates/descriptor";
 import { describePathGate } from "#src/handlers/gates/path";
@@ -27,6 +38,11 @@ function makeTcc(overrides: Partial<ToolCallContext> = {}): ToolCallContext {
 // ── tests ──────────────────────────────────────────────────────────────────
 
 describe("describePathGate", () => {
+  beforeEach(() => {
+    realpathSync.mockReset();
+    realpathSync.mockImplementation((p: string) => p);
+  });
+
   it("returns null for non-path-bearing tools", () => {
     const resolver = makeResolver();
     const result = describePathGate(
@@ -152,16 +168,31 @@ describe("describePathGate", () => {
     expect(result.decision.value).toBe(".env");
   });
 
-  it("resolves the path surface with the file path and agent name", () => {
+  it("resolves the path surface with an access-path intent and agent name", () => {
     const resolver = makeResolver(makeCheckResult({ state: "allow" }));
     describePathGate(makeTcc({ agentName: "my-agent" }), resolver);
     expect(resolver.resolve).toHaveBeenCalledWith({
-      kind: "tool",
+      kind: "access-path",
       surface: "path",
-      input: { path: ".env" },
+      path: AccessPath.forPath(".env", { cwd: "/test/project" }),
       agentName: "my-agent",
     });
   });
+
+  it("emits an access-path whose matchValues include the symlink-resolved form (#486)", () => {
+    // /test/project/.env is a symlink to /vault/secret.env.
+    realpathSync.mockImplementation((p: string) =>
+      p === "/test/project/.env" ? "/vault/secret.env" : p,
+    );
+    const resolver = makeResolver(makeCheckResult({ state: "allow" }));
+    describePathGate(makeTcc(), resolver);
+
+    const intent = resolver.resolve.mock.lastCall?.[0];
+    expect(intent?.kind).toBe("access-path");
+    expect(intent?.kind === "access-path" && intent.path.matchValues()).toEqual(
+      ["/test/project/.env", ".env", "/vault/secret.env"],
+    );
+  });
 });
 
 // Home-relative path characterization (#350) ──────────────────────────────
@@ -189,9 +220,9 @@ describe("describePathGate — home-relative paths", () => {
       pathValue: "~/.ssh/config",
     });
     expect(resolver.resolve).toHaveBeenCalledWith({
-      kind: "tool",
+      kind: "access-path",
       surface: "path",
-      input: { path: "~/.ssh/config" },
+      path: AccessPath.forPath("~/.ssh/config", { cwd: "/test/project" }),
       agentName: undefined,
     });
   });
@@ -246,9 +277,9 @@ describe("describePathGate — extension and MCP tools (#352)", () => {
     );
     expect(isGateDescriptor(result)).toBe(true);
     expect(resolver.resolve).toHaveBeenCalledWith({
-      kind: "tool",
+      kind: "access-path",
       surface: "path",
-      input: { path: ".env" },
+      path: AccessPath.forPath(".env", { cwd: "/test/project" }),
       agentName: undefined,
     });
   });
@@ -263,9 +294,9 @@ describe("describePathGate — extension and MCP tools (#352)", () => {
     );
     expect(isGateDescriptor(result)).toBe(true);
     expect(resolver.resolve).toHaveBeenCalledWith({
-      kind: "tool",
+      kind: "access-path",
       surface: "path",
-      input: { path: ".env" },
+      path: AccessPath.forPath(".env", { cwd: "/test/project" }),
       agentName: undefined,
     });
   });
@@ -280,9 +311,9 @@ describe("describePathGate — extension and MCP tools (#352)", () => {
       extractorLookup("ffgrep", "target"),
     );
     expect(resolver.resolve).toHaveBeenCalledWith({
-      kind: "tool",
+      kind: "access-path",
       surface: "path",
-      input: { path: "/etc/passwd" },
+      path: AccessPath.forPath("/etc/passwd", { cwd: "/test/project" }),
       agentName: undefined,
     });
   });

package/test/helpers/gate-fixtures.ts

@@ -213,8 +213,7 @@ export function makePathDispatchResolver(
       }
       return defaultResult;
     }
-    const values =
-      intent.kind === "access-path" ? intent.path.matchValues() : intent.values;
+    const values = intent.path.matchValues();
     for (const value of values) {
       if (value in byPath) return byPath[value];
     }

package/test/permission-resolver.test.ts

@@ -120,28 +120,7 @@ describe("PermissionResolver", () => {
     });
   });
 
-  describe("resolve — path-values intent", () => {
-    it("forwards a path-values intent with the current session ruleset", () => {
-      const { resolver, permissionManager } = makeResolver();
-
-      resolver.resolve({
-        kind: "path-values",
-        surface: "path",
-        values: ["/proj/src/a.ts", "src/a.ts"],
-        agentName: "agent-x",
-      });
-
-      expect(permissionManager.check).toHaveBeenCalledWith(
-        {
-          kind: "path-values",
-          surface: "path",
-          values: ["/proj/src/a.ts", "src/a.ts"],
-          agentName: "agent-x",
-        },
-        [],
-      );
-    });
-
+  describe("resolve — session ruleset threading", () => {
     it("applies a recorded session approval on the next call", () => {
       const pm = makePermissionManager();
       const sessionRules = new SessionRules();
@@ -151,9 +130,9 @@ describe("PermissionResolver", () => {
         SessionApproval.single("path", "src/*"),
       );
       resolver.resolve({
-        kind: "path-values",
+        kind: "access-path",
         surface: "path",
-        values: ["src/a.ts"],
+        path: AccessPath.forPath("src/a.ts", { cwd: "/proj" }),
       });
 
       const passedRules = vi.mocked(pm.check).mock.calls[0][1];
@@ -169,10 +148,7 @@ describe("PermissionResolver", () => {
   describe("resolve — access-path intent", () => {
     it("unwraps the AccessPath via matchValues() into a path-values intent", () => {
       const { resolver, permissionManager } = makeResolver();
-      const accessPath = AccessPath.forExternalDirectory(
-        "/tmp/x",
-        "/workspace",
-      );
+      const accessPath = AccessPath.forPath("/tmp/x", { cwd: "/workspace" });
 
       resolver.resolve({
         kind: "access-path",
@@ -202,10 +178,7 @@ describe("PermissionResolver", () => {
         matchedPattern: "/tmp/*",
       });
       const { resolver } = makeResolver(pm);
-      const accessPath = AccessPath.forExternalDirectory(
-        "/tmp/x",
-        "/workspace",
-      );
+      const accessPath = AccessPath.forPath("/tmp/x", { cwd: "/workspace" });
 
       const result = resolver.resolve({
         kind: "access-path",