@gotgenes/pi-permission-system 16.2.1 → 17.1.0

package/src/forwarded-permissions/permission-forwarder.ts

@@ -77,6 +77,8 @@ export interface ForwarderContext {
 export interface PermissionForwarderDeps {
   forwardingDir: string;
   subagentSessionsDir: string;
+  /** Host platform, injected from the composition root, for subagent-context path detection. */
+  platform: NodeJS.Platform;
   /** In-process subagent session registry for detection and forwarding target resolution. */
   registry?: SubagentSessionRegistry;
   /** Event bus used for UI prompt broadcasts. */
@@ -185,6 +187,7 @@ export interface InboxProcessor {
 export class PermissionForwarder implements ApprovalRequester, InboxProcessor {
   private readonly forwardingDir: string;
   private readonly subagentSessionsDir: string;
+  private readonly platform: NodeJS.Platform;
   private readonly registry: SubagentSessionRegistry | undefined;
   private readonly events: PermissionEventBus | undefined;
   private readonly logger: DebugReviewLogger;
@@ -199,6 +202,7 @@ export class PermissionForwarder implements ApprovalRequester, InboxProcessor {
   constructor(deps: PermissionForwarderDeps) {
     this.forwardingDir = deps.forwardingDir;
     this.subagentSessionsDir = deps.subagentSessionsDir;
+    this.platform = deps.platform;
     this.registry = deps.registry;
     this.events = deps.events;
     this.logger = deps.logger;
@@ -228,7 +232,12 @@ export class PermissionForwarder implements ApprovalRequester, InboxProcessor {
     }
 
     if (
-      !isSubagentExecutionContext(ctx, this.subagentSessionsDir, this.registry)
+      !isSubagentExecutionContext(
+        ctx,
+        this.subagentSessionsDir,
+        this.platform,
+        this.registry,
+      )
     ) {
       return Promise.resolve({ approved: false, state: "denied" });
     }
@@ -307,6 +316,7 @@ export class PermissionForwarder implements ApprovalRequester, InboxProcessor {
       isSubagent: isSubagentExecutionContext(
         ctx,
         this.subagentSessionsDir,
+        this.platform,
         this.registry,
       ),
       currentSessionId: requesterSessionId,

package/src/forwarding-manager.ts

@@ -30,6 +30,7 @@ export class ForwardingManager {
   constructor(
     private readonly subagentSessionsDir: string,
     private readonly forwarder: InboxProcessor,
+    private readonly platform: NodeJS.Platform,
     private readonly registry?: SubagentSessionRegistry,
   ) {}
 
@@ -42,7 +43,12 @@ export class ForwardingManager {
   start(ctx: ExtensionContext): void {
     if (
       !ctx.hasUI ||
-      isSubagentExecutionContext(ctx, this.subagentSessionsDir, this.registry)
+      isSubagentExecutionContext(
+        ctx,
+        this.subagentSessionsDir,
+        this.platform,
+        this.registry,
+      )
     ) {
       this.stop();
       return;

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

@@ -85,6 +85,7 @@ export class AgentPrepHandler {
       this.resolver,
       agentName,
       ctx.cwd,
+      this.session.getPlatform(),
     );
     this.session.setActiveSkillEntries(skillPromptResult.entries);
     return skillPromptResult.prompt !== event.systemPrompt

package/src/handlers/gates/bash-path-extractor.ts

@@ -1,21 +1,23 @@
 import { BashProgram } from "#src/access-intent/bash/program";
+import type { PathNormalizer } from "#src/path-normalizer";
 
 /**
- * Extract paths from a bash command string that resolve outside CWD.
+ * Extract paths from a bash command that resolve outside CWD.
  *
- * Thin facade over {@link BashProgram.externalPaths}; parses the command and
+ * Thin facade over {@link BashProgram.externalPaths}; parses the command
+ * through the injected {@link PathNormalizer} (platform + cwd baked in) and
  * returns the cd-aware external paths in their lexical (as-typed) string form.
  * See `BashProgram` for the parsing and resolution semantics.
  *
  * Returns `string[]` (not `AccessPath[]`) so the large projection-correctness
  * test suite in `bash-external-directory.test.ts` can assert path values
- * without migrating every call site.
+ * without migrating to the `AccessPath` accessors.
  */
 export async function extractExternalPathsFromBashCommand(
   command: string,
-  cwd: string,
+  normalizer: PathNormalizer,
 ): Promise<string[]> {
-  return (await BashProgram.parse(command, cwd))
+  return (await BashProgram.parse(command, normalizer))
     .externalPaths()
     .map((p) => p.value());
 }

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

@@ -1,3 +1,4 @@
+import type { AccessPath } from "#src/access-intent/access-path";
 import type { BashProgram } from "#src/access-intent/bash/program";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
@@ -41,20 +42,20 @@ export function describeBashPathGate(
   const tokens = candidates.map(({ token }) => token);
 
   // Tokens whose resolved state needs a check (deny/ask), paired with the raw
-  // token (prompt/decision display) and its policy values (the first of which
-  // is the canonical absolute path the approval pattern is derived from).
+  // token (prompt/decision display) and its `AccessPath` (whose `value()` is
+  // the lexical absolute path the approval pattern is derived from).
   const uncovered: Array<{
     token: string;
-    policyValues: readonly string[];
+    path: AccessPath;
     check: PermissionCheckResult;
   }> = [];
   let allSessionCovered = true;
 
-  for (const { token, policyValues } of candidates) {
+  for (const { token, path } of candidates) {
     const check = resolver.resolve({
-      kind: "path-values",
+      kind: "access-path",
       surface: "path",
-      values: policyValues,
+      path,
       agentName: tcc.agentName ?? undefined,
     });
 
@@ -71,11 +72,11 @@ export function describeBashPathGate(
     }
 
     if (check.state === "deny") {
-      uncovered.push({ token, policyValues, check });
+      uncovered.push({ token, path, check });
       break; // Short-circuit on deny.
     }
     if (check.state === "ask") {
-      uncovered.push({ token, policyValues, check });
+      uncovered.push({ token, path, check });
     }
   }
 
@@ -108,11 +109,10 @@ export function describeBashPathGate(
   // All tokens evaluate to allow — no restriction.
   if (!worstCheck || !worstToken || !worstEntry) return null;
 
-  // Derive the pattern from the canonical absolute policy value (the cd-aware
-  // resolved path), so it matches the values a later call produces. Falls back
-  // to the raw token only when no base was resolvable (no cwd / unknown cd).
-  const approvalBase = worstEntry.policyValues[0] ?? worstToken;
-  const pattern = deriveApprovalPattern(approvalBase);
+  // Derive the pattern from the lexical absolute form (the cd-aware resolved
+  // path), so it matches the values a later call produces. For an unknown base
+  // (`forLiteral`) `value()` is the raw token.
+  const pattern = deriveApprovalPattern(worstEntry.path.value());
   const askMessage = formatPathAskPrompt(
     tcc.toolName,
     worstToken,

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

@@ -1,10 +1,5 @@
-import { AccessPath } from "#src/access-intent/access-path";
-import {
-  getToolInputPath,
-  isPathOutsideWorkingDirectory,
-  isPiInfrastructureRead,
-  normalizePathForComparison,
-} from "#src/path-utils";
+import type { PathNormalizer } from "#src/path-normalizer";
+import { getToolInputPath, isPiInfrastructureRead } from "#src/path-utils";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
@@ -26,6 +21,8 @@ export function describeExternalDirectoryGate(
   tcc: ToolCallContext,
   infraDirs: string[],
   resolver: ScopedPermissionResolver,
+  normalizer: PathNormalizer,
+  platform: NodeJS.Platform,
   extractors?: ToolAccessExtractorLookup,
 ): GateResult {
   const externalDirectoryPath = getToolInputPath(
@@ -35,22 +32,25 @@ export function describeExternalDirectoryGate(
   );
   if (!externalDirectoryPath) return null;
 
-  if (!isPathOutsideWorkingDirectory(externalDirectoryPath, tcc.cwd)) {
+  if (!normalizer.isOutsideWorkingDirectory(externalDirectoryPath)) {
     return null;
   }
 
   // The boundary decision (above) and the infrastructure-read containment
   // check (below) use the canonical, symlink-resolved path; pattern matching
   // uses the typed and resolved aliases (#418).
-  const accessPath = AccessPath.forExternalDirectory(
-    externalDirectoryPath,
-    tcc.cwd,
-  );
+  const accessPath = normalizer.forPath(externalDirectoryPath);
   const canonicalExtPath = accessPath.boundaryValue();
 
   // ── Pi infrastructure read bypass ──────────────────────────────────────
   if (
-    isPiInfrastructureRead(tcc.toolName, canonicalExtPath, infraDirs, tcc.cwd)
+    isPiInfrastructureRead(
+      tcc.toolName,
+      canonicalExtPath,
+      infraDirs,
+      tcc.cwd,
+      platform,
+    )
   ) {
     return {
       action: "allow",
@@ -90,9 +90,7 @@ export function describeExternalDirectoryGate(
     resolver,
     tcc.agentName ?? undefined,
   );
-  const pattern = deriveApprovalPattern(
-    normalizePathForComparison(externalDirectoryPath, tcc.cwd),
-  );
+  const pattern = deriveApprovalPattern(accessPath.value());
 
   return {
     surface: "external_directory",

package/src/handlers/gates/path.ts

@@ -1,4 +1,5 @@
-import { getToolInputPath, normalizePathForComparison } from "#src/path-utils";
+import type { PathNormalizer } from "#src/path-normalizer";
+import { getToolInputPath } from "#src/path-utils";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
@@ -17,15 +18,20 @@ import type { ToolCallContext } from "./types";
 export function describePathGate(
   tcc: ToolCallContext,
   resolver: ScopedPermissionResolver,
+  normalizer: PathNormalizer,
   extractors?: ToolAccessExtractorLookup,
 ): GateResult {
   const filePath = getToolInputPath(tcc.toolName, tcc.input, extractors);
   if (!filePath) return null;
 
+  // Emit an access-path intent so the resolver matches the lexical aliases
+  // *and* the canonical (symlink-resolved) form, the same set
+  // `external_directory` matches (#418, #486).
+  const accessPath = normalizer.forPath(filePath);
   const check = resolver.resolve({
-    kind: "tool",
+    kind: "access-path",
     surface: "path",
-    input: { path: filePath },
+    path: accessPath,
     agentName: tcc.agentName ?? undefined,
   });
 
@@ -36,10 +42,9 @@ export function describePathGate(
   // "path" key should not trigger path-level prompts (#58).
   if (check.matchedPattern === undefined) return null;
 
-  // Resolve to the canonical (cwd-anchored, absolute) path so the approval
-  // pattern matches the policy values a later call produces.
-  const approvalPath = normalizePathForComparison(filePath, tcc.cwd);
-  const pattern = deriveApprovalPattern(approvalPath);
+  // Derive the approval pattern from the lexical absolute form so it matches
+  // the policy values a later call produces.
+  const pattern = deriveApprovalPattern(accessPath.value());
 
   const descriptor: GateDescriptor = {
     surface: "path",

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

@@ -15,6 +15,7 @@ import type { ToolCallContext } from "./types";
  */
 export function describeSkillReadGate(
   tcc: ToolCallContext,
+  platform: NodeJS.Platform,
   getActiveSkillEntries: () => SkillPromptEntry[],
 ): GateDescriptor | null {
   const activeSkillEntries = getActiveSkillEntries();
@@ -29,10 +30,15 @@ export function describeSkillReadGate(
     return null;
   }
 
-  const normalizedReadPath = normalizePathForComparison(path, tcc.cwd);
+  const normalizedReadPath = normalizePathForComparison(
+    path,
+    tcc.cwd,
+    platform,
+  );
   const matchedSkill = findSkillPathMatch(
     normalizedReadPath,
     activeSkillEntries,
+    platform,
   );
 
   if (!matchedSkill) {

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

@@ -1,4 +1,5 @@
 import { BashProgram } from "#src/access-intent/bash/program";
+import type { PathNormalizer } from "#src/path-normalizer";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
 import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
@@ -36,6 +37,10 @@ export interface ToolCallGateInputs {
   getInfrastructureReadDirs(): string[];
   /** Resolved tool-preview formatter options from the current config. */
   getToolPreviewLimits(): ToolPreviewFormatterOptions;
+  /** The session's path normalizer (platform + cwd baked in). */
+  getPathNormalizer(): PathNormalizer;
+  /** The host platform injected at the composition root. */
+  getPlatform(): NodeJS.Platform;
 }
 
 /**
@@ -64,9 +69,10 @@ export class ToolCallGatePipeline {
     // Parse the bash command exactly once per evaluate; the three bash gates
     // share this single BashProgram instead of each re-parsing (#308).
     const command = getNonEmptyString(toRecord(tcc.input).command);
+    const normalizer = this.inputs.getPathNormalizer();
     const bashProgram =
       tcc.toolName === "bash" && command
-        ? await BashProgram.parse(command, tcc.cwd)
+        ? await BashProgram.parse(command, normalizer)
         : null;
 
     const formatter = new ToolPreviewFormatter(
@@ -75,16 +81,22 @@ export class ToolCallGatePipeline {
     );
 
     const infraDirs = this.inputs.getInfrastructureReadDirs();
+    const platform = this.inputs.getPlatform();
 
     const gateProducers: Array<() => GateResult | Promise<GateResult>> = [
       () =>
-        describeSkillReadGate(tcc, () => this.inputs.getActiveSkillEntries()),
-      () => describePathGate(tcc, this.resolver, this.customExtractors),
+        describeSkillReadGate(tcc, platform, () =>
+          this.inputs.getActiveSkillEntries(),
+        ),
+      () =>
+        describePathGate(tcc, this.resolver, normalizer, this.customExtractors),
       () =>
         describeExternalDirectoryGate(
           tcc,
           infraDirs,
           this.resolver,
+          normalizer,
+          platform,
           this.customExtractors,
         ),
       () => describeBashExternalDirectoryGate(tcc, bashProgram, this.resolver),
@@ -108,7 +120,12 @@ export class ToolCallGatePipeline {
                 input: tcc.input,
                 agentName: tcc.agentName ?? undefined,
               });
-        const toolDescriptor = describeToolGate(tcc, toolCheck, formatter);
+        const toolDescriptor = describeToolGate(
+          tcc,
+          toolCheck,
+          formatter,
+          platform,
+        );
         toolDescriptor.preCheck = toolCheck;
         return toolDescriptor;
       },

package/src/handlers/gates/tool.ts

@@ -23,12 +23,13 @@ import type { ToolCallContext } from "./types";
 function deriveSuggestionValue(
   tcc: ToolCallContext,
   check: PermissionCheckResult,
+  platform: NodeJS.Platform,
 ): string {
   if (tcc.toolName === "bash") return check.command ?? "";
   if (tcc.toolName === "mcp") return check.target ?? "mcp";
   const path = getPathBearingToolPath(tcc.toolName, tcc.input);
   if (path === null) return "*";
-  return normalizePathForComparison(path, tcc.cwd);
+  return normalizePathForComparison(path, tcc.cwd, platform);
 }
 
 /**
@@ -41,6 +42,7 @@ export function describeToolGate(
   tcc: ToolCallContext,
   check: PermissionCheckResult,
   formatter: ToolPreviewFormatter,
+  platform: NodeJS.Platform,
 ): GateDescriptor {
   const permissionLogContext = formatter.getPermissionLogContext(
     check,
@@ -51,7 +53,7 @@ export function describeToolGate(
   // Compute session approval suggestion for the "for this session" option.
   const suggestion = suggestSessionPattern(
     tcc.toolName,
-    deriveSuggestionValue(tcc, check),
+    deriveSuggestionValue(tcc, check, platform),
   );
 
   const askMessage = formatAskPrompt(

package/src/index.ts

@@ -42,7 +42,14 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   // getPackageDir() is Pi's own install dir; auto-allow it for read-only tools
   // so the agent can read Pi's bundled docs/examples regardless of layout.
   const paths = computeExtensionPaths(agentDir, getPackageDir());
-  const permissionManager = new PermissionManager({ agentDir });
+  // The single process.platform read for the whole extension; injected into the
+  // session (PathNormalizer) and, later, rule evaluation. Interior modules must
+  // not read process.platform (enforced by the eslint guard scoped to src/).
+  const hostPlatform = process.platform;
+  const permissionManager = new PermissionManager({
+    agentDir,
+    platform: hostPlatform,
+  });
   const sessionRules = new SessionRules();
   const subagentRegistry = getSubagentSessionRegistry();
   const formatterRegistry = new ToolInputFormatterRegistry();
@@ -73,6 +80,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   const forwardingDeps: PermissionForwarderDeps = {
     forwardingDir: paths.forwardingDir,
     subagentSessionsDir: paths.subagentSessionsDir,
+    platform: hostPlatform,
     registry: subagentRegistry,
     events: pi.events,
     logger,
@@ -91,6 +99,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   const gateway = new PromptingGateway({
     config: configStore,
     subagentSessionsDir: paths.subagentSessionsDir,
+    platform: hostPlatform,
     registry: subagentRegistry,
     prompter,
   });
@@ -100,12 +109,14 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     new ForwardingManager(
       paths.subagentSessionsDir,
       forwarder,
+      hostPlatform,
       subagentRegistry,
     ),
     permissionManager,
     sessionRules,
     configStore,
     gateway,
+    hostPlatform,
   );
 
   // refresh() must run after `session` is assigned: a debug-write IO failure

package/src/input-normalizer.ts

@@ -66,13 +66,14 @@ export function normalizeInput(
   toolName: string,
   input: unknown,
   configuredMcpServerNames: readonly string[],
+  platform: NodeJS.Platform,
   cwd?: string,
 ): NormalizedInput {
   // --- Special surfaces (path, external_directory) ---
   if (SPECIAL_PERMISSION_KEYS.has(toolName)) {
     return {
       surface: toolName,
-      values: normalizePathSurfaceValues(input, cwd),
+      values: normalizePathSurfaceValues(input, platform, cwd),
       resultExtras: {},
     };
   }
@@ -123,7 +124,7 @@ export function normalizeInput(
   if (PATH_BEARING_TOOLS.has(toolName)) {
     return {
       surface: toolName,
-      values: normalizePathSurfaceValues(input, cwd),
+      values: normalizePathSurfaceValues(input, platform, cwd),
       resultExtras: {},
     };
   }
@@ -149,9 +150,13 @@ export function normalizeInput(
  * Only `input.path` is read — policy values are never sourced from any other
  * (potentially attacker-controlled) field on the raw tool input.
  */
-function normalizePathSurfaceValues(input: unknown, cwd?: string): string[] {
+function normalizePathSurfaceValues(
+  input: unknown,
+  platform: NodeJS.Platform,
+  cwd?: string,
+): string[] {
   const path = getNonEmptyString(toRecord(input).path);
   if (path === null) return ["*"];
-  const values = getPathPolicyValues(path, cwd ? { cwd } : {});
+  const values = getPathPolicyValues(path, cwd ? { cwd } : {}, platform);
   return values.length > 0 ? values : ["*"];
 }

package/src/path-normalizer.ts

@@ -0,0 +1,70 @@
+import { posix as posixPath, win32 as winPath } from "node:path";
+
+import { AccessPath } from "./access-intent/access-path";
+import {
+  isPathOutsideWorkingDirectory,
+  isPathWithinDirectory,
+} from "./path-utils";
+
+/**
+ * Path-interpretation collaborator, constructed once at the session edge with
+ * the two ambient inputs — the host `platform` and the session `cwd` — baked
+ * in, and handed raw path tokens thereafter.
+ *
+ * The bash path pipeline and the per-tool/external-directory gates ask this
+ * object the platform-dependent questions ("is this path absolute *under our
+ * platform*?", "resolve this `cd` offset *against our cwd*") and receive
+ * prepared {@link AccessPath} values, instead of reading `process.platform`
+ * ambiently or threading `cwd` through every call. Internally it selects the
+ * `win32`/`posix` path flavor once and delegates to the platform-parameterized
+ * `path-utils` / `AccessPath` primitives.
+ */
+export class PathNormalizer {
+  private readonly impl: typeof posixPath;
+
+  constructor(
+    private readonly platform: NodeJS.Platform,
+    private readonly cwd: string,
+  ) {
+    this.impl = platform === "win32" ? winPath : posixPath;
+  }
+
+  /** Build an AccessPath for a token, resolved against `resolveBase` (default cwd). */
+  forPath(pathValue: string, options?: { resolveBase?: string }): AccessPath {
+    return AccessPath.forPath(pathValue, {
+      cwd: this.cwd,
+      resolveBase: options?.resolveBase,
+      platform: this.platform,
+    });
+  }
+
+  /** Build a literal-only AccessPath (unknown base after a non-literal `cd`). */
+  forLiteral(literal: string): AccessPath {
+    return AccessPath.forLiteral(literal);
+  }
+
+  /** Platform-aware absoluteness (`win32` vs `posix` rules). */
+  isAbsolute(pathValue: string): boolean {
+    return this.impl.isAbsolute(pathValue);
+  }
+
+  /** Resolve a `cd`-folded offset against the baked cwd (platform-aware). */
+  resolveBase(offset: string): string {
+    return this.impl.resolve(this.cwd, offset);
+  }
+
+  /** Join a `cd` offset with a relative target (platform-aware), for cd-folding. */
+  joinBase(offset: string, target: string): string {
+    return this.impl.join(offset, target);
+  }
+
+  /** Containment of `pathValue` within `directory` (platform-aware). */
+  isWithinDirectory(pathValue: string, directory: string): boolean {
+    return isPathWithinDirectory(pathValue, directory, this.platform);
+  }
+
+  /** Canonical (symlink-resolved) outside-cwd test against the baked cwd. */
+  isOutsideWorkingDirectory(pathValue: string): boolean {
+    return isPathOutsideWorkingDirectory(pathValue, this.cwd, this.platform);
+  }
+}