@gotgenes/pi-permission-system 17.0.0 → 17.1.0

package/src/permission-manager.ts

@@ -85,10 +85,17 @@ export interface PermissionManagerOptions extends PolicyLoaderOptions {
    * from this value and supports {@link PermissionManager.configureForCwd}.
    */
   agentDir?: string;
+  /**
+   * Host platform, injected from the composition root, that decides whether
+   * path-surface rule matching folds case (and separators) on Windows.
+   * Defaults to a POSIX flavor; production always supplies the real platform.
+   */
+  platform?: NodeJS.Platform;
 }
 
 export class PermissionManager implements ScopedPermissionManager {
   private readonly agentDir: string | undefined;
+  private readonly platform: NodeJS.Platform;
   private currentCwd: string | undefined;
   private loader: PolicyLoader;
   private readonly resolvedPermissionsCache = new Map<
@@ -98,6 +105,7 @@ export class PermissionManager implements ScopedPermissionManager {
 
   constructor(options: PermissionManagerOptions = {}) {
     this.agentDir = options.agentDir;
+    this.platform = options.platform ?? "linux";
     this.loader =
       options.policyLoader ??
       new FilePolicyLoader(
@@ -216,23 +224,25 @@ export class PermissionManager implements ScopedPermissionManager {
 
     // Special surfaces (external_directory): evaluate directly by surface name.
     if (SPECIAL_PERMISSION_KEYS.has(normalizedToolName)) {
-      return evaluate(normalizedToolName, "*", composedRules).action;
+      return evaluate(normalizedToolName, "*", composedRules, this.platform)
+        .action;
     }
 
     // Bash, MCP, skill: evaluate with "*" value — the per-surface catch-all
     // (or universal default) handles this correctly.
     if (normalizedToolName === "bash") {
-      return evaluate("bash", "*", composedRules).action;
+      return evaluate("bash", "*", composedRules, this.platform).action;
     }
     if (normalizedToolName === "mcp") {
-      return evaluate("mcp", "*", composedRules).action;
+      return evaluate("mcp", "*", composedRules, this.platform).action;
     }
     if (normalizedToolName === "skill") {
-      return evaluate("skill", "*", composedRules).action;
+      return evaluate("skill", "*", composedRules, this.platform).action;
     }
 
     // Tool-name surfaces (read, write, etc. and extension tools).
-    return evaluate(normalizedToolName, "*", composedRules).action;
+    return evaluate(normalizedToolName, "*", composedRules, this.platform)
+      .action;
   }
 
   /**
@@ -260,6 +270,7 @@ export class PermissionManager implements ScopedPermissionManager {
         intent.surface,
         intent.surface,
         fullRules,
+        this.platform,
       );
     }
 
@@ -269,6 +280,7 @@ export class PermissionManager implements ScopedPermissionManager {
       toolName,
       intent.input,
       this.loader.getConfiguredMcpServerNames(),
+      this.platform,
       this.currentCwd,
     );
     return buildCheckResult(
@@ -278,6 +290,7 @@ export class PermissionManager implements ScopedPermissionManager {
       toolName,
       intent.surface,
       fullRules,
+      this.platform,
     );
   }
 }
@@ -296,10 +309,11 @@ function buildCheckResult(
   normalizedToolName: string,
   toolName: string,
   fullRules: Ruleset,
+  platform: NodeJS.Platform,
 ): PermissionCheckResult {
   const { rule, value } = PATH_SURFACES.has(surface)
-    ? evaluateAnyValue(surface, values, fullRules)
-    : evaluateFirst(surface, values, fullRules);
+    ? evaluateAnyValue(surface, values, fullRules, platform)
+    : evaluateFirst(surface, values, fullRules, platform);
 
   // For MCP, replace the normalizer's fallback target with the actual
   // matched candidate value so PermissionCheckResult.target is accurate.

package/src/permission-session.ts

@@ -9,6 +9,7 @@ import type { PermissionSystemExtensionConfig } from "./extension-config";
 import type { ExtensionPaths } from "./extension-paths";
 import type { ForwardingController } from "./forwarding-manager";
 import type { ToolCallGateInputs } from "./handlers/gates/tool-call-gate-pipeline";
+import { PathNormalizer } from "./path-normalizer";
 import type { ScopedPermissionManager } from "./permission-manager";
 import type { PromptingGatewayLifecycle } from "./prompting-gateway";
 
@@ -37,6 +38,7 @@ export class PermissionSession implements ToolCallGateInputs {
   private context: ExtensionContext | null = null;
   private skillEntries: SkillPromptEntry[] = [];
   private knownAgentName: string | null = null;
+  private pathNormalizer: PathNormalizer;
 
   constructor(
     private readonly paths: ExtensionPaths,
@@ -45,13 +47,28 @@ export class PermissionSession implements ToolCallGateInputs {
     private readonly sessionRules: SessionRules,
     private readonly configStore: SessionConfigStore,
     private readonly gateway: PromptingGatewayLifecycle,
-  ) {}
+    private readonly platform: NodeJS.Platform,
+  ) {
+    // Placeholder until the first activate(ctx) binds the real cwd; every gate
+    // evaluate runs after activate (handleToolCall activates first), so this
+    // empty-cwd value is never read.
+    this.pathNormalizer = new PathNormalizer(platform, "");
+  }
 
   // ── Context lifecycle ──────────────────────────────────────────────────
 
-  /** Store the current extension context, start forwarding, and activate the gateway. */
+  /**
+   * Store the current extension context, rebuild the path normalizer for its
+   * cwd, start forwarding, and activate the gateway.
+   *
+   * The normalizer is (re)built here rather than only at `resetForNewSession`
+   * so it always tracks the active context's cwd — `ctx.cwd` is stable within a
+   * session, so this is a no-op rebuild in production, but it closes the
+   * fail-open gap if a tool call ever arrives before `session_start`.
+   */
   activate(ctx: ExtensionContext): void {
     this.context = ctx;
+    this.pathNormalizer = new PathNormalizer(this.platform, ctx.cwd);
     this.forwarding.start(ctx);
     this.gateway.activate(ctx);
   }
@@ -68,6 +85,11 @@ export class PermissionSession implements ToolCallGateInputs {
     return this.context;
   }
 
+  /** The host platform injected at the composition root. */
+  getPlatform(): NodeJS.Platform {
+    return this.platform;
+  }
+
   // ── UI notifications ────────────────────────────────────────────────────
 
   /** Surface a warning message to the user via the active UI context, if any. */
@@ -186,4 +208,15 @@ export class PermissionSession implements ToolCallGateInputs {
   getToolPreviewLimits(): ToolPreviewFormatterOptions {
     return resolveToolPreviewLimits(this.config);
   }
+
+  // ── Path normalization ────────────────────────────────────────────────
+
+  /**
+   * The session's {@link PathNormalizer}, carrying the host platform and the
+   * session cwd. Rebuilt on every `resetForNewSession` so a session switch
+   * rebinds the cwd.
+   */
+  getPathNormalizer(): PathNormalizer {
+    return this.pathNormalizer;
+  }
 }

package/src/prompting-gateway.ts

@@ -23,6 +23,8 @@ export interface PromptingGatewayDeps {
   config: ConfigReader;
   /** Static path used to detect a forwarding subagent context. */
   subagentSessionsDir: string;
+  /** Host platform, injected from the composition root, for subagent-context path detection. */
+  platform: NodeJS.Platform;
   /** Process-global registry used to detect a registered child session. */
   registry?: SubagentSessionRegistry;
   /** Resolves the permission decision: direct UI dialog or forwarded to parent. */
@@ -82,6 +84,7 @@ export class PromptingGateway
       isSubagent: isSubagentExecutionContext(
         this.context,
         this.deps.subagentSessionsDir,
+        this.deps.platform,
         this.deps.registry,
       ),
     });

package/src/rule.ts

@@ -54,8 +54,8 @@ export function evaluate(
   surface: string,
   pattern: string,
   rules: Ruleset,
+  platform: NodeJS.Platform,
   defaultAction?: PermissionState,
-  platform: NodeJS.Platform = process.platform,
 ): Rule {
   const rule = rules.findLast((r) =>
     ruleMatches(r, surface, pattern, platform),
@@ -124,10 +124,11 @@ export function evaluateMostRestrictive(
   surface: string,
   values: string[],
   rules: Ruleset,
+  platform: NodeJS.Platform,
 ): { rule: Rule; value: string } | null {
   let worst: { rule: Rule; value: string } | null = null;
   for (const value of values) {
-    const rule = evaluate(surface, value, rules);
+    const rule = evaluate(surface, value, rules, platform);
     if (rule.action === "deny") return { rule, value };
     if (rule.action === "ask" && worst?.rule.action !== "ask") {
       worst = { rule, value };
@@ -140,9 +141,10 @@ export function evaluateFirst(
   surface: string,
   values: string[],
   rules: Ruleset,
+  platform: NodeJS.Platform,
 ): { rule: Rule; value: string } {
   for (const value of values) {
-    const rule = evaluate(surface, value, rules);
+    const rule = evaluate(surface, value, rules, platform);
     if (rule.layer !== "default") {
       return { rule, value };
     }
@@ -150,7 +152,7 @@ export function evaluateFirst(
   // All candidates matched only the synthesized default — use the first.
   const fallbackValue = values[0] ?? "*";
   return {
-    rule: evaluate(surface, fallbackValue, rules),
+    rule: evaluate(surface, fallbackValue, rules, platform),
     value: fallbackValue,
   };
 }
@@ -167,7 +169,7 @@ export function evaluateAnyValue(
   surface: string,
   values: string[],
   rules: Ruleset,
-  platform: NodeJS.Platform = process.platform,
+  platform: NodeJS.Platform,
 ): { rule: Rule; value: string } {
   const fallbackValue = values[0] ?? "*";
   const rule = rules.findLast((r) =>
@@ -182,7 +184,7 @@ export function evaluateAnyValue(
     };
   }
   return {
-    rule: evaluate(surface, fallbackValue, rules),
+    rule: evaluate(surface, fallbackValue, rules, platform),
     value: fallbackValue,
   };
 }

package/src/skill-prompt-sanitizer.ts

@@ -152,14 +152,23 @@ function createResolvedSkillEntry(
   entry: ParsedSkillPromptEntry,
   state: PermissionState,
   cwd: string,
+  platform: NodeJS.Platform,
 ): SkillPromptEntry {
   return {
     name: entry.name,
     description: entry.description,
     location: entry.location,
     state,
-    normalizedLocation: normalizePathForComparison(entry.location, cwd),
-    normalizedBaseDir: normalizePathForComparison(dirname(entry.location), cwd),
+    normalizedLocation: normalizePathForComparison(
+      entry.location,
+      cwd,
+      platform,
+    ),
+    normalizedBaseDir: normalizePathForComparison(
+      dirname(entry.location),
+      cwd,
+      platform,
+    ),
   };
 }
 
@@ -190,6 +199,7 @@ export function resolveSkillPromptEntries(
   permissionManager: SkillPermissionChecker,
   agentName: string | null,
   cwd: string,
+  platform: NodeJS.Platform,
 ): { prompt: string; entries: SkillPromptEntry[] } {
   const sections = parseAllSkillPromptSections(prompt);
   if (sections.length === 0) {
@@ -209,7 +219,7 @@ export function resolveSkillPromptEntries(
         agentName,
         permissionCache,
       );
-      return createResolvedSkillEntry(entry, state, cwd);
+      return createResolvedSkillEntry(entry, state, cwd, platform);
     });
 
     const visibleSectionEntries = resolvedEntries.filter(
@@ -257,6 +267,7 @@ export function resolveSkillPromptEntries(
 export function findSkillPathMatch(
   normalizedPath: string,
   entries: readonly SkillPromptEntry[],
+  platform: NodeJS.Platform,
 ): SkillPromptEntry | null {
   if (!normalizedPath || entries.length === 0) {
     return null;
@@ -275,7 +286,7 @@ export function findSkillPathMatch(
   for (const entry of entries) {
     if (
       !entry.normalizedBaseDir ||
-      !isPathWithinDirectory(normalizedPath, entry.normalizedBaseDir)
+      !isPathWithinDirectory(normalizedPath, entry.normalizedBaseDir, platform)
     ) {
       continue;
     }

package/src/subagent-context.ts

@@ -1,4 +1,4 @@
-import { normalize } from "node:path";
+import { posix as posixPath, win32 as winPath } from "node:path";
 
 import { SUBAGENT_ENV_HINT_KEYS } from "./permission-forwarding";
 import type { SubagentSessionRegistry } from "./subagent-registry";
@@ -15,16 +15,19 @@ export interface SubagentDetectionContext {
   };
 }
 
-export function normalizeFilesystemPath(pathValue: string): string {
-  const normalizedPath = normalize(pathValue);
-  return process.platform === "win32"
-    ? normalizedPath.toLowerCase()
-    : normalizedPath;
+export function normalizeFilesystemPath(
+  pathValue: string,
+  platform: NodeJS.Platform,
+): string {
+  const impl = platform === "win32" ? winPath : posixPath;
+  const normalizedPath = impl.normalize(pathValue);
+  return platform === "win32" ? normalizedPath.toLowerCase() : normalizedPath;
 }
 
 function isPathWithinDirectoryForSubagent(
   pathValue: string,
   directory: string,
+  platform: NodeJS.Platform,
 ): boolean {
   if (!pathValue || !directory) {
     return false;
@@ -34,7 +37,7 @@ function isPathWithinDirectoryForSubagent(
     return true;
   }
 
-  const sep = process.platform === "win32" ? "\\" : "/";
+  const sep = platform === "win32" ? "\\" : "/";
   const prefix = directory.endsWith(sep) ? directory : `${directory}${sep}`;
   return pathValue.startsWith(prefix);
 }
@@ -68,6 +71,7 @@ export function isRegisteredSubagentChild(
 export function isSubagentExecutionContext(
   ctx: SubagentDetectionContext,
   subagentSessionsDir: string,
+  platform: NodeJS.Platform,
   registry?: SubagentSessionRegistry,
 ): boolean {
   // 1. Explicit registry — in-process subagent extensions register by child
@@ -95,10 +99,14 @@ export function isSubagentExecutionContext(
     return false;
   }
 
-  const normalizedSessionDir = normalizeFilesystemPath(sessionDir);
-  const normalizedSubagentRoot = normalizeFilesystemPath(subagentSessionsDir);
+  const normalizedSessionDir = normalizeFilesystemPath(sessionDir, platform);
+  const normalizedSubagentRoot = normalizeFilesystemPath(
+    subagentSessionsDir,
+    platform,
+  );
   return isPathWithinDirectoryForSubagent(
     normalizedSessionDir,
     normalizedSubagentRoot,
+    platform,
   );
 }

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

@@ -35,30 +35,37 @@ describe("AccessPath.forPath", () => {
       realpathSync.mockImplementation((p: string) =>
         p.startsWith("/tmp") ? `/private${p}` : p,
       );
-      expect(AccessPath.forPath("/tmp/x", { cwd }).matchValues()).toEqual([
-        "/tmp/x",
-        "/private/tmp/x",
-      ]);
+      expect(
+        AccessPath.forPath("/tmp/x", { cwd, platform: "linux" }).matchValues(),
+      ).toEqual(["/tmp/x", "/private/tmp/x"]);
     });
 
     test("deduplicates when the canonical form equals the lexical form", () => {
-      expect(AccessPath.forPath("/etc/hosts", { cwd }).matchValues()).toEqual([
-        "/etc/hosts",
-      ]);
+      expect(
+        AccessPath.forPath("/etc/hosts", {
+          cwd,
+          platform: "linux",
+        }).matchValues(),
+      ).toEqual(["/etc/hosts"]);
     });
 
     test("keeps the relative aliases for an in-cwd token without duplicating", () => {
-      expect(AccessPath.forPath("src/foo.ts", { cwd }).matchValues()).toEqual([
-        "/projects/my-app/src/foo.ts",
-        "src/foo.ts",
-      ]);
+      expect(
+        AccessPath.forPath("src/foo.ts", {
+          cwd,
+          platform: "linux",
+        }).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.forPath("/etc/hosts", { cwd }).matchValues(),
+        AccessPath.forPath("/etc/hosts", {
+          cwd,
+          platform: "linux",
+        }).matchValues(),
       ).not.toHaveLength(0);
     });
 
@@ -68,6 +75,7 @@ describe("AccessPath.forPath", () => {
         AccessPath.forPath("foo.ts", {
           cwd,
           resolveBase: "/projects/my-app/sub",
+          platform: "linux",
         }).matchValues(),
       ).toEqual(["/projects/my-app/sub/foo.ts", "sub/foo.ts", "foo.ts"]);
     });
@@ -80,6 +88,7 @@ describe("AccessPath.forPath", () => {
         AccessPath.forPath("foo.ts", {
           cwd,
           resolveBase: "/projects/my-app/sub",
+          platform: "linux",
         }).matchValues(),
       ).toEqual([
         "/projects/my-app/sub/foo.ts",
@@ -90,24 +99,59 @@ describe("AccessPath.forPath", () => {
     });
   });
 
+  describe("platform option", () => {
+    test("win32: builds lexical/match/boundary values with win32 rules", () => {
+      const ap = AccessPath.forPath("src\\foo.ts", {
+        cwd: "C:\\Projects\\App",
+        platform: "win32",
+      });
+      expect(ap.value()).toBe("c:\\projects\\app\\src\\foo.ts");
+      expect(ap.boundaryValue()).toBe("c:\\projects\\app\\src\\foo.ts");
+      expect(ap.matchValues()).toEqual([
+        "c:\\projects\\app\\src\\foo.ts",
+        "src\\foo.ts",
+      ]);
+    });
+
+    test("win32: lowercases the symlink-resolved boundary value", () => {
+      realpathSync.mockImplementation((p: string) =>
+        p === "c:\\projects\\app\\link" ? "C:\\Real\\App" : p,
+      );
+      expect(
+        AccessPath.forPath("link", {
+          cwd: "C:\\Projects\\App",
+          platform: "win32",
+        }).boundaryValue(),
+      ).toBe("c:\\real\\app");
+    });
+  });
+
   describe("boundaryValue()", () => {
     test("returns the canonical (symlink-resolved) form", () => {
       realpathSync.mockImplementation((p: string) =>
         p.startsWith("/tmp") ? `/private${p}` : p,
       );
-      expect(AccessPath.forPath("/tmp/x", { cwd }).boundaryValue()).toBe(
-        "/private/tmp/x",
-      );
+      expect(
+        AccessPath.forPath("/tmp/x", {
+          cwd,
+          platform: "linux",
+        }).boundaryValue(),
+      ).toBe("/private/tmp/x");
     });
 
     test("returns the lexical form when path has no symlinks", () => {
-      expect(AccessPath.forPath("/etc/hosts", { cwd }).boundaryValue()).toBe(
-        "/etc/hosts",
-      );
+      expect(
+        AccessPath.forPath("/etc/hosts", {
+          cwd,
+          platform: "linux",
+        }).boundaryValue(),
+      ).toBe("/etc/hosts");
     });
 
     test("returns empty string for empty input", () => {
-      expect(AccessPath.forPath("", { cwd }).boundaryValue()).toBe("");
+      expect(
+        AccessPath.forPath("", { cwd, platform: "linux" }).boundaryValue(),
+      ).toBe("");
     });
   });
 
@@ -117,14 +161,16 @@ describe("AccessPath.forPath", () => {
         p.startsWith("/tmp") ? `/private${p}` : p,
       );
       // Even when the path resolves to a different canonical, value() stays lexical.
-      expect(AccessPath.forPath("/tmp/x", { cwd }).value()).toBe("/tmp/x");
+      expect(
+        AccessPath.forPath("/tmp/x", { cwd, platform: "linux" }).value(),
+      ).toBe("/tmp/x");
     });
 
     test("normalizes the path against cwd", () => {
       // A relative path becomes an absolute lexical value.
-      expect(AccessPath.forPath("src/foo.ts", { cwd }).value()).toBe(
-        "/projects/my-app/src/foo.ts",
-      );
+      expect(
+        AccessPath.forPath("src/foo.ts", { cwd, platform: "linux" }).value(),
+      ).toBe("/projects/my-app/src/foo.ts");
     });
 
     test("normalizes a relative path against an explicit resolveBase", () => {
@@ -132,12 +178,15 @@ describe("AccessPath.forPath", () => {
         AccessPath.forPath("foo.ts", {
           cwd,
           resolveBase: "/projects/my-app/sub",
+          platform: "linux",
         }).value(),
       ).toBe("/projects/my-app/sub/foo.ts");
     });
 
     test("returns empty string for empty input", () => {
-      expect(AccessPath.forPath("", { cwd }).value()).toBe("");
+      expect(AccessPath.forPath("", { cwd, platform: "linux" }).value()).toBe(
+        "",
+      );
     });
   });
 });