@gotgenes/pi-permission-system 17.0.0 → 17.1.1

package/src/access-intent/bash/token-classification.ts

@@ -1,13 +1,19 @@
 /**
  * Pure, synchronous token-classification helpers for bash path extraction.
  *
- * Exports two classifiers consumed by `cwd-projection.ts`:
+ * Exports two classifiers consumed by `bash-path-resolver.ts`:
  *   - `classifyTokenAsPathCandidate` — strict gate for the external-directory guard.
  *   - `classifyTokenAsRuleCandidate` — broader gate for cross-cutting `path` rules.
  *
  * Both classifiers share the private `rejectNonPathToken` predicate that captures
  * the seven rejection cases common to both (the production clone this module was
  * extracted to eliminate).
+ *
+ * Both classifiers recognize Windows drive-letter absolute paths (`C:/…`, `C:\…`)
+ * unconditionally on all platforms. On POSIX the token resolves as a real in-CWD
+ * relative path and is gated by the `path` surface; on Windows the `PathNormalizer`
+ * routes it through the absolute-path branch. Shape recognition is platform-independent
+ * string matching; the platform-sensitive absoluteness decision belongs to `PathNormalizer`.
  */
 
 // ── Public classifiers ─────────────────────────────────────────────────────
@@ -19,6 +25,7 @@
  * - Absolute paths (starting with `/`)
  * - Home-relative paths (starting with `~/`)
  * - Parent-traversal paths (containing `..`)
+ * - Windows drive-letter absolute paths (`C:/…` or `C:\…`)
  *
  * Returns the raw token string if it qualifies, or `null` to skip.
  */
@@ -28,6 +35,7 @@ export function classifyTokenAsPathCandidate(token: string): string | null {
   if (token.startsWith("/")) return token;
   if (token.startsWith("~/")) return token;
   if (token.includes("..")) return token;
+  if (WINDOWS_DRIVE_PATH_PATTERN.test(token)) return token;
 
   return null;
 }
