@gotgenes/pi-permission-system 17.0.0 → 17.1.1

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [17.1.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v17.1.0...pi-permission-system-v17.1.1) (2026-06-29)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** gate Windows drive-letter paths in bash external_directory ([#508](https://github.com/gotgenes/pi-packages/issues/508)) ([2d33183](https://github.com/gotgenes/pi-packages/commit/2d331834254f58bcb0782b3da353132821536296))
+
+## [17.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v17.0.0...pi-permission-system-v17.1.0) (2026-06-28)
+
+
+### Features
+
+* **pi-permission-system:** add PathNormalizer collaborator ([#510](https://github.com/gotgenes/pi-packages/issues/510)) ([d016089](https://github.com/gotgenes/pi-packages/commit/d016089690aff3821eabd5bd5351bb3a0c3639d4))
+
 ## [17.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v16.2.1...pi-permission-system-v17.0.0) (2026-06-27)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "17.0.0",
+  "version": "17.1.1",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {

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

@@ -87,13 +87,13 @@ export class AccessPath {
    */
   static forPath(
     pathValue: string,
-    options: { cwd: string; resolveBase?: string },
+    options: { cwd: string; resolveBase?: string; platform: NodeJS.Platform },
   ): AccessPath {
-    const { cwd, resolveBase = cwd } = options;
+    const { cwd, resolveBase = cwd, platform } = options;
     return new AccessPath(
-      normalizePathForComparison(pathValue, resolveBase),
-      getPathPolicyValues(pathValue, { cwd, resolveBase }),
-      canonicalNormalizePathForComparison(pathValue, resolveBase),
+      normalizePathForComparison(pathValue, resolveBase, platform),
+      getPathPolicyValues(pathValue, { cwd, resolveBase }, platform),
+      canonicalNormalizePathForComparison(pathValue, resolveBase, platform),
     );
   }
 

package/src/access-intent/bash/bash-path-resolver.ts

@@ -0,0 +1,535 @@
+import type { AccessPath } from "#src/access-intent/access-path";
+import {
+  ARG_NODE_TYPES,
+  SKIP_SUBTREE_TYPES,
+} from "#src/access-intent/bash/node-text";
+import type { TSNode } from "#src/access-intent/bash/parser";
+import {
+  classifyTokenAsPathCandidate,
+  classifyTokenAsRuleCandidate,
+} from "#src/access-intent/bash/token-classification";
+import {
+  collectCommandTokens,
+  collectPathCandidateTokens,
+  collectRedirectTokens,
+  extractCommandName,
+} from "#src/access-intent/bash/token-collection";
+import type { PathNormalizer } from "#src/path-normalizer";
+import { isSafeSystemPath, normalizePathPolicyLiteral } from "#src/path-utils";
+
+// ── Internal types ───────────────────────────────────────────────────────────
+
+/**
+ * The working directory in force where a path candidate appears.
+ *
+ * A `known` base carries an `offset` to be joined with `cwd` at resolution
+ * time: a relative-or-absolute path string built by folding the literal targets
+ * of current-shell `cd` commands (`""` = `cwd`); an absolute offset (from
+ * `cd /abs`) ignores `cwd` at resolution time.
+ * An `unknown` base marks a non-literal `cd` target (`cd "$DIR"`, `cd $(…)`,
+ * `cd -`, bare `cd`, `cd ~…`) that made the effective directory unresolvable.
+ */
+type EffectiveBase =
+  | { readonly kind: "known"; readonly offset: string }
+  | { readonly kind: "unknown" };
+
+/**
+ * A path-candidate token paired with the effective working directory projected
+ * onto the point in the command stream where it appears.
+ */
+interface PathCandidate {
+  readonly token: string;
+  readonly base: EffectiveBase;
+}
+
+// ── Public output types ──────────────────────────────────────────────────────
+
+export interface BashPathRuleCandidate {
+  /** Raw path-like token shown in prompts, logs, and session approvals. */
+  readonly token: string;
+  /** The path's lexical and canonical forms for permission policy matching. */
+  readonly path: AccessPath;
+}
+
+/**
+ * The filesystem paths a bash program references, resolved against the working
+ * directory and platform — the two typed slices {@link BashProgram} exposes.
+ */
+export interface ResolvedBashPaths {
+  /** Deduplicated paths resolving outside the working directory (#418). */
+  readonly externalPaths: readonly AccessPath[];
+  /** Every path-rule token paired with its cd-aware policy values (#393). */
+  readonly ruleCandidates: readonly BashPathRuleCandidate[];
+}
+
+// ── Walk-time constants ──────────────────────────────────────────────────────
+
+/** The working directory in force at the start of a program (`cwd`). */
+const CWD_BASE: EffectiveBase = { kind: "known", offset: "" };
+
+/** The effective directory after a non-literal or unresolvable `cd`. */
+const UNKNOWN_BASE: EffectiveBase = { kind: "unknown" };
+
+/**
+ * Resolves the filesystem paths a parsed bash program references.
+ *
+ * Holds a {@link PathNormalizer} (platform + cwd baked in) as its collaborator
+ * and answers all platform/cwd-dependent questions through it — `cd`-base
+ * folding (`isAbsolute`/`joinBase`), per-candidate resolution (`forPath`/
+ * `forLiteral`/`resolveBase`), and the outside-cwd boundary decision — so no
+ * walk step re-reads the platform or threads the cwd.
+ *
+ * Tell-don't-ask: callers hand it a parsed tree and receive the resolved
+ * {@link ResolvedBashPaths} slices in one {@link resolve} call; the AST walk,
+ * the `cd`-folding state, and the intermediate path candidates stay private.
+ * One instance per parse ({@link BashProgram.parse} constructs it with the
+ * session normalizer).
+ */
+export class BashPathResolver {
+  constructor(private readonly normalizer: PathNormalizer) {}
+
+  /**
+   * Resolve a parsed bash program's path references into its external-path and
+   * rule-candidate slices, walking the AST exactly once.
+   */
+  resolve(rootNode: TSNode): ResolvedBashPaths {
+    const candidates = this.collectPathCandidates(rootNode);
+    return {
+      externalPaths: this.projectExternalPaths(candidates),
+      ruleCandidates: this.projectRuleCandidates(candidates),
+    };
+  }
+
+  // ── AST walk — collect PathCandidates ──────────────────────────────────
+
+  /**
+   * Walk the AST once, collecting every path-candidate token tagged with the
+   * effective working directory projected onto its position.
+   *
+   * The effective directory is stateful: it starts at `cwd` and each
+   * current-shell `cd <literal>` (joined by `&&`, `||`, `;`, or a newline)
+   * folds into it for subsequent commands.
+   * A `cd` inside a pipeline or a backgrounded command runs in a subshell and
+   * does not update the running directory; subshell and brace-group interiors
+   * inherit the enclosing base without folding their own `cd`s (a conservative
+   * first tier).
+   */
+  private collectPathCandidates(rootNode: TSNode): PathCandidate[] {
+    const out: PathCandidate[] = [];
+    this.walkForCandidates(rootNode, CWD_BASE, out);
+    return out;
+  }
+
+  /**
+   * Collect a single node's candidates tagged with `base`, returning the
+   * effective base in force *after* the node (the input base unless the node is
+   * a current-shell `cd <literal>` that folds the running directory).
+   */
+  private walkForCandidates(
+    node: TSNode,
+    base: EffectiveBase,
+    out: PathCandidate[],
+  ): EffectiveBase {
+    switch (node.type) {
+      case "program":
+      case "list":
+      case "redirected_statement":
+        return this.walkCurrentShellSequence(node, base, out);
+      case "command":
+        tagTokens(collectCommandTokens(node), base, out);
+        return this.foldCd(node, base);
+      case "pipeline":
+        // tree-sitter-bash mis-groups a redirect-bearing `&&`/`;` list as the
+        // first stage of a pipeline (`cd a && pnpm x 2>&1 | tail` parses as
+        // `(cd a && pnpm x 2>&1) | tail`), burying a current-shell `cd` inside
+        // a node the `default` case treats as non-folding. Recover bash operator
+        // precedence (`|` binds tighter than `&&`/`||`/`;`): fold the first
+        // stage's leading current-shell commands while keeping its terminal
+        // command and every downstream stage as non-folding subshells (#454).
+        return this.walkPipeline(node, base, out);
+      case "subshell":
+        // A subshell runs in a child shell: its interior `cd`s fold within the
+        // subshell but reset on exit, so the folded base is discarded.
+        this.walkCurrentShellSequence(node, base, out);
+        return base;
+      case "compound_statement":
+        // A `{ … }` brace group runs in the current shell, so its `cd`s persist
+        // to following commands — thread and return the folded base.
+        return this.walkCurrentShellSequence(node, base, out);
+      default:
+        // Pipelines, control-flow bodies, redirect targets, and command/process
+        // substitution interiors: collect every candidate in the subtree tagged
+        // with the enclosing base and do not fold their internal `cd`s. (Folding
+        // inside substitutions is deferred — conservative, never under-flags.)
+        tagTokens(collectPathCandidateTokens(node), base, out);
+        return base;
+    }
+  }
+
+  /**
+   * Fold a current-shell sequence (`program` / `list` / `redirected_statement`):
+   * thread the effective base left-to-right through the children so a `cd`
+   * updates the base for following siblings.
+   * A statement immediately followed by the background operator (`&`) runs in a
+   * subshell, so its folded base is discarded.
+   */
+  private walkCurrentShellSequence(
+    seqNode: TSNode,
+    base: EffectiveBase,
+    out: PathCandidate[],
+  ): EffectiveBase {
+    let current = base;
+    for (let i = 0; i < seqNode.childCount; i++) {
+      const child = seqNode.child(i);
+      if (!child?.isNamed) continue;
+      if (SKIP_SUBTREE_TYPES.has(child.type)) continue;
+      const after = this.walkForCandidates(child, current, out);
+      current = isBackgrounded(seqNode, i) ? current : after;
+    }
+    return current;
+  }
+
+  /**
+   * Walk a `pipeline` node, returning the effective base in force after it.
+   *
+   * Each stage of a true pipeline (`A | B | C`) runs in a subshell, so a `cd`
+   * inside any stage must not leak — the base normally passes through unchanged.
+   * The exception is the first stage: tree-sitter-bash wraps a redirect-bearing
+   * current-shell `&&`/`;` list (`cd a && pnpm x 2>&1 | tail`) as that stage,
+   * and bash precedence makes the list's leading commands current-shell, so they
+   * fold and the folded base persists past the pipeline to following siblings.
+   *
+   * The terminal command of the first stage is the real pipe stage (a subshell)
+   * and must not fold; every stage after a `|` is a downstream subshell stage
+   * and collects tokens against the folded base without folding (#454).
+   */
+  private walkPipeline(
+    node: TSNode,
+    base: EffectiveBase,
+    out: PathCandidate[],
+  ): EffectiveBase {
+    let current = base;
+    let first = true;
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i);
+      if (!child?.isNamed) continue;
+      if (SKIP_SUBTREE_TYPES.has(child.type)) continue;
+      if (first) {
+        current = this.foldPipelineFirstStage(child, current, out);
+        first = false;
+        continue;
+      }
+      // Downstream stage (after a `|`): subshell — collect against the folded
+      // base, do not fold.
+      tagTokens(collectPathCandidateTokens(child), current, out);
+    }
+    return current;
+  }
+
+  /**
+   * Collect the first pipe stage's candidates, folding its leading current-shell
+   * `cd` commands when tree-sitter wrapped a `list` or `redirected_statement`
+   * around them.
+   * The terminal command of that container is the real pipe stage (a subshell)
+   * and is collected without folding.
+   * A bare `command` first stage (a true pipeline first stage such as
+   * `cd nested | cat ../b`) is a subshell: it collects against the input base
+   * and does not fold.
+   */
+  private foldPipelineFirstStage(
+    node: TSNode,
+    base: EffectiveBase,
+    out: PathCandidate[],
+  ): EffectiveBase {
+    if (node.type === "list")
+      return this.foldListExceptTerminal(node, base, out);
+    if (node.type === "redirected_statement") {
+      let current = base;
+      for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        if (!child?.isNamed) continue;
+        if (child.type === "file_redirect") {
+          // Redirect destinations are part of the piped stage; collect them
+          // against the folded base without folding.
+          tagTokens(collectRedirectTokens(child), current, out);
+          continue;
+        }
+        // The inner statement is the `list`/`command` being redirected; fold its
+        // leading current-shell commands via the terminal-excluding walk.
+        current = this.foldPipelineFirstStage(child, current, out);
+      }
+      return current;
+    }
+    // Bare `command` or any other shape: a true subshell first stage.
+    tagTokens(collectPathCandidateTokens(node), base, out);
+    return base;
+  }
+
+  /**
+   * Fold every named, non-skip child of a `list` except the last, threading the
+   * effective base left-to-right through the leading current-shell commands; the
+   * terminal child is the real pipe stage and is collected without folding.
+   */
+  private foldListExceptTerminal(
+    node: TSNode,
+    base: EffectiveBase,
+    out: PathCandidate[],
+  ): EffectiveBase {
+    const namedChildren: TSNode[] = [];
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i);
+      if (child?.isNamed && !SKIP_SUBTREE_TYPES.has(child.type)) {
+        namedChildren.push(child);
+      }
+    }
+    let current = base;
+    for (let i = 0; i < namedChildren.length; i++) {
+      const child = namedChildren[i];
+      if (i < namedChildren.length - 1) {
+        current = this.walkForCandidates(child, current, out);
+      } else {
+        // Terminal child = the real pipe stage; collect without folding.
+        tagTokens(collectPathCandidateTokens(child), current, out);
+      }
+    }
+    return current;
+  }
+
+  /**
+   * Compute the effective base after a command runs.
+   * Returns `base` unchanged unless the command is `cd`:
+   *
+   * - `cd /abs` (absolute literal) → a fresh known base, recovering from an
+   *   earlier unknown base.
+   * - `cd rel` (relative literal) → fold into a known base, or stay unknown if
+   *   the base was already unknown.
+   * - `cd "$DIR"` / `cd $(…)` / `cd -` / bare `cd` / `cd ~…` (non-literal) →
+   *   unknown.
+   */
+  private foldCd(commandNode: TSNode, base: EffectiveBase): EffectiveBase {
+    if (extractCommandName(commandNode) !== "cd") return base;
+    const target = cdLiteralTarget(commandNode);
+    if (target === null) return UNKNOWN_BASE;
+    if (this.normalizer.isAbsolute(target))
+      return { kind: "known", offset: target };
+    if (base.kind === "unknown") return UNKNOWN_BASE;
+    return {
+      kind: "known",
+      offset: this.normalizer.joinBase(base.offset, target),
+    };
+  }
+
+  // ── Projection ─────────────────────────────────────────────────────────
+
+  /**
+   * Project the collected candidates into deduplicated external paths.
+   *
+   * Filters candidates through the strict path classifier
+   * (`classifyTokenAsPathCandidate`), resolves each against its effective working
+   * directory base, and returns only paths that resolve outside the baked cwd in
+   * their lexical (as-typed, normalized but not symlink-resolved) form.
+   *
+   * The outside-cwd decision and the dedup identity use the canonical
+   * (symlink-resolved) form so `external_directory` config patterns match the
+   * path as the user typed it (#418).
+   */
+  private projectExternalPaths(
+    candidates: readonly PathCandidate[],
+  ): AccessPath[] {
+    const seen = new Set<string>();
+    const externalPaths: AccessPath[] = [];
+
+    for (const { token, base } of candidates) {
+      const candidate = classifyTokenAsPathCandidate(token);
+      if (!candidate) continue;
+
+      // Unknown effective directory: a relative candidate could resolve
+      // anywhere, so flag it conservatively (resolved against the baked cwd
+      // only for a display path). Absolute / `~` candidates are base-independent
+      // below.
+      if (base.kind === "unknown" && this.isRelativeCandidate(candidate)) {
+        const accessPath = this.normalizer.forPath(candidate);
+        const canonical = accessPath.boundaryValue();
+        if (canonical && !isSafeSystemPath(canonical) && !seen.has(canonical)) {
+          seen.add(canonical);
+          externalPaths.push(accessPath);
+        }
+        continue;
+      }
+
+      const resolveBase =
+        base.kind === "known"
+          ? this.normalizer.resolveBase(base.offset)
+          : undefined;
+      const accessPath = this.normalizer.forPath(candidate, { resolveBase });
+      const lexical = accessPath.value();
+      if (!lexical) continue;
+      // The boundary decision and dedup identity use the canonical
+      // (symlink-resolved) form, but the returned value is the lexical form so
+      // config patterns match the path as the user typed it (#418).
+      const canonical = accessPath.boundaryValue();
+
+      if (
+        this.normalizer.isOutsideWorkingDirectory(lexical) &&
+        !seen.has(canonical)
+      ) {
+        seen.add(canonical);
+        externalPaths.push(accessPath);
+      }
+    }
+
+    return externalPaths;
+  }
+
+  /**
+   * Project the collected candidates into rule candidates with their cd-aware
+   * policy lookup values.
+   *
+   * Filters candidates through the broad path classifier
+   * (`classifyTokenAsRuleCandidate`) and pairs each qualifying token with its
+   * set of policy values (absolute + project-relative + raw).
+   * A token after a non-literal `cd` keeps only its literal value so no
+   * spurious absolute rule can match (#393).
+   */
+  private projectRuleCandidates(
+    candidates: readonly PathCandidate[],
+  ): BashPathRuleCandidate[] {
+    const seen = new Set<string>();
+    const result: BashPathRuleCandidate[] = [];
+
+    for (const { token, base } of candidates) {
+      const candidate = classifyTokenAsRuleCandidate(token);
+      if (!candidate) continue;
+
+      const path = this.buildRuleCandidatePath(candidate, base);
+      const matchValues = path.matchValues();
+      if (matchValues.length === 0) continue;
+
+      const key = matchValues.join("\0");
+      if (seen.has(key)) continue;
+      seen.add(key);
+      result.push({ token: candidate, path });
+    }
+
+    return result;
+  }
+
+  private buildRuleCandidatePath(
+    candidate: string,
+    base: EffectiveBase,
+  ): AccessPath {
+    // An unknown base + relative candidate stays literal-only: a resolved
+    // absolute or canonical alias would resolve against the wrong directory and
+    // could spuriously match a rule (#393).
+    if (base.kind === "unknown" && this.isRelativeCandidate(candidate)) {
+      return this.normalizer.forLiteral(normalizePathPolicyLiteral(candidate));
+    }
+
+    const resolveBase =
+      base.kind === "known"
+        ? this.normalizer.resolveBase(base.offset)
+        : undefined;
+    return this.normalizer.forPath(candidate, { resolveBase });
+  }
+
+  /**
+   * True when a path candidate is relative (resolved against the effective
+   * directory) rather than absolute or home-relative (`~…`), which are
+   * base-independent.
+   *
+   * Delegates the absoluteness decision to the platform-aware `PathNormalizer`
+   * rather than a POSIX-only `startsWith("/")` check, so Windows drive-letter
+   * paths (`C:/…`, `C:\…`) are correctly treated as absolute on win32 and as
+   * relative on POSIX (where they denote an in-CWD path).
+   */
+  private isRelativeCandidate(candidate: string): boolean {
+    return !this.normalizer.isAbsolute(candidate) && !candidate.startsWith("~");
+  }
+}
+
+// ── Pure AST/string helpers ──────────────────────────────────────────────────
+
+/**
+ * True when the statement at `index` is immediately followed by the background
+ * operator (`&`) — distinct from the `&&` / `||` / `;` current-shell
+ * separators.
+ */
+function isBackgrounded(seqNode: TSNode, index: number): boolean {
+  const next = seqNode.child(index + 1);
+  if (!next || next.isNamed) return false;
+  return next.type === "&";
+}
+
+function tagTokens(
+  tokens: readonly string[],
+  base: EffectiveBase,
+  out: PathCandidate[],
+): void {
+  for (const token of tokens) out.push({ token, base });
+}
+
+/**
+ * Resolve the literal target of a `cd` command, or `null` when the first
+ * argument is not a static literal (contains an expansion or command
+ * substitution) or cannot be resolved against the working directory (`cd -`,
+ * `cd ~…`, bare `cd`).
+ */
+function cdLiteralTarget(commandNode: TSNode): string | null {
+  for (let i = 0; i < commandNode.childCount; i++) {
+    const child = commandNode.child(i);
+    if (!child) continue;
+    if (child.type === "command_name" || child.type === "variable_assignment")
+      continue;
+    if (!child.isNamed) continue;
+    // Skip the `--` end-of-flags marker; the next argument is the target.
+    if (child.type === "word" && child.text === "--") continue;
+    if (!ARG_NODE_TYPES.has(child.type)) return null;
+    return literalTextOf(child);
+  }
+  return null;
+}
+
+/**
+ * The literal string value of an argument node, or `null` when it contains a
+ * variable expansion / command substitution or is a non-resolvable `cd`
+ * destination (`-`, `~…`).
+ */
+function literalTextOf(node: TSNode): string | null {
+  switch (node.type) {
+    case "word": {
+      const text = node.text;
+      if (text === "-" || text.startsWith("~")) return null;
+      return text;
+    }
+    case "raw_string": {
+      const text = node.text;
+      return text.length >= 2 && text.startsWith("'") && text.endsWith("'")
+        ? text.slice(1, -1)
+        : text;
+    }
+    case "concatenation": {
+      let result = "";
+      for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        if (!child) continue;
+        const part = literalTextOf(child);
+        if (part === null) return null;
+        result += part;
+      }
+      return result;
+    }
+    case "string": {
+      let result = "";
+      for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        if (!child) continue;
+        if (child.type === '"') continue;
+        if (child.type !== "string_content") return null;
+        result += child.text;
+      }
+      return result;
+    }
+    default:
+      return null;
+  }
+}

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

