@gotgenes/pi-permission-system 10.5.3 → 10.7.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ 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).
 
+## [10.7.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v10.6.0...pi-permission-system-v10.7.0) (2026-06-09)
+
+
+### Features
+
+* add normalizeOptionalStringArray to common ([8be9154](https://github.com/gotgenes/pi-packages/commit/8be9154d7a492f13526f7bd8d4e33fc2e209f98d))
+
+
+### Bug Fixes
+
+* carry piInfrastructureReadPaths through the unified config loader ([#347](https://github.com/gotgenes/pi-packages/issues/347)) ([51bc145](https://github.com/gotgenes/pi-packages/commit/51bc145c15cc54bc69333d1e6cc48c74dda267d1))
+
+## [10.6.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v10.5.3...pi-permission-system-v10.6.0) (2026-06-08)
+
+
+### Features
+
+* **pi-permission-system:** add best-effort canonicalizePath helper ([5b5002e](https://github.com/gotgenes/pi-packages/commit/5b5002e1b5400485f30a9f22440a88d14ed5135d))
+
+
+### Bug Fixes
+
+* **pi-permission-system:** canonicalize bash external-path containment ([#345](https://github.com/gotgenes/pi-packages/issues/345)) ([89f8e9b](https://github.com/gotgenes/pi-packages/commit/89f8e9bb35cd268e46a2b124663f44c11a44be97))
+* **pi-permission-system:** canonicalize tool-call external-directory containment ([#345](https://github.com/gotgenes/pi-packages/issues/345)) ([d7f3bd1](https://github.com/gotgenes/pi-packages/commit/d7f3bd1c02d115621cd87065de240b816837065f))
+
+
+### Documentation
+
+* **pi-permission-system:** note symlink canonicalization in architecture ([b758a48](https://github.com/gotgenes/pi-packages/commit/b758a48bc55485ad9e751543db59858886ba360c))
+
 ## [10.5.3](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v10.5.2...pi-permission-system-v10.5.3) (2026-06-08)
 
 

package/package.json

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

package/src/canonicalize-path.ts

@@ -0,0 +1,30 @@
+import { realpathSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Resolve symlinks in an absolute path, best-effort.
+ *
+ * Splits the path into components and tries `realpathSync` from the full path
+ * down to `/`, re-appending the non-existent tail to the first ancestor that
+ * resolves. Returns the input unchanged when no ancestor resolves (unreachable
+ * in practice since `/` always exists) or when a non-ENOENT/ENOTDIR error is
+ * encountered (e.g. `EACCES`, `ELOOP`), so callers fall back to lexical
+ * containment for paths that cannot be resolved.
+ */
+export function canonicalizePath(absolutePath: string): string {
+  if (!absolutePath) return absolutePath;
+
+  const parts = absolutePath.split("/").filter(Boolean);
+  for (let i = parts.length; i >= 0; i--) {
+    const candidate = "/" + parts.slice(0, i).join("/");
+    try {
+      const real = realpathSync(candidate);
+      const tail = parts.slice(i);
+      return tail.length === 0 ? real : join(real, ...tail);
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== "ENOENT" && code !== "ENOTDIR") return absolutePath;
+    }
+  }
+  return absolutePath;
+}

package/src/common.ts

@@ -17,6 +17,16 @@ export function getNonEmptyString(value: unknown): string | null {
   return trimmed.length > 0 ? trimmed : null;
 }
 
+/** Returns `raw` if it is an array of strings; otherwise `undefined`. */
+export function normalizeOptionalStringArray(
+  raw: unknown,
+): string[] | undefined {
+  return Array.isArray(raw) &&
+    raw.every((p): p is string => typeof p === "string")
+    ? raw
+    : undefined;
+}
+
 /** Returns `raw` if it is a positive integer; otherwise `undefined`. */
 export function normalizeOptionalPositiveInt(raw: unknown): number | undefined {
   return typeof raw === "number" && Number.isInteger(raw) && raw > 0

package/src/config-loader.ts

@@ -4,6 +4,7 @@ import { normalize } from "node:path";
 import {
   isPermissionState,
   normalizeOptionalPositiveInt,
+  normalizeOptionalStringArray,
   toRecord,
 } from "./common";
 import {
@@ -27,6 +28,7 @@ export interface UnifiedPermissionConfig {
   yoloMode?: boolean;
   toolInputPreviewMaxLength?: number;
   toolTextSummaryMaxLength?: number;
+  piInfrastructureReadPaths?: string[];
 
   // Flat permission policy
   permission?: FlatPermissionConfig;
@@ -201,6 +203,12 @@ export function normalizeUnifiedConfig(raw: unknown): {
   if (toolTextSummaryMaxLength !== undefined)
     config.toolTextSummaryMaxLength = toolTextSummaryMaxLength;
 
+  const piInfrastructureReadPaths = normalizeOptionalStringArray(
+    record.piInfrastructureReadPaths,
+  );
+  if (piInfrastructureReadPaths !== undefined)
+    config.piInfrastructureReadPaths = piInfrastructureReadPaths;
+
   // Flat permission policy
   const permission = normalizeFlatPermissionValue(record.permission);
   if (permission !== undefined) config.permission = permission;
@@ -213,6 +221,8 @@ export function normalizeUnifiedConfig(raw: unknown): {
  * - `permission` is deep-shallow merged (surface-level object maps are shallow-merged).
  * - Scalar fields (debugLog, permissionReviewLog, yoloMode) are replaced when
  *   present in the override.
+ * - Array fields (piInfrastructureReadPaths) replace the base when present in
+ *   the override (override-wins, same as scalars).
  */
 export function mergeUnifiedConfigs(
   base: UnifiedPermissionConfig,
@@ -239,6 +249,13 @@ export function mergeUnifiedConfigs(
     }
   }
 
+  // Array fields: override replaces base when defined
+  const piInfrastructureReadPaths =
+    override.piInfrastructureReadPaths ?? base.piInfrastructureReadPaths;
+  if (piInfrastructureReadPaths !== undefined) {
+    merged.piInfrastructureReadPaths = piInfrastructureReadPaths;
+  }
+
   // Permission: deep-shallow merge
   const basePerm = base.permission;
   const overridePerm = override.permission;

package/src/extension-config.ts

@@ -2,7 +2,11 @@ import { mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { normalizeOptionalPositiveInt, toRecord } from "./common";
+import {
+  normalizeOptionalPositiveInt,
+  normalizeOptionalStringArray,
+  toRecord,
+} from "./common";
 
 export const EXTENSION_ID = "pi-permission-system";
 
@@ -50,12 +54,9 @@ export function normalizePermissionSystemConfig(
   raw: unknown,
 ): PermissionSystemExtensionConfig {
   const record = toRecord(raw);
-  const rawPaths = record.piInfrastructureReadPaths;
-  const piInfrastructureReadPaths: string[] | undefined =
-    Array.isArray(rawPaths) &&
-    rawPaths.every((p): p is string => typeof p === "string")
-      ? rawPaths
-      : undefined;
+  const piInfrastructureReadPaths = normalizeOptionalStringArray(
+    record.piInfrastructureReadPaths,
+  );
   const result: PermissionSystemExtensionConfig = {
     debugLog: record.debugLog === true,
     permissionReviewLog: record.permissionReviewLog !== false,

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

@@ -1,6 +1,6 @@
 import { createRequire } from "node:module";
 import { basename, isAbsolute, join, resolve } from "node:path";
-
+import { canonicalizePath } from "#src/canonicalize-path";
 import {
   classifyTokenAsPathCandidate,
   classifyTokenAsRuleCandidate,
@@ -186,7 +186,9 @@ export class BashProgram {
    * the running directory.
    */
   externalPaths(cwd: string): string[] {
-    const normalizedCwd = normalizePathForComparison(cwd, cwd);
+    const normalizedCwd = canonicalizePath(
+      normalizePathForComparison(cwd, cwd),
+    );
 
     const seen = new Set<string>();
     const externalPaths: string[] = [];
@@ -200,7 +202,9 @@ export class BashProgram {
       // display path). Absolute / `~` candidates are base-independent and
       // resolve normally below.
       if (base.kind === "unknown" && isRelativeCandidate(candidate)) {
-        const normalized = normalizePathForComparison(candidate, cwd);
+        const normalized = canonicalizePath(
+          normalizePathForComparison(candidate, cwd),
+        );
         if (
           normalized &&
           normalizedCwd !== "" &&
@@ -215,7 +219,9 @@ export class BashProgram {
 
       const resolveBase =
         base.kind === "known" ? resolve(cwd, base.offset) : cwd;
-      const normalized = normalizePathForComparison(candidate, resolveBase);
+      const normalized = canonicalizePath(
+        normalizePathForComparison(candidate, resolveBase),
+      );
       if (!normalized) continue;
 
       if (

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

@@ -1,8 +1,8 @@
 import {
+  canonicalNormalizePathForComparison,
   getPathBearingToolPath,
   isPathOutsideWorkingDirectory,
   isPiInfrastructureRead,
-  normalizePathForComparison,
 } from "#src/path-utils";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
@@ -31,7 +31,7 @@ export function describeExternalDirectoryGate(
     return null;
   }
 
-  const normalizedExtPath = normalizePathForComparison(
+  const normalizedExtPath = canonicalNormalizePathForComparison(
     externalDirectoryPath,
     tcc.cwd,
   );

package/src/path-utils.ts

@@ -1,5 +1,6 @@
 import { join, normalize, resolve, sep } from "node:path";
 
+import { canonicalizePath } from "./canonicalize-path";
 import { getNonEmptyString, toRecord } from "./common";
 import { expandHomePath } from "./expand-home";
 import { wildcardMatch } from "./wildcard-matcher";
@@ -89,12 +90,27 @@ export function getPathBearingToolPath(
   return getNonEmptyString(toRecord(input).path);
 }
 
+/**
+ * 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,
+): string {
+  const lexical = normalizePathForComparison(pathValue, cwd);
+  if (!lexical) return "";
+  const canonical = canonicalizePath(lexical);
+  return process.platform === "win32" ? canonical.toLowerCase() : canonical;
+}
+
 export function isPathOutsideWorkingDirectory(
   pathValue: string,
   cwd: string,
 ): boolean {
-  const normalizedCwd = normalizePathForComparison(cwd, cwd);
-  const normalizedPath = normalizePathForComparison(pathValue, cwd);
+  const normalizedCwd = canonicalNormalizePathForComparison(cwd, cwd);
+  const normalizedPath = canonicalNormalizePathForComparison(pathValue, cwd);
   if (!normalizedCwd || !normalizedPath) {
     return false;
   }

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

@@ -9,6 +9,14 @@ vi.mock("node:os", () => {
   };
 });
 
+// Mock node:fs with an identity realpathSync so canonicalizePath
+// (used by BashProgram.externalPaths) leaves test paths unchanged and
+// existing expected-value literals remain accurate across platforms.
+vi.mock("node:fs", () => ({
+  realpathSync: (p: string) => p,
+  default: { realpathSync: (p: string) => p },
+}));
+
 import { formatDenyReason } from "#src/denial-messages";
 import {
   extractExternalPathsFromBashCommand,

package/test/canonicalize-path.test.ts

@@ -0,0 +1,93 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+const realpathSync = vi.hoisted(() => vi.fn<(path: string) => string>());
+
+vi.mock("node:fs", () => ({
+  realpathSync,
+  default: { realpathSync },
+}));
+
+import { canonicalizePath } from "#src/canonicalize-path";
+
+function enoent(p: string): NodeJS.ErrnoException {
+  return Object.assign(new Error(`ENOENT: no such file or directory '${p}'`), {
+    code: "ENOENT",
+  });
+}
+
+describe("canonicalizePath", () => {
+  beforeEach(() => {
+    realpathSync.mockReset();
+  });
+
+  test("returns empty string for empty input", () => {
+    expect(canonicalizePath("")).toBe("");
+  });
+
+  test("returns realpathSync result when path exists", () => {
+    realpathSync.mockReturnValueOnce("/real/projects/app");
+    expect(canonicalizePath("/projects/link")).toBe("/real/projects/app");
+  });
+
+  test("re-appends a non-existent leaf to the canonical parent", () => {
+    realpathSync
+      .mockImplementationOnce(() => {
+        throw enoent("/projects/app/new-file.ts");
+      })
+      .mockReturnValueOnce("/canonical/app");
+    expect(canonicalizePath("/projects/app/new-file.ts")).toBe(
+      "/canonical/app/new-file.ts",
+    );
+  });
+
+  test("walks up multiple levels for a deeply non-existent path", () => {
+    realpathSync
+      .mockImplementationOnce(() => {
+        throw enoent("/projects/app/src/new-file.ts");
+      })
+      .mockImplementationOnce(() => {
+        throw enoent("/projects/app/src");
+      })
+      .mockImplementationOnce(() => {
+        throw enoent("/projects/app");
+      })
+      .mockReturnValueOnce("/canonical/projects");
+    expect(canonicalizePath("/projects/app/src/new-file.ts")).toBe(
+      "/canonical/projects/app/src/new-file.ts",
+    );
+  });
+
+  test("returns input unchanged when walk reaches filesystem root (all ENOENT)", () => {
+    realpathSync.mockImplementation(() => {
+      throw enoent("");
+    });
+    expect(canonicalizePath("/nonexistent/path/file.ts")).toBe(
+      "/nonexistent/path/file.ts",
+    );
+  });
+
+  test("returns input unchanged on ELOOP (symlink loop)", () => {
+    realpathSync.mockImplementation(() => {
+      throw Object.assign(new Error("ELOOP"), { code: "ELOOP" });
+    });
+    expect(canonicalizePath("/some/looping/path")).toBe("/some/looping/path");
+  });
+
+  test("returns input unchanged on EACCES (permission denied)", () => {
+    realpathSync.mockImplementation(() => {
+      throw Object.assign(new Error("EACCES"), { code: "EACCES" });
+    });
+    expect(canonicalizePath("/restricted/path")).toBe("/restricted/path");
+  });
+
+  test("handles ENOTDIR by walking up (like ENOENT)", () => {
+    realpathSync
+      .mockImplementationOnce(() => {
+        throw Object.assign(new Error("ENOTDIR"), { code: "ENOTDIR" });
+      })
+      .mockReturnValueOnce("/real/parent");
+    expect(canonicalizePath("/real/parent/not-a-dir")).toBe(
+      "/real/parent/not-a-dir",
+    );
+  });
+});

package/test/common.test.ts

@@ -5,6 +5,7 @@ import {
   getNonEmptyString,
   isPermissionState,
   normalizeOptionalPositiveInt,
+  normalizeOptionalStringArray,
   parseSimpleYamlMap,
   toRecord,
 } from "#src/common";
@@ -189,6 +190,44 @@ describe("parseSimpleYamlMap", () => {
   });
 });
 
+describe("normalizeOptionalStringArray", () => {
+  it("returns the array for a valid string array", () => {
+    expect(normalizeOptionalStringArray(["a", "b", "c"])).toEqual([
+      "a",
+      "b",
+      "c",
+    ]);
+  });
+
+  it("returns an empty array for an empty array", () => {
+    expect(normalizeOptionalStringArray([])).toEqual([]);
+  });
+
+  it("returns undefined for a plain string", () => {
+    expect(normalizeOptionalStringArray("x")).toBeUndefined();
+  });
+
+  it("returns undefined for a number", () => {
+    expect(normalizeOptionalStringArray(42)).toBeUndefined();
+  });
+
+  it("returns undefined for a plain object", () => {
+    expect(normalizeOptionalStringArray({ a: "b" })).toBeUndefined();
+  });
+
+  it("returns undefined for a mixed-type array", () => {
+    expect(normalizeOptionalStringArray(["a", 1])).toBeUndefined();
+  });
+
+  it("returns undefined for undefined", () => {
+    expect(normalizeOptionalStringArray(undefined)).toBeUndefined();
+  });
+
+  it("returns undefined for null", () => {
+    expect(normalizeOptionalStringArray(null)).toBeUndefined();
+  });
+});
+
 describe("normalizeOptionalPositiveInt", () => {
   it("returns the value for a valid positive integer", () => {
     expect(normalizeOptionalPositiveInt(1)).toBe(1);

package/test/config-loader.test.ts

@@ -324,6 +324,48 @@ describe("loadUnifiedConfig", () => {
     const result = loadUnifiedConfig(configPath);
     expect(result.config).not.toHaveProperty("toolTextSummaryMaxLength");
   });
+
+  it("parses piInfrastructureReadPaths when a valid string array is present", () => {
+    const configPath = join(tempDir, "config.json");
+    writeFileSync(
+      configPath,
+      JSON.stringify({ piInfrastructureReadPaths: ["/extra/path"] }),
+    );
+    const result = loadUnifiedConfig(configPath);
+    expect(result.config.piInfrastructureReadPaths).toEqual(["/extra/path"]);
+  });
+
+  it("parses piInfrastructureReadPaths as empty array when set to []", () => {
+    const configPath = join(tempDir, "config.json");
+    writeFileSync(
+      configPath,
+      JSON.stringify({ piInfrastructureReadPaths: [] }),
+    );
+    const result = loadUnifiedConfig(configPath);
+    expect(result.config.piInfrastructureReadPaths).toEqual([]);
+  });
+
+  it("omits piInfrastructureReadPaths when absent", () => {
+    const configPath = join(tempDir, "config.json");
+    writeFileSync(configPath, JSON.stringify({ debugLog: false }));
+    const result = loadUnifiedConfig(configPath);
+    expect(result.config).not.toHaveProperty("piInfrastructureReadPaths");
+  });
+
+  it.each([
+    ["string", "not-an-array"],
+    ["number", 42],
+    ["mixed-type array", ["a", 1]],
+    ["object", { a: "b" }],
+  ] as const)("omits piInfrastructureReadPaths for invalid value: %s", (_label, value) => {
+    const configPath = join(tempDir, "config.json");
+    writeFileSync(
+      configPath,
+      JSON.stringify({ piInfrastructureReadPaths: value }),
+    );
+    const result = loadUnifiedConfig(configPath);
+    expect(result.config).not.toHaveProperty("piInfrastructureReadPaths");
+  });
 });
 
 describe("mergeUnifiedConfigs", () => {
@@ -460,6 +502,35 @@ describe("mergeUnifiedConfigs", () => {
     const merged = mergeUnifiedConfigs({}, { permissionReviewLog: true });
     expect(merged).not.toHaveProperty("toolTextSummaryMaxLength");
   });
+
+  it("override piInfrastructureReadPaths replaces base array", () => {
+    const merged = mergeUnifiedConfigs(
+      { piInfrastructureReadPaths: ["/base/path"] },
+      { piInfrastructureReadPaths: ["/override/path"] },
+    );
+    expect(merged.piInfrastructureReadPaths).toEqual(["/override/path"]);
+  });
+
+  it("base piInfrastructureReadPaths survives when override omits it", () => {
+    const merged = mergeUnifiedConfigs(
+      { piInfrastructureReadPaths: ["/kept/path"] },
+      { debugLog: true },
+    );
+    expect(merged.piInfrastructureReadPaths).toEqual(["/kept/path"]);
+  });
+
+  it("piInfrastructureReadPaths is absent when both base and override omit it", () => {
+    const merged = mergeUnifiedConfigs({ debugLog: true }, { yoloMode: false });
+    expect(merged).not.toHaveProperty("piInfrastructureReadPaths");
+  });
+
+  it("override piInfrastructureReadPaths as empty array replaces non-empty base", () => {
+    const merged = mergeUnifiedConfigs(
+      { piInfrastructureReadPaths: ["/base/path"] },
+      { piInfrastructureReadPaths: [] },
+    );
+    expect(merged.piInfrastructureReadPaths).toEqual([]);
+  });
 });
 
 describe("loadAndMergeConfigs", () => {

package/test/config-store.test.ts

@@ -293,6 +293,18 @@ describe("ConfigStore", () => {
       store.refresh(ctx);
       expect(mockSyncPermissionSystemStatus).not.toHaveBeenCalled();
     });
+
+    it("carries piInfrastructureReadPaths from merged config into current()", () => {
+      const { store } = makeStore();
+      mockLoadAndMergeConfigs.mockReturnValue({
+        merged: { piInfrastructureReadPaths: ["/extra/path"] },
+        issues: [],
+      });
+      store.refresh();
+      expect(store.current().piInfrastructureReadPaths).toEqual([
+        "/extra/path",
+      ]);
+    });
   });
 
   // ── save() ─────────────────────────────────────────────────────────────
@@ -385,6 +397,20 @@ describe("ConfigStore", () => {
         "utf-8",
       );
     });
+
+    it("preserves an existing global piInfrastructureReadPaths on save", () => {
+      const { store } = makeStore();
+      // Simulate a global config.json that already has the infra-paths field.
+      mockLoadUnifiedConfig.mockReturnValue({
+        config: { piInfrastructureReadPaths: ["/extra/path"] },
+      });
+      store.save({ ...DEFAULT_EXTENSION_CONFIG }, makeCommandCtx());
+      expect(mockWriteFileSync).toHaveBeenCalledWith(
+        expect.stringContaining(".tmp"),
+        expect.stringContaining('"piInfrastructureReadPaths"'),
+        "utf-8",
+      );
+    });
   });
 
   // ── logResolvedPaths() ─────────────────────────────────────────────────

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

@@ -1,4 +1,14 @@
-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 is identity so all existing lexical tests are unaffected.
+const realpathSync = vi.hoisted(() =>
+  vi.fn<(path: string) => string>((p) => p),
+);
+vi.mock("node:fs", () => ({
+  realpathSync,
+  default: { realpathSync },
+}));
 
 import { BashProgram } from "#src/handlers/gates/bash-program";
 
@@ -23,6 +33,11 @@ describe("BashProgram", () => {
   describe("externalPaths", () => {
     const cwd = "/projects/my-app";
 
+    beforeEach(() => {
+      realpathSync.mockReset();
+      realpathSync.mockImplementation((p: string) => p);
+    });
+
     it("returns absolute paths resolving outside cwd", async () => {
       const program = await BashProgram.parse("cat /etc/hosts");
       // Subset matcher: the path is normalized before comparison.
@@ -142,6 +157,33 @@ describe("BashProgram", () => {
         expect(program.externalPaths(cwd)).toHaveLength(0);
       });
     });
+
+    it("flags an absolute in-cwd path that resolves externally via a symlink", async () => {
+      // The strict classifier only processes absolute tokens, so the escape
+      // surface is `cat /cwd/link/hosts` (absolute) where `link -> /etc`.
+      // Without canonicalization: /projects/my-app/link/hosts looks internal.
+      // With canonicalization: realpathSync resolves it to /etc/hosts.
+      realpathSync.mockImplementation((p: string) => {
+        if (p === "/projects/my-app/link/hosts") return "/etc/hosts";
+        return p;
+      });
+      const program = await BashProgram.parse(
+        "cat /projects/my-app/link/hosts",
+      );
+      expect(program.externalPaths(cwd)).toContain("/etc/hosts");
+    });
+
+    it("does not flag a token that resolves within a symlinked cwd", async () => {
+      // Simulates /tmp -> /private/tmp on macOS; cwd is the canonical form.
+      const symlinkCwd = "/private/tmp";
+      realpathSync.mockImplementation((p: string) => {
+        if (p === "/tmp") return "/private/tmp";
+        if (p.startsWith("/tmp/")) return "/private/tmp" + p.slice(4);
+        return p;
+      });
+      const program = await BashProgram.parse("cat /tmp/workspace/file.ts");
+      expect(program.externalPaths(symlinkCwd)).toHaveLength(0);
+    });
   });
 
   describe("commands", () => {

package/test/path-utils.test.ts

@@ -1,5 +1,5 @@
 import { join } from "node:path";
-import { describe, expect, test, vi } from "vitest";
+import { beforeEach, describe, expect, test, vi } from "vitest";
 
 // Mock node:os so tilde-expansion is deterministic across platforms.
 vi.mock("node:os", () => {
@@ -10,7 +10,18 @@ vi.mock("node:os", () => {
   };
 });
 
+// Mock node:fs so realpathSync (used by canonicalizePath) is controllable.
+// Default implementation is identity — existing lexical tests are unaffected.
+const realpathSync = vi.hoisted(() =>
+  vi.fn<(path: string) => string>((p) => p),
+);
+vi.mock("node:fs", () => ({
+  realpathSync,
+  default: { realpathSync },
+}));
+
 import {
+  canonicalNormalizePathForComparison,
   getPathBearingToolPath,
   isPathOutsideWorkingDirectory,
   isPathWithinDirectory,
@@ -200,6 +211,12 @@ describe("getPathBearingToolPath", () => {
 describe("isPathOutsideWorkingDirectory", () => {
   const cwd = "/projects/my-app";
 
+  beforeEach(() => {
+    // Reset then restore the identity default so symlink tests don't bleed.
+    realpathSync.mockReset();
+    realpathSync.mockImplementation((p: string) => p);
+  });
+
   test("returns false when path is inside cwd", () => {
     expect(isPathOutsideWorkingDirectory("/projects/my-app/src", cwd)).toBe(
       false,
@@ -245,6 +262,57 @@ describe("isPathOutsideWorkingDirectory", () => {
   test("returns true for /dev/null/subdir (not a safe path)", () => {
     expect(isPathOutsideWorkingDirectory("/dev/null/subdir", cwd)).toBe(true);
   });
+
+  test("returns true for in-cwd symlink that resolves to external path", () => {
+    // ./link -> /etc: realpathSync resolves the full token in one call.
+    realpathSync.mockImplementation((p: string) => {
+      if (p === "/projects/my-app/link/hosts") return "/etc/hosts";
+      return p;
+    });
+    expect(isPathOutsideWorkingDirectory("./link/hosts", cwd)).toBe(true);
+  });
+
+  test("returns false for path inside a symlinked cwd", () => {
+    // /tmp -> /private/tmp on macOS; cwd reported as /private/tmp.
+    const symlinkCwd = "/private/tmp";
+    realpathSync.mockImplementation((p: string) => {
+      if (p.startsWith("/tmp/")) return "/private/tmp" + p.slice(4);
+      if (p === "/tmp") return "/private/tmp";
+      return p;
+    });
+    expect(
+      isPathOutsideWorkingDirectory("/tmp/workspace/file.ts", symlinkCwd),
+    ).toBe(false);
+  });
+});
+
+describe("canonicalNormalizePathForComparison", () => {
+  const cwd = "/projects/my-app";
+
+  beforeEach(() => {
+    realpathSync.mockReset();
+    realpathSync.mockImplementation((p: string) => p);
+  });
+
+  test("returns canonical form of an existing path", () => {
+    realpathSync.mockImplementation((p: string) => {
+      if (p === "/projects/link") return "/real/projects/app";
+      return p;
+    });
+    expect(canonicalNormalizePathForComparison("/projects/link", cwd)).toBe(
+      "/real/projects/app",
+    );
+  });
+
+  test("returns empty string for empty input", () => {
+    expect(canonicalNormalizePathForComparison("", cwd)).toBe("");
+  });
+
+  test("returns lexical form when no symlinks (identity realpathSync)", () => {
+    expect(
+      canonicalNormalizePathForComparison("/projects/my-app/src/index.ts", cwd),
+    ).toBe("/projects/my-app/src/index.ts");
+  });
 });
 
 describe("isPiInfrastructureRead", () => {