@@ -38,8 +46,13 @@ export function classifyTokenAsPathCandidate(token: string): string | null {
  * Accepts the same shapes as `classifyTokenAsPathCandidate`, plus:
  * - Dot-files and `./`-relative paths (starting with `.`)
  * - Any relative path containing `/` (e.g. `src/foo.ts`)
+ * - Windows drive-letter absolute paths (`C:/…` or `C:\…`)
  *
  * The `~/foo` case is covered by `includes("/")` — no separate `~/` branch needed.
+ * The forward-slash drive form (`C:/…`) is also caught by `includes("/")`, but the
+ * explicit `WINDOWS_DRIVE_PATH_PATTERN` branch makes both separator forms first-class
+ * and order-independent, and covers the backslash-only form (`D:\…`) which `includes("/")`
+ * cannot reach.
  *
  * Does NOT require the strict "must start with `/` or `~/` or contain `..`"
  * gate that the external-directory classifier uses.
@@ -52,12 +65,22 @@ export function classifyTokenAsRuleCandidate(token: string): string | null {
   if (token.startsWith(".")) return token;
   if (token.includes("/")) return token; // covers ~/ paths and all relative paths with /
   if (token.includes("..")) return token; // bare ".." (no slash)
+  if (WINDOWS_DRIVE_PATH_PATTERN.test(token)) return token; // backslash-only drive form
 
   return null;
 }
 
 // ── Private rejection predicate ────────────────────────────────────────────
 
+/**
+ * Windows drive-letter absolute path: a single ASCII letter, a colon, then a
+ * separator (`/` or `\`). Matches `C:/…` and `C:\…` but not drive-relative
+ * `C:foo` (no separator) or multi-letter schemes (`https:`, `mailto:`).
+ * Single-letter schemes with `//` (e.g. `c://x`) are already rejected by
+ * `URL_PATTERN` before this pattern is tested.
+ */
+const WINDOWS_DRIVE_PATH_PATTERN = /^[a-zA-Z]:[/\\]/;
+
 /**
  * URL pattern to skip tokens that look like URLs rather than paths.
  */

package/src/canonicalize-path.ts

@@ -1,5 +1,5 @@
 import { realpathSync } from "node:fs";
-import { join } from "node:path";
+import { posix as posixPath, win32 as winPath } from "node:path";
 
 /**
  * Resolve symlinks in an absolute path, best-effort.
@@ -11,16 +11,22 @@ import { join } from "node:path";
  * encountered (e.g. `EACCES`, `ELOOP`), so callers fall back to lexical
  * containment for paths that cannot be resolved.
  */
-export function canonicalizePath(absolutePath: string): string {
+export function canonicalizePath(
+  absolutePath: string,
+  platform: NodeJS.Platform,
+): string {
   if (!absolutePath) return absolutePath;
 
-  const parts = absolutePath.split("/").filter(Boolean);
+  const impl = platform === "win32" ? winPath : posixPath;
+  const root = impl.parse(absolutePath).root;
+  const rest = absolutePath.slice(root.length);
+  const parts = rest.split(impl.sep).filter(Boolean);
   for (let i = parts.length; i >= 0; i--) {
-    const candidate = "/" + parts.slice(0, i).join("/");
+    const candidate = root + parts.slice(0, i).join(impl.sep);
     try {
       const real = realpathSync(candidate);
       const tail = parts.slice(i);
-      return tail.length === 0 ? real : join(real, ...tail);
+      return tail.length === 0 ? real : impl.join(real, ...tail);
     } catch (error) {
       const code = (error as NodeJS.ErrnoException).code;
       if (code !== "ENOENT" && code !== "ENOTDIR") return absolutePath;

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

@@ -84,7 +84,7 @@ export class AgentPrepHandler {
       toolPromptResult.prompt,
       this.resolver,
       agentName,
-      ctx.cwd,
+      this.session.getPathNormalizer(),
     );
     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/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 } 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,7 @@ export function describeExternalDirectoryGate(
   tcc: ToolCallContext,
   infraDirs: string[],
   resolver: ScopedPermissionResolver,
+  normalizer: PathNormalizer,
   extractors?: ToolAccessExtractorLookup,
 ): GateResult {
   const externalDirectoryPath = getToolInputPath(
@@ -35,22 +31,17 @@ 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.forPath(externalDirectoryPath, {
-    cwd: tcc.cwd,
-  });
-  const canonicalExtPath = accessPath.boundaryValue();
+  const accessPath = normalizer.forPath(externalDirectoryPath);
 
   // ── Pi infrastructure read bypass ──────────────────────────────────────
-  if (
-    isPiInfrastructureRead(tcc.toolName, canonicalExtPath, infraDirs, tcc.cwd)
-  ) {
+  if (normalizer.isInfrastructureRead(tcc.toolName, accessPath, infraDirs)) {
     return {
       action: "allow",
       log: {
@@ -89,9 +80,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,4 @@
-import { AccessPath } from "#src/access-intent/access-path";
+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";
@@ -18,6 +18,7 @@ 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);
@@ -26,7 +27,7 @@ export function describePathGate(
   // 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 = AccessPath.forPath(filePath, { cwd: tcc.cwd });
+  const accessPath = normalizer.forPath(filePath);
   const check = resolver.resolve({
     kind: "access-path",
     surface: "path",

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

@@ -1,4 +1,4 @@
-import { normalizePathForComparison } from "#src/path-utils";
+import type { PathNormalizer } from "#src/path-normalizer";
 import { formatSkillPathAskPrompt } from "#src/permission-prompts";
 import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
 import { findSkillPathMatch } from "#src/skill-prompt-sanitizer";
@@ -15,6 +15,7 @@ import type { ToolCallContext } from "./types";
  */
 export function describeSkillReadGate(
   tcc: ToolCallContext,
+  normalizer: PathNormalizer,
   getActiveSkillEntries: () => SkillPromptEntry[],
 ): GateDescriptor | null {
   const activeSkillEntries = getActiveSkillEntries();
@@ -29,10 +30,11 @@ export function describeSkillReadGate(
     return null;
   }
 
-  const normalizedReadPath = normalizePathForComparison(path, tcc.cwd);
+  const normalizedReadPath = normalizer.comparableValue(path);
   const matchedSkill = findSkillPathMatch(
     normalizedReadPath,
     activeSkillEntries,
+    normalizer,
   );
 
   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,21 @@ 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, normalizer, () =>
+          this.inputs.getActiveSkillEntries(),
+        ),
+      () =>
+        describePathGate(tcc, this.resolver, normalizer, this.customExtractors),
       () =>
         describeExternalDirectoryGate(
           tcc,
           infraDirs,
           this.resolver,
+          normalizer,
           this.customExtractors,
         ),
       () => describeBashExternalDirectoryGate(tcc, bashProgram, this.resolver),
@@ -108,7 +119,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,100 @@
+import { posix as posixPath, win32 as winPath } from "node:path";
+
+import { AccessPath } from "./access-intent/access-path";
+import {
+  isPathOutsideWorkingDirectory,
+  isPathWithinDirectory,
+  isPiInfrastructureRead,
+  normalizePathForComparison,
+} 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);
+  }
+
+  /**
+   * Lexical (not symlink-resolved) comparison value, resolved against the baked
+   * cwd. Mirrors the as-typed absolute form used for skill-prompt matching;
+   * touches no filesystem, unlike {@link forPath}'s canonical alias.
+   */
+  comparableValue(pathValue: string): string {
+    return normalizePathForComparison(pathValue, this.cwd, this.platform);
+  }
+
+  /**
+   * Pi infrastructure-read containment for a read-only tool, decided against
+   * the canonical (symlink-resolved) path and the baked cwd/platform. Takes the
+   * already-built {@link AccessPath} so the caller does not re-resolve it.
+   */
+  isInfrastructureRead(
+    toolName: string,
+    accessPath: AccessPath,
+    infraDirs: readonly string[],
+  ): boolean {
+    return isPiInfrastructureRead(
+      toolName,
+      accessPath.boundaryValue(),
+      infraDirs,
+      this.cwd,
+      this.platform,
+    );
+  }
+}