@@ -1,15 +1,14 @@
 import type { AccessPath } from "#src/access-intent/access-path";
+import {
+  BashPathResolver,
+  type BashPathRuleCandidate,
+} from "#src/access-intent/bash/bash-path-resolver";
 import {
   type BashCommand,
   collectCommands,
 } from "#src/access-intent/bash/command-enumeration";
-import {
-  type BashPathRuleCandidate,
-  collectPathCandidates,
-  projectExternalPaths,
-  projectRuleCandidates,
-} from "#src/access-intent/bash/cwd-projection";
 import { getParser } from "#src/access-intent/bash/parser";
+import type { PathNormalizer } from "#src/path-normalizer";
 
 export type { BashCommand, BashPathRuleCandidate };
 
@@ -35,20 +34,26 @@ export class BashProgram {
    *
    * Uses tree-sitter-bash to build the full AST, enumerates command units and
    * walks path-candidate tokens once, then eagerly resolves all three slices
-   * against `cwd`. Heredoc bodies, comments, and other non-argument content are
-   * skipped. An unparseable command yields an empty program.
+   * through the injected {@link PathNormalizer} (platform + cwd baked in).
+   * Heredoc bodies, comments, and other non-argument content are skipped. An
+   * unparseable command yields an empty program.
    */
-  static async parse(command: string, cwd: string): Promise<BashProgram> {
+  static async parse(
+    command: string,
+    normalizer: PathNormalizer,
+  ): Promise<BashProgram> {
     const parser = await getParser();
     const tree = parser.parse(command);
     if (!tree) return new BashProgram([], [], []);
 
     try {
-      const candidates = collectPathCandidates(tree.rootNode);
+      const { externalPaths, ruleCandidates } = new BashPathResolver(
+        normalizer,
+      ).resolve(tree.rootNode);
       return new BashProgram(
         collectCommands(tree.rootNode),
-        projectExternalPaths(candidates, cwd),
-        projectRuleCandidates(candidates, cwd),
+        externalPaths,
+        ruleCandidates,
       );
     } finally {
       tree.delete();
@@ -81,7 +86,8 @@ export class BashProgram {
    * objects holding both the lexical (as-typed) and canonical (symlink-resolved)
    * forms behind distinct accessors.
    *
-   * Resolved eagerly at parse time against the `cwd` supplied to `parse()`.
+   * Resolved eagerly at parse time through the `PathNormalizer` supplied to
+   * `parse()` (platform + cwd baked in).
    * Use `.matchValues()` for `external_directory` pattern matching and
    * `.boundaryValue()` for containment checks; `.value()` for display and logs.
    */
@@ -92,7 +98,8 @@ export class BashProgram {
   /**
    * Path-rule candidates paired with their policy lookup values.
    *
-   * Resolved eagerly at parse time against the `cwd` supplied to `parse()`.
+   * Resolved eagerly at parse time through the `PathNormalizer` supplied to
+   * `parse()` (platform + cwd baked in).
    * Each token is resolved against the effective working directory in force at
    * the token's position (folding literal current-shell `cd` commands), while
    * raw and project-relative aliases are retained for backward-compatible