@gotgenes/pi-permission-system 16.2.1 → 17.1.0

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

@@ -1,9 +1,21 @@
-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";
 import type { ToolCallContext } from "#src/handlers/gates/types";
+import { PathNormalizer } from "#src/path-normalizer";
 
 import {
   makeGateCheckResult as makeCheckResult,
@@ -24,14 +36,24 @@ function makeTcc(overrides: Partial<ToolCallContext> = {}): ToolCallContext {
   };
 }
 
+// The gate reads the path normalizer (platform + cwd baked in) from the
+// session; here it is bound to the makeTcc default cwd.
+const normalizer = new PathNormalizer(process.platform, "/test/project");
+
 // ── 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(
       makeTcc({ toolName: "bash", input: { command: "ls" } }),
       resolver,
+      normalizer,
     );
     expect(result).toBeNull();
     expect(resolver.resolve).not.toHaveBeenCalled();
@@ -42,13 +64,14 @@ describe("describePathGate", () => {
     const result = describePathGate(
       makeTcc({ toolName: "read", input: {} }),
       resolver,
+      normalizer,
     );
     expect(result).toBeNull();
   });
 
   it("returns null when path check result is allow", () => {
     const resolver = makeResolver(makeCheckResult({ state: "allow" }));
-    const result = describePathGate(makeTcc(), resolver);
+    const result = describePathGate(makeTcc(), resolver, normalizer);
     expect(result).toBeNull();
   });
 
@@ -61,7 +84,7 @@ describe("describePathGate", () => {
         origin: "builtin",
       }),
     );
-    const result = describePathGate(makeTcc(), resolver);
+    const result = describePathGate(makeTcc(), resolver, normalizer);
     expect(result).toBeNull();
   });
 
@@ -74,7 +97,7 @@ describe("describePathGate", () => {
         origin: "global",
       }),
     );
-    const result = describePathGate(makeTcc(), resolver);
+    const result = describePathGate(makeTcc(), resolver, normalizer);
     expect(result).not.toBeNull();
     expect(isGateDescriptor(result)).toBe(true);
   });
