@gotgenes/pi-permission-system 18.0.1 → 18.0.2

package/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [18.0.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v18.0.1...pi-permission-system-v18.0.2) (2026-07-01)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** add AccessPath.resolvedAlias() for symlink-target disclosure ([cf6e25c](https://github.com/gotgenes/pi-packages/commit/cf6e25c8a5b672fbab4b41a21240af8ca818971b))
+* **pi-permission-system:** disclose resolved symlink target in tool external-directory messages ([1225e2b](https://github.com/gotgenes/pi-packages/commit/1225e2bcface907a0a4407aadcd744c2398edc19))
+* **pi-permission-system:** disclose resolved symlink targets in bash external-directory messages ([f9fab42](https://github.com/gotgenes/pi-packages/commit/f9fab42b758dd106e67b83a0e3c95fe6fc216687))
+
 ## [18.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v18.0.0...pi-permission-system-v18.0.1) (2026-06-30)
 
 

package/package.json

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

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

@@ -19,6 +19,9 @@ import {
  *   outside-CWD containment and infra-read checks.
  * - {@link value} returns `string` — the lexical absolute form, for display,
  *   approval patterns, decision values, and logs.
+ * - {@link resolvedAlias} returns `string | undefined` — the canonical form
+ *   only when it names a location distinct from the lexical form, for
+ *   disclosing a symlink target in a prompt or denial message.
  *
  * Construct via {@link forPath} (resolved, with optional cd-folded base) or
  * {@link forLiteral} (literal-only, for an unknown base); the constructor is
@@ -66,6 +69,19 @@ export class AccessPath {
     return this.lexical;
   }
 
+  /**
+   * The canonical (symlink-resolved) form when it names a location distinct
+   * from the lexical form — for disclosing the resolved target in a prompt or
+   * denial message. `undefined` when the path is not a symlink (canonical
+   * equals lexical) or has no canonical (literal-only / empty input).
+   */
+  resolvedAlias(): string | undefined {
+    if (!this.canonical || this.canonical === this.lexical) {
+      return undefined;
+    }
+    return this.canonical;
+  }
+
   /**
    * Build an `AccessPath` for a tool-input or bash-token path, resolved against
    * `resolveBase` (the cd-folded effective directory; defaults to `cwd`).

package/src/denial-messages.ts

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

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

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

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

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

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

@@ -67,9 +67,11 @@ export function describeExternalDirectoryGate(
   }
 
   // ── Build descriptor for permission check ───────────────────────────────
+  const resolvedAlias = accessPath.resolvedAlias();
   const extDirMessage = formatExternalDirectoryAskPrompt(
     tcc.toolName,
     externalDirectoryPath,
+    resolvedAlias,
     tcc.cwd,
     tcc.agentName ?? undefined,
   );
@@ -90,6 +92,7 @@ export function describeExternalDirectoryGate(
       kind: "external_directory",
       toolName: tcc.toolName,
       pathValue: externalDirectoryPath,
+      resolvedPath: resolvedAlias,
       cwd: tcc.cwd,
       agentName: tcc.agentName ?? undefined,
     },

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

@@ -191,6 +191,67 @@ describe("AccessPath.forPath", () => {
   });
 });
 
+describe("resolvedAlias()", () => {
+  const cwd = "/projects/my-app";
+
+  beforeEach(() => {
+    realpathSync.mockReset();
+    realpathSync.mockImplementation((p: string) => p);
+  });
+
+  test("returns the canonical form when a symlink resolves elsewhere", () => {
+    realpathSync.mockImplementation((p: string) =>
+      p === "/projects/my-app/demo-symlink-passwd" ? "/etc/passwd" : p,
+    );
+    expect(
+      AccessPath.forPath("demo-symlink-passwd", {
+        cwd,
+        platform: "linux",
+      }).resolvedAlias(),
+    ).toBe("/etc/passwd");
+  });
+
+  test("returns undefined when the path has no symlinks (canonical equals lexical)", () => {
+    expect(
+      AccessPath.forPath("/etc/hosts", {
+        cwd,
+        platform: "linux",
+      }).resolvedAlias(),
+    ).toBeUndefined();
+  });
+
+  test("returns undefined for a literal-only path (no canonical)", () => {
+    expect(AccessPath.forLiteral("foo.ts").resolvedAlias()).toBeUndefined();
+  });
+
+  test("returns undefined for empty input", () => {
+    expect(
+      AccessPath.forPath("", { cwd, platform: "linux" }).resolvedAlias(),
+    ).toBeUndefined();
+  });
+
+  test("win32: returns the lowercased canonical form for a real symlink target", () => {
+    realpathSync.mockImplementation((p: string) =>
+      p === "c:\\projects\\app\\link" ? "C:\\Real\\App" : p,
+    );
+    expect(
+      AccessPath.forPath("link", {
+        cwd: "C:\\Projects\\App",
+        platform: "win32",
+      }).resolvedAlias(),
+    ).toBe("c:\\real\\app");
+  });
+
+  test("win32: returns undefined for a case-only difference (both forms lowercased)", () => {
+    expect(
+      AccessPath.forPath("src\\foo.ts", {
+        cwd: "C:\\Projects\\App",
+        platform: "win32",
+      }).resolvedAlias(),
+    ).toBeUndefined();
+  });
+});
+
 describe("AccessPath.forLiteral", () => {
   beforeEach(() => {
     realpathSync.mockReset();

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

@@ -924,7 +924,7 @@ describe("formatBashExternalDirectoryAskPrompt", () => {
   test("includes command, external paths, and CWD", () => {
     const result = formatBashExternalDirectoryAskPrompt(
       "cat /etc/hosts",
-      ["/etc/hosts"],
+      [{ path: "/etc/hosts" }],
       "/projects/my-app",
     );
     expect(result).toContain("cat /etc/hosts");
@@ -935,7 +935,7 @@ describe("formatBashExternalDirectoryAskPrompt", () => {
   test("includes agent name when provided", () => {
     const result = formatBashExternalDirectoryAskPrompt(
       "cat /etc/hosts",
-      ["/etc/hosts"],
+      [{ path: "/etc/hosts" }],
       "/projects/my-app",
       "my-agent",
     );
@@ -945,12 +945,26 @@ describe("formatBashExternalDirectoryAskPrompt", () => {
   test("shows multiple external paths", () => {
     const result = formatBashExternalDirectoryAskPrompt(
       "diff /etc/hosts /var/log/syslog",
-      ["/etc/hosts", "/var/log/syslog"],
+      [{ path: "/etc/hosts" }, { path: "/var/log/syslog" }],
       "/projects/my-app",
     );
     expect(result).toContain("/etc/hosts");
     expect(result).toContain("/var/log/syslog");
   });
+
+  test("discloses the resolved target per path when it differs", () => {
+    const result = formatBashExternalDirectoryAskPrompt(
+      "cat demo-symlink-passwd /etc/hosts",
+      [
+        { path: "demo-symlink-passwd", resolvedPath: "/etc/passwd" },
+        { path: "/etc/hosts" },
+      ],
+      "/projects/my-app",
+    );
+    expect(result).toBe(
+      "Current agent requested bash command 'cat demo-symlink-passwd /etc/hosts' which references path(s) outside working directory '/projects/my-app': demo-symlink-passwd (resolves to '/etc/passwd'), /etc/hosts. Allow this external directory access?",
+    );
+  });
 });
 
 describe("Windows drive-letter paths (win32 semantics)", () => {
@@ -996,7 +1010,7 @@ describe("bash external-directory denial messages (centralized)", () => {
     const result = formatDenyReason({
       kind: "bash_external_directory",
       command: "cat /etc/hosts",
-      externalPaths: ["/etc/hosts"],
+      externalPaths: [{ path: "/etc/hosts" }],
       cwd: "/projects/my-app",
     });
     expect(result).toContain("cat /etc/hosts");

package/test/denial-messages.test.ts

@@ -242,6 +242,20 @@ describe("formatDenyReason", () => {
         "[pi-permission-system] Agent 'sec-agent' is not permitted to run tool 'read' for path '/etc/passwd' outside working directory '/project'.",
       );
     });
+
+    test("discloses the resolved path when it differs from the typed path", () => {
+      expect(
+        formatDenyReason({
+          kind: "external_directory",
+          toolName: "read",
+          pathValue: "demo-symlink-passwd",
+          resolvedPath: "/etc/passwd",
+          cwd: "/project",
+        }),
+      ).toBe(
+        "[pi-permission-system] Current agent is not permitted to run tool 'read' for path 'demo-symlink-passwd' (resolves to '/etc/passwd') outside working directory '/project'.",
+      );
+    });
   });
 
   describe("bash_external_directory context", () => {
@@ -250,7 +264,7 @@ describe("formatDenyReason", () => {
         formatDenyReason({
           kind: "bash_external_directory",
           command: "cat /etc/hosts",
-          externalPaths: ["/etc/hosts"],
+          externalPaths: [{ path: "/etc/hosts" }],
           cwd: "/project",
         }),
       ).toBe(
@@ -263,7 +277,7 @@ describe("formatDenyReason", () => {
         formatDenyReason({
           kind: "bash_external_directory",
           command: "cp /etc/hosts /tmp/out",
-          externalPaths: ["/etc/hosts", "/tmp/out"],
+          externalPaths: [{ path: "/etc/hosts" }, { path: "/tmp/out" }],
           cwd: "/project",
           agentName: "my-agent",
         }),
@@ -271,6 +285,22 @@ describe("formatDenyReason", () => {
         "[pi-permission-system] Agent 'my-agent' is not permitted to run bash command 'cp /etc/hosts /tmp/out' which references path(s) outside working directory '/project': /etc/hosts, /tmp/out.",
       );
     });
+
+    test("discloses resolved targets per path when they differ", () => {
+      expect(
+        formatDenyReason({
+          kind: "bash_external_directory",
+          command: "cat demo-symlink-passwd /etc/hosts",
+          externalPaths: [
+            { path: "demo-symlink-passwd", resolvedPath: "/etc/passwd" },
+            { path: "/etc/hosts" },
+          ],
+          cwd: "/project",
+        }),
+      ).toBe(
+        "[pi-permission-system] Current agent is not permitted to run bash command 'cat demo-symlink-passwd /etc/hosts' which references path(s) outside working directory '/project': demo-symlink-passwd (resolves to '/etc/passwd'), /etc/hosts.",
+      );
+    });
   });
 
   describe("bash_path context", () => {
@@ -403,12 +433,26 @@ describe("formatUnavailableReason", () => {
     );
   });
 
+  test("external_directory discloses the resolved path when it differs from the typed path", () => {
+    expect(
+      formatUnavailableReason({
+        kind: "external_directory",
+        toolName: "read",
+        pathValue: "demo-symlink-passwd",
+        resolvedPath: "/etc/passwd",
+        cwd: "/project",
+      }),
+    ).toBe(
+      "[pi-permission-system] Accessing 'demo-symlink-passwd' (resolves to '/etc/passwd') outside the working directory requires approval, but no interactive UI is available.",
+    );
+  });
+
   test("bash_external_directory", () => {
     expect(
       formatUnavailableReason({
         kind: "bash_external_directory",
         command: "cat /etc/hosts",
-        externalPaths: ["/etc/hosts"],
+        externalPaths: [{ path: "/etc/hosts" }],
         cwd: "/project",
       }),
     ).toBe(
@@ -539,6 +583,20 @@ describe("formatUserDeniedReason", () => {
         "[pi-permission-system] User denied external directory access for tool 'edit' path '/etc/hosts'. Reason: too risky.",
       );
     });
+
+    test("discloses the resolved path when it differs from the typed path", () => {
+      expect(
+        formatUserDeniedReason({
+          kind: "external_directory",
+          toolName: "edit",
+          pathValue: "demo-symlink-hosts",
+          resolvedPath: "/etc/hosts",
+          cwd: "/project",
+        }),
+      ).toBe(
+        "[pi-permission-system] User denied external directory access for tool 'edit' path 'demo-symlink-hosts' (resolves to '/etc/hosts').",
+      );
+    });
   });
 
   describe("bash_external_directory context", () => {
@@ -547,7 +605,7 @@ describe("formatUserDeniedReason", () => {
         formatUserDeniedReason({
           kind: "bash_external_directory",
           command: "rm /etc/hosts",
-          externalPaths: ["/etc/hosts"],
+          externalPaths: [{ path: "/etc/hosts" }],
           cwd: "/project",
         }),
       ).toBe(
@@ -561,7 +619,7 @@ describe("formatUserDeniedReason", () => {
           {
             kind: "bash_external_directory",
             command: "rm /etc/hosts",
-            externalPaths: ["/etc/hosts"],
+            externalPaths: [{ path: "/etc/hosts" }],
             cwd: "/project",
           },
           "dangerous",

package/test/handlers/external-directory-integration.test.ts

@@ -47,7 +47,12 @@ describe("external_directory helper regression guard", () => {
   it("formatExternalDirectoryAskPrompt is a callable function", () => {
     expect(typeof formatExternalDirectoryAskPrompt).toBe("function");
     expect(
-      formatExternalDirectoryAskPrompt("read", "/outside/file", "/project"),
+      formatExternalDirectoryAskPrompt(
+        "read",
+        "/outside/file",
+        undefined,
+        "/project",
+      ),
     ).toContain("/outside/file");
   });
 

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

@@ -15,6 +15,7 @@ describe("formatExternalDirectoryAskPrompt", () => {
     const result = formatExternalDirectoryAskPrompt(
       "read",
       "/etc/passwd",
+      undefined,
       "/projects/my-app",
     );
     expect(result).toContain("Current agent");
@@ -27,6 +28,7 @@ describe("formatExternalDirectoryAskPrompt", () => {
     const result = formatExternalDirectoryAskPrompt(
       "write",
       "/tmp/out.txt",
+      undefined,
       "/projects/my-app",
       "my-agent",
     );
@@ -34,13 +36,35 @@ describe("formatExternalDirectoryAskPrompt", () => {
     expect(result).toContain("write");
     expect(result).toContain("/tmp/out.txt");
   });
+
+  test("discloses the resolved path when it differs from the typed path", () => {
+    const result = formatExternalDirectoryAskPrompt(
+      "read",
+      "demo-symlink-passwd",
+      "/etc/passwd",
+      "/projects/my-app",
+    );
+    expect(result).toBe(
+      "Current agent requested tool 'read' for path 'demo-symlink-passwd' (resolves to '/etc/passwd') outside working directory '/projects/my-app'. Allow this external directory access?",
+    );
+  });
+
+  test("omits the disclosure when resolvedPath is undefined", () => {
+    const result = formatExternalDirectoryAskPrompt(
+      "read",
+      "/etc/passwd",
+      undefined,
+      "/projects/my-app",
+    );
+    expect(result).not.toContain("resolves to");
+  });
 });
 
 describe("formatBashExternalDirectoryAskPrompt", () => {
   test("includes command, paths, cwd, and agent name", () => {
     const result = formatBashExternalDirectoryAskPrompt(
       "cat /etc/passwd",
-      ["/etc/passwd"],
+      [{ path: "/etc/passwd" }],
       "/projects/my-app",
       "my-agent",
     );
@@ -53,7 +77,7 @@ describe("formatBashExternalDirectoryAskPrompt", () => {
   test("uses 'Current agent' when no agent name provided", () => {
     const result = formatBashExternalDirectoryAskPrompt(
       "ls /tmp",
-      ["/tmp"],
+      [{ path: "/tmp" }],
       "/projects/my-app",
     );
     expect(result).toContain("Current agent");