@gotgenes/pi-permission-system 16.0.2 → 16.2.0

package/src/permission-manager.ts

@@ -1,4 +1,5 @@
 import { join } from "node:path";
+import type { ResolvedAccessIntent } from "./access-intent/access-intent";
 import { isPermissionState } from "./common";
 import {
   getGlobalConfigPath,
@@ -50,7 +51,7 @@ type FileCacheEntry<TValue> = {
 type ResolvedPermissions = {
   /**
    * Fully composed ruleset: synthesized defaults → baseline → config.
-   * Session rules are appended at call-time inside checkPermission().
+   * Session rules are appended at call-time inside check().
    */
   composedRules: Ruleset;
 };
@@ -62,25 +63,16 @@ type ResolvedPermissions = {
  */
 export interface ScopedPermissionManager {
   configureForCwd(cwd: string | undefined | null): void;
-  checkPermission(
-    toolName: string,
-    input: unknown,
-    agentName?: string,
-    sessionRules?: Ruleset,
-  ): PermissionCheckResult;
   /**
-   * Evaluate a path-shaped surface (`path` or `external_directory`) against a
-   * caller-supplied set of equivalent policy values (e.g. bash tokens already
-   * resolved against a preceding literal `cd`, or a path's typed and
-   * symlink-resolved aliases). The values are trusted because they are computed
-   * internally, never read from a field on raw tool input. `surface` defaults
-   * to `path`.
+   * Unified resolution entry point (Phase 6 Step 6, #478).
+   *
+   * Replaces the former `checkPermission` + `checkPathPolicy` method pair with
+   * a single dispatched call, making it structurally impossible to stub one
+   * method and forget the other (the #393 false-green class).
    */
-  checkPathPolicy(
-    values: readonly string[],
-    agentName?: string,
+  check(
+    intent: ResolvedAccessIntent,
     sessionRules?: Ruleset,
-    surface?: string,
   ): PermissionCheckResult;
   getToolPermission(toolName: string, agentName?: string): PermissionState;
   getConfigIssues(agentName?: string): string[];
@@ -243,56 +235,48 @@ export class PermissionManager implements ScopedPermissionManager {
     return evaluate(normalizedToolName, "*", composedRules).action;
   }
 
-  checkPermission(
-    toolName: string,
-    input: unknown,
-    agentName?: string,
+  /**
+   * Unified resolution entry point — dispatches on intent kind.
+   *
+   * `"tool"` → normalizes raw input through `normalizeInput`.
+   * `"path-values"` → evaluates the precomputed values directly.
+   */
+  check(
+    intent: ResolvedAccessIntent,
     sessionRules?: Ruleset,
   ): PermissionCheckResult {
-    const { composedRules } = this.resolvePermissions(agentName);
-    const normalizedToolName = toolName.trim();
-
-    // Append session rules at the end (highest priority) so evaluate() handles
-    // them via last-match-wins — no separate per-branch pre-check needed.
+    const { composedRules } = this.resolvePermissions(intent.agentName);
     const fullRules: Ruleset = sessionRules?.length
       ? [...composedRules, ...sessionRules]
       : composedRules;
 
+    if (intent.kind === "path-values") {
+      const lookupValues =
+        intent.values.length > 0 ? [...intent.values] : ["*"];
+      return buildCheckResult(
+        intent.surface,
+        lookupValues,
+        {},
+        intent.surface,
+        intent.surface,
+        fullRules,
+      );
+    }
+
+    // kind === "tool"
+    const toolName = intent.surface.trim();
     const { surface, values, resultExtras } = normalizeInput(
-      normalizedToolName,
-      input,
+      toolName,
+      intent.input,
       this.loader.getConfiguredMcpServerNames(),
       this.currentCwd,
     );
-
     return buildCheckResult(
       surface,
       values,
       resultExtras,
-      normalizedToolName,
       toolName,
-      fullRules,
-    );
-  }
-
-  checkPathPolicy(
-    values: readonly string[],
-    agentName?: string,
-    sessionRules?: Ruleset,
-    surface = "path",
-  ): PermissionCheckResult {
-    const { composedRules } = this.resolvePermissions(agentName);
-    const fullRules: Ruleset = sessionRules?.length
-      ? [...composedRules, ...sessionRules]
-      : composedRules;
-
-    const lookupValues = values.length > 0 ? [...values] : ["*"];
-    return buildCheckResult(
-      surface,
-      lookupValues,
-      {},
-      surface,
-      surface,
+      intent.surface,
       fullRules,
     );
   }
@@ -302,8 +286,8 @@ export class PermissionManager implements ScopedPermissionManager {
  * Evaluate a normalized surface/values triple and shape the result.
  *
  * Path surfaces use {@link evaluateAnyValue} (last-match-wins across equivalent
- * aliases); every other surface keeps {@link evaluateFirst}. Shared by
- * `checkPermission` and `checkPathPolicy`.
+ * aliases); every other surface keeps {@link evaluateFirst}. Shared by the
+ * `"tool"` and `"path-values"` branches of {@link PermissionManager.check}.
  */
 function buildCheckResult(
   surface: string,
@@ -357,7 +341,7 @@ function derivePolicyLoaderOptions(
  * Map a matched rule + tool name to the correct PermissionCheckResult.source.
  *
  * Mirrors the source-derivation logic from the former per-branch
- * checkPermission() implementation:
+ * permission-check implementation:
  *
  * - session          → "session" (always, all surfaces)
  * - mcp + default    → "default"

package/src/permission-resolver.ts

@@ -1,34 +1,42 @@
+import type {
+  AccessIntent,
+  ResolvedAccessIntent,
+} from "./access-intent/access-intent";
 import type { ScopedPermissionManager } from "./permission-manager";
 import type { Rule } from "./rule";
 import type { SessionRules } from "./session-rules";
+import type { SkillPermissionChecker } from "./skill-prompt-sanitizer";
 import type { PermissionCheckResult, PermissionState } from "./types";
 
 /**
- * Resolves the effective permission for a surface/input, applying the current
- * session rules internally.
+ * Answers an {@link AccessIntent} a gate emits, applying the current session
+ * rules internally.
  *
- * Collapses the `checkPermission` + `getSessionRuleset` relay that every gate
- * previously threaded by hand: the ruleset was only ever fetched to be passed
- * straight back into `checkPermission`, so the two are one operation.
+ * A single `resolve(intent)` entry point means adding a gate cannot widen the
+ * resolver surface, and a test fixture cannot stub one resolution method and
+ * forget another (the #393 false-green class) — #478.
  */
 export interface ScopedPermissionResolver {
-  resolve(
-    surface: string,
-    input: unknown,
-    agentName?: string,
-  ): PermissionCheckResult;
-  /**
-   * Resolve a path-shaped surface against a caller-supplied set of equivalent
-   * policy values, applying the current session rules. Used by the bash path
-   * gate (`path`) and the external-directory gates (`external_directory`),
-   * which compute equivalent path aliases per token. `surface` defaults to
-   * `path`.
-   */
-  resolvePathPolicy(
-    values: readonly string[],
-    agentName?: string,
-    surface?: string,
-  ): PermissionCheckResult;
+  resolve(intent: AccessIntent): PermissionCheckResult;
+}
+
+/**
+ * Reduce a gate-emitted {@link AccessIntent} to the string-based
+ * {@link ResolvedAccessIntent} the manager consumes.
+ *
+ * Tell-Don't-Ask: the resolver asks an `AccessPath` for its `matchValues()`,
+ * so the low-level manager never imports the value object.
+ */
+function toResolvedIntent(intent: AccessIntent): ResolvedAccessIntent {
+  if (intent.kind === "access-path") {
+    return {
+      kind: "path-values",
+      surface: intent.surface,
+      values: intent.path.matchValues(),
+      agentName: intent.agentName,
+    };
+  }
+  return intent;
 }
 
 /**
@@ -41,60 +49,40 @@ export interface ScopedPermissionResolver {
  * - `permissionManager` — the narrow session-scoped permission-checking interface
  * - `sessionRules` — narrowed to `getRuleset` (ISP: the resolver only reads, never records)
  */
-export class PermissionResolver implements ScopedPermissionResolver {
+export class PermissionResolver
+  implements ScopedPermissionResolver, SkillPermissionChecker
+{
   constructor(
     private readonly permissionManager: ScopedPermissionManager,
     private readonly sessionRules: Pick<SessionRules, "getRuleset">,
   ) {}
 
   /**
-   * Resolve the effective permission for a surface/input, applying the current
-   * session rules. Composes `checkPermission` with `getRuleset()` so callers
-   * never thread the ruleset by hand.
+   * Answer a gate-emitted access intent, composing the current session ruleset
+   * so callers never thread it by hand. Unwraps the `access-path` variant via
+   * `matchValues()` before handing a string-based intent to the manager.
    */
-  resolve(
-    surface: string,
-    input: unknown,
-    agentName?: string,
-  ): PermissionCheckResult {
-    return this.checkPermission(
-      surface,
-      input,
-      agentName,
+  resolve(intent: AccessIntent): PermissionCheckResult {
+    return this.permissionManager.check(
+      toResolvedIntent(intent),
       this.sessionRules.getRuleset(),
     );
   }
 
   /**
-   * Resolve a path-shaped surface (`path` or `external_directory`) for
-   * precomputed policy values, composing the current session ruleset so callers
-   * never thread it by hand. `surface` defaults to `path`; the external-directory
-   * gates pass `external_directory` so a path's typed and symlink-resolved
-   * aliases match against the `external_directory` rules.
+   * Raw permission check without session rules — the no-session-rules path
+   * consumed by `SkillInputGateInputs` / `SkillPermissionChecker`.
+   *
+   * Not on `ScopedPermissionResolver` (ISP: gates do not use this).
    */
-  resolvePathPolicy(
-    values: readonly string[],
-    agentName?: string,
-    surface = "path",
-  ): PermissionCheckResult {
-    return this.permissionManager.checkPathPolicy(
-      values,
-      agentName,
-      this.sessionRules.getRuleset(),
-      surface,
-    );
-  }
-
   checkPermission(
     surface: string,
     input: unknown,
     agentName?: string,
     sessionRules?: Rule[],
   ): PermissionCheckResult {
-    return this.permissionManager.checkPermission(
-      surface,
-      input,
-      agentName,
+    return this.permissionManager.check(
+      { kind: "tool", surface, input, agentName },
       sessionRules,
     );
   }

package/src/permissions-service.ts

@@ -32,10 +32,8 @@ export class LocalPermissionsService implements PermissionsService {
     agentName?: string,
   ): ReturnType<PermissionsService["checkPermission"]> {
     const input = buildInputForSurface(surface, value);
-    return this.permissionManager.checkPermission(
-      surface,
-      input,
-      agentName,
+    return this.permissionManager.check(
+      { kind: "tool", surface, input, agentName },
       this.sessionRules.getRuleset(),
     );
   }

package/src/skill-prompt-sanitizer.ts

@@ -7,8 +7,8 @@ import {
 import type { PermissionCheckResult, PermissionState } from "./types";
 
 /**
- * Narrow interface for the permission checker used by skill prompt resolution.
- * Both `PermissionManager` and `PermissionResolver` satisfy this structurally.
+ * Narrow interface for the raw (no-session-rules) permission checker used by
+ * skill prompt resolution. `PermissionResolver` implements it (#478).
  */
 export interface SkillPermissionChecker {
   checkPermission(

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

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

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

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

package/test/handlers/before-agent-start.test.ts

@@ -49,10 +49,8 @@ function makeSetup(opts?: {
       opts.toolPermission,
     );
   }
-  // Default checkPermission returns allow (for skill-prompt sanitizer)
-  vi.mocked(permissionManager.checkPermission).mockReturnValue(
-    makeCheckResult(),
-  );
+  // Default check returns allow (for skill-prompt sanitizer via resolver.checkPermission)
+  vi.mocked(permissionManager.check).mockReturnValue(makeCheckResult());
   const toolRegistry = makeToolRegistry(opts?.toolRegistry);
   const handler = new AgentPrepHandler(session, resolver, toolRegistry);
   return {
@@ -195,11 +193,10 @@ describe("AgentPrepHandler.handle", () => {
       "</available_skills>",
     ].join("\n");
     const { handler, permissionManager } = makeSetup();
-    vi.mocked(permissionManager.checkPermission).mockImplementation(
-      (surface) =>
-        surface === "skill"
-          ? makeCheckResult({ state: "deny" })
-          : makeCheckResult(),
+    vi.mocked(permissionManager.check).mockImplementation((intent) =>
+      intent.surface === "skill"
+        ? makeCheckResult({ state: "deny" })
+        : makeCheckResult(),
     );
 
     const first = await handler.handle(makeEvent(systemPrompt), makeCtx());