@@ -83,7 +106,7 @@ describe("describePathGate", () => {
     const resolver = makeResolver(
       makeCheckResult({ state: "deny", matchedPattern: "*.env" }),
     );
-    const result = describePathGate(makeTcc(), resolver);
+    const result = describePathGate(makeTcc(), resolver, normalizer);
     expect(result).not.toBeNull();
     expect(isGateDescriptor(result)).toBe(true);
     const desc = result as GateDescriptor;
@@ -95,7 +118,7 @@ describe("describePathGate", () => {
     const resolver = makeResolver(
       makeCheckResult({ state: "ask", matchedPattern: "*.env" }),
     );
-    const result = describePathGate(makeTcc(), resolver);
+    const result = describePathGate(makeTcc(), resolver, normalizer);
     expect(result).not.toBeNull();
     expect(isGateDescriptor(result)).toBe(true);
     const desc = result as GateDescriptor;
@@ -110,6 +133,7 @@ describe("describePathGate", () => {
     const result = describePathGate(
       makeTcc({ input: { path: "/test/project/src/.env" } }),
       resolver,
+      normalizer,
     ) as GateDescriptor;
     expect(result.sessionApproval).toBeDefined();
     expect(result.sessionApproval?.surface).toBe("path");
@@ -123,6 +147,7 @@ describe("describePathGate", () => {
     const result = describePathGate(
       makeTcc({ input: { path: "index.html" }, cwd: "/test/project" }),
       resolver,
+      normalizer,
     ) as GateDescriptor;
     expect(result.sessionApproval?.surface).toBe("path");
     expect(result.sessionApproval?.representativePattern).toBe(
@@ -134,7 +159,11 @@ describe("describePathGate", () => {
     const resolver = makeResolver(
       makeCheckResult({ state: "deny", matchedPattern: "*.env" }),
     );
-    const result = describePathGate(makeTcc(), resolver) as GateDescriptor;
+    const result = describePathGate(
+      makeTcc(),
+      resolver,
+      normalizer,
+    ) as GateDescriptor;
     expect(result.denialContext).toEqual({
       kind: "path",
       toolName: "read",
@@ -147,21 +176,43 @@ describe("describePathGate", () => {
     const resolver = makeResolver(
       makeCheckResult({ state: "deny", matchedPattern: "*.env" }),
     );
-    const result = describePathGate(makeTcc(), resolver) as GateDescriptor;
+    const result = describePathGate(
+      makeTcc(),
+      resolver,
+      normalizer,
+    ) as GateDescriptor;
     expect(result.decision.surface).toBe("path");
     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);
+    describePathGate(makeTcc({ agentName: "my-agent" }), resolver, normalizer);
     expect(resolver.resolve).toHaveBeenCalledWith({
-      kind: "tool",
+      kind: "access-path",
       surface: "path",
-      input: { path: ".env" },
+      path: AccessPath.forPath(".env", {
+        cwd: "/test/project",
+        platform: "linux",
+      }),
       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, normalizer);
+
+    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) ──────────────────────────────
@@ -178,6 +229,7 @@ describe("describePathGate — home-relative paths", () => {
     const result = describePathGate(
       makeTcc({ input: { path: "~/.ssh/config" } }),
       resolver,
+      normalizer,
     ) as GateDescriptor;
 
     expect(isGateDescriptor(result)).toBe(true);
@@ -189,9 +241,12 @@ 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",
+        platform: "linux",
+      }),
       agentName: undefined,
     });
   });
@@ -203,6 +258,7 @@ describe("describePathGate — home-relative paths", () => {
     const result = describePathGate(
       makeTcc({ input: { path: "$HOME/.ssh/config" } }),
       resolver,
+      normalizer,
     ) as GateDescriptor;
 
     expect(isGateDescriptor(result)).toBe(true);
@@ -218,6 +274,7 @@ describe("describePathGate — home-relative paths", () => {
     const result = describePathGate(
       makeTcc({ input: { path: "~/.ssh/config" } }),
       resolver,
+      normalizer,
     );
     expect(result).toBeNull();
   });
@@ -243,12 +300,16 @@ describe("describePathGate — extension and MCP tools (#352)", () => {
     const result = describePathGate(
       makeTcc({ toolName: "my-ext", input: { path: ".env" } }),
       resolver,
+      normalizer,
     );
     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",
+        platform: "linux",
+      }),
       agentName: undefined,
     });
   });
@@ -260,12 +321,16 @@ describe("describePathGate — extension and MCP tools (#352)", () => {
     const result = describePathGate(
       makeTcc({ toolName: "mcp", input: { arguments: { path: ".env" } } }),
       resolver,
+      normalizer,
     );
     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",
+        platform: "linux",
+      }),
       agentName: undefined,
     });
   });
@@ -277,12 +342,16 @@ describe("describePathGate — extension and MCP tools (#352)", () => {
     describePathGate(
       makeTcc({ toolName: "ffgrep", input: { target: "/etc/passwd" } }),
       resolver,
+      normalizer,
       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",
+        platform: "linux",
+      }),
       agentName: undefined,
     });
   });
@@ -292,6 +361,7 @@ describe("describePathGate — extension and MCP tools (#352)", () => {
     const result = describePathGate(
       makeTcc({ toolName: "my-ext", input: { other: true } }),
       resolver,
+      normalizer,
     );
     expect(result).toBeNull();
     expect(resolver.resolve).not.toHaveBeenCalled();

package/test/handlers/gates/skill-read.test.ts

@@ -41,34 +41,39 @@ function makeTcc(overrides: Partial<ToolCallContext> = {}): ToolCallContext {
 
 describe("describeSkillReadGate", () => {
   it("returns null when tool is not read", () => {
-    const result = describeSkillReadGate(makeTcc({ toolName: "write" }), () => [
-      makeSkillEntry(),
-    ]);
+    const result = describeSkillReadGate(
+      makeTcc({ toolName: "write" }),
+      "linux",
+      () => [makeSkillEntry()],
+    );
     expect(result).toBeNull();
   });
 
   it("returns null when no active skill entries", () => {
-    const result = describeSkillReadGate(makeTcc(), () => []);
+    const result = describeSkillReadGate(makeTcc(), "linux", () => []);
     expect(result).toBeNull();
   });
 
   it("returns null when read path does not match any skill", () => {
     const result = describeSkillReadGate(
       makeTcc({ input: { path: "/test/project/src/index.ts" } }),
+      "linux",
       () => [makeSkillEntry()],
     );
     expect(result).toBeNull();
   });
 
   it("returns null when input has no path", () => {
-    const result = describeSkillReadGate(makeTcc({ input: {} }), () => [
-      makeSkillEntry(),
-    ]);
+    const result = describeSkillReadGate(
+      makeTcc({ input: {} }),
+      "linux",
+      () => [makeSkillEntry()],
+    );
     expect(result).toBeNull();
   });
 
   it("returns GateDescriptor with preResolved.state matching skill entry state (ask)", () => {
-    const result = describeSkillReadGate(makeTcc(), () => [
+    const result = describeSkillReadGate(makeTcc(), "linux", () => [
       makeSkillEntry({ state: "ask" }),
     ]);
     expect(result).not.toBeNull();
@@ -77,7 +82,7 @@ describe("describeSkillReadGate", () => {
   });
 
   it("returns GateDescriptor with preResolved.state matching skill entry state (allow)", () => {
-    const result = describeSkillReadGate(makeTcc(), () => [
+    const result = describeSkillReadGate(makeTcc(), "linux", () => [
       makeSkillEntry({ state: "allow" }),
     ]);
     expect(result).not.toBeNull();
@@ -86,7 +91,7 @@ describe("describeSkillReadGate", () => {
   });
 
   it("returns GateDescriptor with preResolved.state matching skill entry state (deny)", () => {
-    const result = describeSkillReadGate(makeTcc(), () => [
+    const result = describeSkillReadGate(makeTcc(), "linux", () => [
       makeSkillEntry({ state: "deny" }),
     ]);
     expect(result).not.toBeNull();
@@ -95,7 +100,7 @@ describe("describeSkillReadGate", () => {
   });
 
   it("decision surface is 'skill' and decision value is the skill name", () => {
-    const result = describeSkillReadGate(makeTcc(), () => [
+    const result = describeSkillReadGate(makeTcc(), "linux", () => [
       makeSkillEntry({ name: "my-skill" }),
     ])!;
     expect(result.decision.surface).toBe("skill");
@@ -103,7 +108,7 @@ describe("describeSkillReadGate", () => {
   });
 
   it("denialContext contains the skill name and read path", () => {
-    const result = describeSkillReadGate(makeTcc(), () => [
+    const result = describeSkillReadGate(makeTcc(), "linux", () => [
       makeSkillEntry({ name: "librarian" }),
     ])!;
     expect(result.denialContext).toEqual({
@@ -117,6 +122,7 @@ describe("describeSkillReadGate", () => {
   it("promptDetails includes skill_read source and skillName", () => {
     const result = describeSkillReadGate(
       makeTcc({ agentName: "test-agent", toolCallId: "tc-42" }),
+      "linux",
       () => [makeSkillEntry({ name: "my-skill" })],
     )!;
     expect(result.promptDetails).toMatchObject({
@@ -132,6 +138,7 @@ describe("describeSkillReadGate", () => {
   it("logContext includes skill_read source and skillName", () => {
     const result = describeSkillReadGate(
       makeTcc({ agentName: "agent-1" }),
+      "linux",
       () => [makeSkillEntry({ name: "librarian" })],
     )!;
     expect(result.logContext).toMatchObject({
@@ -142,7 +149,9 @@ describe("describeSkillReadGate", () => {
   });
 
   it("surface is 'skill' on the descriptor", () => {
-    const result = describeSkillReadGate(makeTcc(), () => [makeSkillEntry()])!;
+    const result = describeSkillReadGate(makeTcc(), "linux", () => [
+      makeSkillEntry(),
+    ])!;
     expect(result.surface).toBe("skill");
   });
 });

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

@@ -2,6 +2,7 @@ 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 { PathNormalizer } from "#src/path-normalizer";
 
 import {
   makeGateInputs,
@@ -172,7 +173,7 @@ describe("ToolCallGatePipeline", () => {
       expect(mockBashProgramParse).toHaveBeenCalledTimes(1);
       expect(mockBashProgramParse).toHaveBeenCalledWith(
         "echo hello",
-        "/test/project",
+        expect.any(PathNormalizer),
       );
     });
 

package/test/handlers/gates/tool.test.ts

@@ -53,6 +53,7 @@ describe("describeToolGate", () => {
       makeTcc({ toolName: "read" }),
       makeCheckResult("ask"),
       makeFormatter(),
+      "linux",
     );
     expect(desc.surface).toBe("read");
     expect(desc.decision.surface).toBe("read");
@@ -63,6 +64,7 @@ describe("describeToolGate", () => {
       makeTcc({ toolName: "write" }),
       makeCheckResult("ask"),
       makeFormatter(),
+      "linux",
     );
     expect(desc.decision.value).toBe("write");
   });
@@ -76,6 +78,7 @@ describe("describeToolGate", () => {
       makeTcc({ toolName: "bash", input: { command: "git status" } }),
       check,
       makeFormatter(),
+      "linux",
     );
     expect(desc.surface).toBe("bash");
     expect(desc.decision.surface).toBe("bash");
@@ -91,6 +94,7 @@ describe("describeToolGate", () => {
       makeTcc({ toolName: "mcp", input: { tool: "server:tool" } }),
       check,
       makeFormatter(),
+      "linux",
     );
     expect(desc.surface).toBe("mcp");
     expect(desc.decision.surface).toBe("mcp");
@@ -99,7 +103,7 @@ describe("describeToolGate", () => {
 
   it("populates denialContext with kind 'tool' and check result", () => {
     const check = makeCheckResult("deny", { toolName: "read" });
-    const desc = describeToolGate(makeTcc(), check, makeFormatter());
+    const desc = describeToolGate(makeTcc(), check, makeFormatter(), "linux");
     expect(desc.denialContext).toEqual({
       kind: "tool",
       check,
@@ -114,6 +118,7 @@ describe("describeToolGate", () => {
       makeTcc({ agentName: "my-agent" }),
       check,
       makeFormatter(),
+      "linux",
     );
     expect(desc.denialContext.agentName).toBe("my-agent");
   });
@@ -124,6 +129,7 @@ describe("describeToolGate", () => {
       makeTcc({ toolName: "bash", input: { command: "ls" } }),
       check,
       makeFormatter(),
+      "linux",
     );
     expect(desc.denialContext).toMatchObject({
       kind: "tool",
@@ -140,6 +146,7 @@ describe("describeToolGate", () => {
       makeTcc({ toolName: "bash", input: { command: "git status" } }),
       check,
       makeFormatter(),
+      "linux",
     );
     expect(desc.sessionApproval).toBeDefined();
     expect(desc.sessionApproval?.surface).toBe("bash");
@@ -156,6 +163,7 @@ describe("describeToolGate", () => {
       }),
       check,
       makeFormatter(),
+      "linux",
     );
     expect(desc.sessionApproval?.surface).toBe("edit");
     expect(desc.sessionApproval?.representativePattern).toBe("/test/project/*");
@@ -174,6 +182,7 @@ describe("describeToolGate", () => {
       }),
       check,
       makeFormatter(),
+      "linux",
     );
     expect(desc.sessionApproval?.representativePattern).toBe(
       "/test/project/src/*",
@@ -186,6 +195,7 @@ describe("describeToolGate", () => {
       makeTcc({ toolName: "read", agentName: "my-agent", toolCallId: "tc-42" }),
       check,
       makeFormatter(),
+      "linux",
     );
     expect(desc.promptDetails).toMatchObject({
       source: "tool_call",
@@ -203,6 +213,7 @@ describe("describeToolGate", () => {
       makeTcc({ toolName: "bash", input: { command: "ls" } }),
       check,
       makeFormatter(),
+      "linux",
     );
     expect(desc.logContext).toMatchObject({
       source: "tool_call",
@@ -216,6 +227,7 @@ describe("describeToolGate", () => {
       makeTcc({ toolName: "edit", input: { path: "/a.ts" } }),
       makeCheckResult("ask", { toolName: "edit" }),
       makeFormatter(),
+      "linux",
     );
     expect(desc.surface).toBe("edit");
     expect(desc.input).toEqual({ path: "/a.ts" });

package/test/helpers/gate-fixtures.ts

@@ -10,6 +10,7 @@ import { GateRunner } from "#src/handlers/gates/runner";
 import type { SkillInputGateInputs } from "#src/handlers/gates/skill-input-gate-pipeline";
 import type { ToolCallGateInputs } from "#src/handlers/gates/tool-call-gate-pipeline";
 import type { ToolCallContext } from "#src/handlers/gates/types";
+import { PathNormalizer } from "#src/path-normalizer";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import type { SessionApprovalRecorder } from "#src/session-approval-recorder";
 import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
@@ -213,8 +214,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];
     }
@@ -254,6 +254,8 @@ export function makeGateInputs(
     getActiveSkillEntries?: () => SkillPromptEntry[];
     getInfrastructureReadDirs?: () => string[];
     getToolPreviewLimits?: () => ToolPreviewFormatterOptions;
+    getPathNormalizer?: () => PathNormalizer;
+    getPlatform?: () => NodeJS.Platform;
   } = {},
 ): ToolCallGateInputs {
   return {
@@ -269,6 +271,13 @@ export function makeGateInputs(
         toolTextSummaryMaxLength: 100,
         toolInputLogPreviewMaxLength: 200,
       })),
+    getPathNormalizer:
+      overrides.getPathNormalizer ??
+      vi.fn<() => PathNormalizer>(
+        () => new PathNormalizer(process.platform, "/test/cwd"),
+      ),
+    getPlatform:
+      overrides.getPlatform ?? vi.fn<() => NodeJS.Platform>(() => "linux"),
   };
 }
 

package/test/helpers/session-fixtures.ts

@@ -126,6 +126,7 @@ export function makeRealSession(overrides?: {
   sessionRules?: SessionRules;
   configStore?: SessionConfigStore;
   gateway?: PromptingGatewayLifecycle;
+  platform?: NodeJS.Platform;
 }): {
   session: PermissionSession;
   paths: ExtensionPaths;
@@ -146,6 +147,7 @@ export function makeRealSession(overrides?: {
   const sessionRules = overrides?.sessionRules ?? new SessionRules();
   const configStore = overrides?.configStore ?? makeConfigStore();
   const gateway = overrides?.gateway ?? makeGateway();
+  const platform = overrides?.platform ?? process.platform;
   const session = new PermissionSession(
     paths,
     forwarding,
@@ -153,6 +155,7 @@ export function makeRealSession(overrides?: {
     sessionRules,
     configStore,
     gateway,
+    platform,
   );
   return {
     session,