@gotgenes/pi-permission-system 20.3.0 → 20.4.0

package/src/path/path-flavor.ts

@@ -0,0 +1,114 @@
+import type { PlatformPath } from "node:path";
+import { posix as posixPath, win32 as winPath } from "node:path";
+
+import {
+  type BashTokenShape,
+  classifyWin32BashToken,
+} from "#src/access-intent/bash/msys-bash-tokens";
+import type { WildcardMatchOptions } from "#src/wildcard-matcher";
+
+/**
+ * The resolved product of the single win32-vs-POSIX platform decision: the
+ * platform's path *language* as one immutable collaborator.
+ *
+ * The win32-vs-POSIX difference is not variant growth (the set is closed) but
+ * **connascence of algorithm** — every path leaf must re-derive the same
+ * mapping identically, and in a permission system a leaf that misses the case
+ * fold or separator fold is a silent bypass (the #382 / #508 class). `PathFlavor`
+ * captures that mapping once so the leaves consume the resolved capability
+ * instead of re-interpreting a raw `NodeJS.Platform` string. It owns platform
+ * **semantics** — syntax ({@link hasPathSeparator}), token shape
+ * ({@link bashTokenShape}), and the equivalence relation ({@link fold} /
+ * {@link comparable} / {@link isWithin} / {@link matchOptions}); domain policy
+ * (lexical cleanup, alias generation, safe-system-path exclusions, rule
+ * dispatch) stays in the functions that consume it.
+ */
+export interface PathFlavor {
+  /**
+   * Node's own platform path strategy (`path.win32` | `path.posix`). Exposed
+   * directly — its post-migration consumers are all path-domain primitives and
+   * `PlatformPath` is itself a maintained strategy object, so wrapping it would
+   * be pure forwarding.
+   */
+  readonly impl: PlatformPath;
+  /**
+   * Wildcard match options for path-surface rule matching: the win32
+   * case-and-separator fold, or `undefined` on POSIX.
+   */
+  readonly matchOptions: WildcardMatchOptions | undefined;
+  /** Comparison case fold: win32 lowercases, POSIX returns the value unchanged. */
+  fold(value: string): string;
+  /**
+   * Resolve `pathValue` against `base`, normalize, and fold — the single home
+   * of the #382 case-fold invariant for absolute comparison values.
+   */
+  comparable(pathValue: string, base: string): string;
+  /** `path.relative`-based containment: is `pathValue` `directory` itself or nested inside it? */
+  isWithin(pathValue: string, directory: string): boolean;
+  /**
+   * True when `token` contains a path separator under this platform: `/` on
+   * POSIX; `/` or `\` on win32 (where a backslash is a separator, #520).
+   */
+  hasPathSeparator(token: string): boolean;
+  /**
+   * The MSYS/Git-Bash interpretation of a bash-command token. On win32 this
+   * carries device / drive-mount / posix-absolute / plain semantics; on POSIX
+   * every token is an ordinary path, so the shape is always `{ kind: "plain" }`.
+   */
+  bashTokenShape(token: string): BashTokenShape;
+}
+
+class PlatformPathFlavor implements PathFlavor {
+  readonly matchOptions: WildcardMatchOptions | undefined;
+
+  constructor(
+    readonly impl: PlatformPath,
+    private readonly windows: boolean,
+  ) {
+    this.matchOptions = windows
+      ? { caseInsensitive: true, windowsSeparators: true }
+      : undefined;
+  }
+
+  fold(value: string): string {
+    return this.windows ? value.toLowerCase() : value;
+  }
+
+  comparable(pathValue: string, base: string): string {
+    return this.fold(this.impl.normalize(this.impl.resolve(base, pathValue)));
+  }
+
+  isWithin(pathValue: string, directory: string): boolean {
+    if (!pathValue || !directory) return false;
+    if (pathValue === directory) return true;
+    const rel = this.impl.relative(directory, pathValue);
+    return (
+      rel !== "" &&
+      rel !== ".." &&
+      !rel.startsWith(`..${this.impl.sep}`) &&
+      !this.impl.isAbsolute(rel)
+    );
+  }
+
+  hasPathSeparator(token: string): boolean {
+    return token.includes("/") || (this.windows && token.includes("\\"));
+  }
+
+  bashTokenShape(token: string): BashTokenShape {
+    return this.windows ? classifyWin32BashToken(token) : { kind: "plain" };
+  }
+}
+
+export const posixPathFlavor: PathFlavor = new PlatformPathFlavor(
+  posixPath,
+  false,
+);
+export const win32PathFlavor: PathFlavor = new PlatformPathFlavor(
+  winPath,
+  true,
+);
+
+/** The one win32-vs-POSIX platform decision in the package. */
+export function pathFlavorForPlatform(platform: NodeJS.Platform): PathFlavor {
+  return platform === "win32" ? win32PathFlavor : posixPathFlavor;
+}

package/src/{pi-infrastructure-read.ts → path/pi-infrastructure-read.ts}

@@ -1,9 +1,9 @@
 import { join } from "node:path";
 
-import { expandHomePath } from "./expand-home";
-import { isPathWithinDirectory } from "./path-containment";
-import { READ_ONLY_PATH_BEARING_TOOLS } from "./path-surfaces";
-import { wildcardMatch } from "./wildcard-matcher";
+import { expandHomePath } from "#src/expand-home";
+import type { PathFlavor } from "#src/path/path-flavor";
+import { READ_ONLY_PATH_BEARING_TOOLS } from "#src/path-surfaces";
+import { wildcardMatch } from "#src/wildcard-matcher";
 
 function containsGlobChars(value: string): boolean {
   return value.includes("*") || value.includes("?");
@@ -29,35 +29,30 @@ export function isPiInfrastructureRead(
   normalizedPath: string,
   infrastructureDirs: readonly string[],
   cwd: string,
-  platform: NodeJS.Platform,
+  flavor: PathFlavor,
 ): boolean {
   if (!READ_ONLY_PATH_BEARING_TOOLS.has(toolName)) {
     return false;
   }
 
-  // On Windows the path value is canonicalized + lowercased; fold case (and
-  // separators) so mixed-case infra dirs and glob patterns still match.
-  const matchOptions =
-    platform === "win32"
-      ? { caseInsensitive: true, windowsSeparators: true }
-      : undefined;
-
+  // On Windows the path value is canonicalized + lowercased; the flavor's match
+  // options fold case (and separators) so mixed-case infra dirs and glob
+  // patterns still match.
   for (const dir of infrastructureDirs) {
     if (containsGlobChars(dir)) {
-      if (wildcardMatch(dir, normalizedPath, matchOptions)) return true;
+      if (wildcardMatch(dir, normalizedPath, flavor.matchOptions)) return true;
     } else {
-      if (isPathWithinDirectory(normalizedPath, expandHomePath(dir), platform))
-        return true;
+      if (flavor.isWithin(normalizedPath, expandHomePath(dir))) return true;
     }
   }
 
   // Project-local Pi packages — checked fresh every call so CWD changes work.
   const projectNpmDir = join(cwd, ".pi", "npm");
   const projectGitDir = join(cwd, ".pi", "git");
-  if (isPathWithinDirectory(normalizedPath, projectNpmDir, platform)) {
+  if (flavor.isWithin(normalizedPath, projectNpmDir)) {
     return true;
   }
-  if (isPathWithinDirectory(normalizedPath, projectGitDir, platform)) {
+  if (flavor.isWithin(normalizedPath, projectGitDir)) {
     return true;
   }
 

package/src/path-normalizer.ts

@@ -1,17 +1,13 @@
-import { posix as posixPath, win32 as winPath } from "node:path";
+import type { PathFlavor } from "#src/path/path-flavor";
 
 import { AccessPath } from "./access-intent/access-path";
-import { classifyWin32BashToken } from "./access-intent/bash/msys-bash-tokens";
 import {
   canonicalNormalizePathForComparison,
   normalizePathForComparison,
   normalizePathPolicyLiteral,
 } from "./access-intent/path-normalization";
-import {
-  isPathOutsideWorkingDirectory,
-  isPathWithinDirectory,
-} from "./path-containment";
-import { isPiInfrastructureRead } from "./pi-infrastructure-read";
+import { isPathOutsideWorkingDirectory } from "./path/path-containment";
+import { isPiInfrastructureRead } from "./path/pi-infrastructure-read";
 
 /**
  * The interpreted effect of a literal `cd` target on the effective base, under
@@ -31,28 +27,27 @@ export type BashCdTarget =
 
 /**
  * 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 two ambient inputs — the resolved {@link PathFlavor} 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
+ * flavor*?", "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. All platform semantics live on the
+ * injected `flavor`; this class holds no platform discriminator and no
+ * `win32`/`posix` branch — it delegates to `flavor` and the flavor-parameterized
  * `path-containment` / `path-normalization` / `AccessPath` primitives.
  */
 export class PathNormalizer {
-  private readonly impl: typeof posixPath;
   /** Canonical form of the baked cwd, resolved once (the symlink target is stable per session). */
   private readonly canonicalCwd: string;
 
   constructor(
-    private readonly platform: NodeJS.Platform,
+    readonly flavor: PathFlavor,
     private readonly cwd: string,
   ) {
-    this.impl = platform === "win32" ? winPath : posixPath;
-    this.canonicalCwd = canonicalNormalizePathForComparison(cwd, cwd, platform);
+    this.canonicalCwd = canonicalNormalizePathForComparison(cwd, cwd, flavor);
   }
 
   /** Build an AccessPath for a token, resolved against `resolveBase` (default cwd). */
@@ -60,7 +55,7 @@ export class PathNormalizer {
     return AccessPath.forPath(pathValue, {
       cwd: this.cwd,
       resolveBase: options?.resolveBase,
-      platform: this.platform,
+      flavor: this.flavor,
     });
   }
 
@@ -74,18 +69,16 @@ export class PathNormalizer {
    * semantics on a win32 host.
    *
    * Pi core always executes bash through Git Bash on Windows, so a POSIX-shaped
-   * absolute token carries MSYS semantics, not `node:path.win32` semantics. On
-   * win32 the recognized safe device paths (`/dev/null`, `/dev/std{in,out,err}`)
-   * are preserved verbatim as devices instead of being resolved into
-   * `c:\dev\null`, and MSYS drive mounts (`/c/…`) are translated to their
-   * Windows equivalent (`C:\…`) before resolution; every other token delegates
-   * to {@link forPath}. On POSIX this is a straight delegation to
-   * {@link forPath}.
+   * absolute token carries MSYS semantics, not `node:path.win32` semantics. The
+   * flavor classifies the token's shape: on win32 the recognized safe device
+   * paths (`/dev/null`, `/dev/std{in,out,err}`) are preserved verbatim as
+   * devices instead of being resolved into `c:\dev\null`, and MSYS drive mounts
+   * (`/c/…`) are translated to their Windows equivalent (`C:\…`) before
+   * resolution; every other token delegates to {@link forPath}. On POSIX every
+   * token is `plain`, so this is a straight delegation to {@link forPath}.
    */
   forBashToken(token: string, options?: { resolveBase?: string }): AccessPath {
-    if (this.platform !== "win32") return this.forPath(token, options);
-
-    const shape = classifyWin32BashToken(token);
+    const shape = this.flavor.bashTokenShape(token);
     switch (shape.kind) {
       case "device":
         return AccessPath.forDevice(token);
@@ -109,19 +102,7 @@ export class PathNormalizer {
 
   /** Platform-aware absoluteness (`win32` vs `posix` rules). */
   isAbsolute(pathValue: string): boolean {
-    return this.impl.isAbsolute(pathValue);
-  }
-
-  /**
-   * True when the host platform treats a backslash as a path separator (win32).
-   *
-   * The bash rule-candidate classifier reads this to decide whether a
-   * backslash-relative token (`dir\file`) is path-shaped: on win32 `\` is a
-   * separator, but on POSIX it is a legal filename character (#520). Keeping the
-   * decision here means no bash-layer module re-reads `process.platform`.
-   */
-  usesWindowsSeparators(): boolean {
-    return this.platform === "win32";
+    return this.flavor.impl.isAbsolute(pathValue);
   }
 
   /**
@@ -131,16 +112,11 @@ export class PathNormalizer {
    * (`cd /c/x`) resolves to a translated Windows base (`C:\x`), a non-mount
    * POSIX absolute (`cd /tmp`) is not deterministically resolvable and yields an
    * `unknown` base, and a native/relative target is handled as usual. On POSIX
-   * an absolute target is absolute and everything else is relative.
+   * every token is `plain`, so an absolute target is absolute and everything
+   * else is relative.
    */
   interpretBashCdTarget(target: string): BashCdTarget {
-    if (this.platform !== "win32") {
-      return this.impl.isAbsolute(target)
-        ? { kind: "absolute", value: target }
-        : { kind: "relative" };
-    }
-
-    const shape = classifyWin32BashToken(target);
+    const shape = this.flavor.bashTokenShape(target);
     switch (shape.kind) {
       case "drive-mount":
         return { kind: "absolute", value: shape.windowsPath };
@@ -148,7 +124,7 @@ export class PathNormalizer {
       case "posix-absolute":
         return { kind: "unknown" };
       case "plain":
-        return this.impl.isAbsolute(target)
+        return this.flavor.impl.isAbsolute(target)
           ? { kind: "absolute", value: target }
           : { kind: "relative" };
     }
@@ -156,17 +132,17 @@ export class PathNormalizer {
 
   /** Resolve a `cd`-folded offset against the baked cwd (platform-aware). */
   resolveBase(offset: string): string {
-    return this.impl.resolve(this.cwd, offset);
+    return this.flavor.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);
+    return this.flavor.impl.join(offset, target);
   }
 
   /** Containment of `pathValue` within `directory` (platform-aware). */
   isWithinDirectory(pathValue: string, directory: string): boolean {
-    return isPathWithinDirectory(pathValue, directory, this.platform);
+    return this.flavor.isWithin(pathValue, directory);
   }
 
   /** Canonical (symlink-resolved) outside-cwd test against the baked cwd. */
@@ -174,12 +150,12 @@ export class PathNormalizer {
     const canonicalPath = canonicalNormalizePathForComparison(
       pathValue,
       this.cwd,
-      this.platform,
+      this.flavor,
     );
     return isPathOutsideWorkingDirectory(
       canonicalPath,
       this.canonicalCwd,
-      this.platform,
+      this.flavor,
     );
   }
 
@@ -196,7 +172,7 @@ export class PathNormalizer {
     return isPathOutsideWorkingDirectory(
       canonicalPath,
       this.canonicalCwd,
-      this.platform,
+      this.flavor,
     );
   }
 
@@ -206,12 +182,12 @@ export class PathNormalizer {
    * touches no filesystem, unlike {@link forPath}'s canonical alias.
    */
   comparableValue(pathValue: string): string {
-    return normalizePathForComparison(pathValue, this.cwd, this.platform);
+    return normalizePathForComparison(pathValue, this.cwd, this.flavor);
   }
 
   /**
    * Pi infrastructure-read containment for a read-only tool, decided against
-   * the canonical (symlink-resolved) path and the baked cwd/platform. Takes the
+   * the canonical (symlink-resolved) path and the baked cwd/flavor. Takes the
    * already-built {@link AccessPath} so the caller does not re-resolve it.
    */
   isInfrastructureRead(
@@ -224,7 +200,7 @@ export class PathNormalizer {
       accessPath.boundaryValue(),
       infraDirs,
       this.cwd,
-      this.platform,
+      this.flavor,
     );
   }
 }

package/src/permission-gate.ts

@@ -1,4 +1,4 @@
-import type { PermissionPromptDecision } from "./permission-dialog";
+import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 
 /** Result of applying the permission gate. */
 export type PermissionGateResult =

package/src/permission-manager.ts

@@ -1,5 +1,6 @@
 import { join } from "node:path";
 import type { ResolvedAccessIntent } from "./access-intent/access-intent";
+import { classifyToolKind } from "./access-intent/tool-kind";
 import {
   getGlobalConfigPath,
   getProjectAgentsDir,
@@ -7,6 +8,7 @@ import {
 } from "./config-paths";
 import { normalizeInput } from "./input-normalizer";
 import { normalizeFlatConfig } from "./normalize";
+import { type PathFlavor, posixPathFlavor } from "./path/path-flavor";
 import { PATH_SURFACES } from "./path-surfaces";
 import {
   FilePolicyLoader,
@@ -37,15 +39,6 @@ import type {
 import { isPermissionState } from "./types";
 import { wildcardMatch } from "./wildcard-matcher";
 
-const BUILT_IN_TOOL_PERMISSION_NAMES = new Set([
-  "bash",
-  "read",
-  "write",
-  "edit",
-  "grep",
-  "find",
-  "ls",
-]);
 const SPECIAL_PERMISSION_KEYS = new Set(["external_directory", "path"]);
 
 /** Universal fallback when permission["*"] is absent from all scopes. */
@@ -109,11 +102,12 @@ export interface PermissionManagerOptions extends PolicyLoaderOptions {
    */
   agentDir?: string;
   /**
-   * Host platform, injected from the composition root, that decides whether
-   * path-surface rule matching folds case (and separators) on Windows.
-   * Defaults to a POSIX flavor; production always supplies the real platform.
+   * Resolved path-language flavor, injected from the composition root, that
+   * decides whether path-surface rule matching folds case (and separators) on
+   * Windows. Defaults to the POSIX flavor; production always supplies the real
+   * platform's flavor.
    */
-  platform?: NodeJS.Platform;
+  flavor?: PathFlavor;
   /**
    * yolo-mode reader, injected from the composition root. When it reports
    * true, {@link PermissionManager.check} rewrites every matched `ask` to a
@@ -126,7 +120,7 @@ export interface PermissionManagerOptions extends PolicyLoaderOptions {
 
 export class PermissionManager implements ScopedPermissionManager {
   private readonly agentDir: string | undefined;
-  private readonly platform: NodeJS.Platform;
+  private readonly flavor: PathFlavor;
   private readonly isYoloEnabled: () => boolean;
   private loader: PolicyLoader;
   private readonly resolvedPermissionsCache = new Map<
@@ -136,7 +130,7 @@ export class PermissionManager implements ScopedPermissionManager {
 
   constructor(options: PermissionManagerOptions = {}) {
     this.agentDir = options.agentDir;
-    this.platform = options.platform ?? "linux";
+    this.flavor = options.flavor ?? posixPathFlavor;
     this.isYoloEnabled = options.isYoloEnabled ?? YOLO_DISABLED;
     this.loader =
       options.policyLoader ??
@@ -270,7 +264,7 @@ export class PermissionManager implements ScopedPermissionManager {
       .map((r) => r.pattern);
     if (patterns.length === 0) return NO_PROMOTION;
 
-    const matchOptions = pathMatchOptions("path", this.platform);
+    const matchOptions = pathMatchOptions("path", this.flavor);
     return (token) =>
       patterns.some((pattern) => wildcardMatch(pattern, token, matchOptions));
   }
@@ -281,29 +275,10 @@ export class PermissionManager implements ScopedPermissionManager {
    */
   getToolPermission(toolName: string, agentName?: string): PermissionState {
     const { composedRules } = this.resolvePermissions(agentName);
-    const normalizedToolName = toolName.trim();
-
-    // Special surfaces (external_directory): evaluate directly by surface name.
-    if (SPECIAL_PERMISSION_KEYS.has(normalizedToolName)) {
-      return evaluate(normalizedToolName, "*", composedRules, this.platform)
-        .action;
-    }
-
-    // Bash, MCP, skill: evaluate with "*" value — the per-surface catch-all
-    // (or universal default) handles this correctly.
-    if (normalizedToolName === "bash") {
-      return evaluate("bash", "*", composedRules, this.platform).action;
-    }
-    if (normalizedToolName === "mcp") {
-      return evaluate("mcp", "*", composedRules, this.platform).action;
-    }
-    if (normalizedToolName === "skill") {
-      return evaluate("skill", "*", composedRules, this.platform).action;
-    }
-
-    // Tool-name surfaces (read, write, etc. and extension tools).
-    return evaluate(normalizedToolName, "*", composedRules, this.platform)
-      .action;
+    // Every surface (special, bash, mcp, skill, path-bearing, and extension
+    // tools) resolves its tool-level state identically: evaluate the surface
+    // name against the "*" catch-all value. There is no per-kind branch.
+    return evaluate(toolName.trim(), "*", composedRules, this.flavor).action;
   }
 
   /**
@@ -345,7 +320,7 @@ export class PermissionManager implements ScopedPermissionManager {
         intent.surface,
         intent.surface,
         fullRules,
-        this.platform,
+        this.flavor,
       );
     }
 
@@ -363,7 +338,7 @@ export class PermissionManager implements ScopedPermissionManager {
       toolName,
       intent.surface,
       fullRules,
-      this.platform,
+      this.flavor,
     );
   }
 }
@@ -382,16 +357,18 @@ function buildCheckResult(
   normalizedToolName: string,
   toolName: string,
   fullRules: Ruleset,
-  platform: NodeJS.Platform,
+  flavor: PathFlavor,
 ): PermissionCheckResult {
   const { rule, value } = PATH_SURFACES.has(surface)
-    ? evaluateAnyValue(surface, values, fullRules, platform)
-    : evaluateFirst(surface, values, fullRules, platform);
+    ? evaluateAnyValue(surface, values, fullRules, flavor)
+    : evaluateFirst(surface, values, fullRules, flavor);
 
   // For MCP, replace the normalizer's fallback target with the actual
   // matched candidate value so PermissionCheckResult.target is accurate.
   const extras =
-    surface === "mcp" ? { ...resultExtras, target: value } : resultExtras;
+    classifyToolKind(surface) === "mcp"
+      ? { ...resultExtras, target: value }
+      : resultExtras;
 
   return {
     toolName,
@@ -444,19 +421,22 @@ function deriveSource(
   toolName: string,
 ): PermissionCheckResult["source"] {
   if (rule.layer === "session") return "session";
-
-  if (toolName === "mcp") {
-    if (rule.layer === "default") return "default";
-    return "mcp";
-  }
-
   if (SPECIAL_PERMISSION_KEYS.has(toolName)) return "special";
-  if (toolName === "skill") return "skill";
-  if (toolName === "bash") return "bash";
 
-  // Built-in tools always report "tool"; extension tools distinguish default.
-  if (BUILT_IN_TOOL_PERMISSION_NAMES.has(toolName)) return "tool";
-  return rule.layer === "default" ? "default" : "tool";
+  switch (classifyToolKind(toolName)) {
+    case "mcp":
+      return rule.layer === "default" ? "default" : "mcp";
+    case "skill":
+      return "skill";
+    case "bash":
+      return "bash";
+    case "path":
+      // Built-in path-bearing tools (read/write/edit/grep/find/ls).
+      return "tool";
+    case "extension":
+      // Extension tools distinguish a synthesized-default match from a rule.
+      return rule.layer === "default" ? "default" : "tool";
+  }
 }
 
 // Re-export types that external modules import from this file.

package/src/permission-prompts.ts

@@ -1,3 +1,4 @@
+import { classifyToolKind, isMcpCheck } from "./access-intent/tool-kind";
 import { matchQualifier } from "./denial-messages";
 import type { SkillPromptEntry } from "./skill-prompt-sanitizer";
 import type { ToolPreviewFormatter } from "./tool-preview-formatter";
@@ -22,7 +23,7 @@ export function formatUnknownToolReason(
     preview.length > 0 ? `${preview.join(", ")}${suffix}` : "none";
 
   const mcpHint =
-    toolName === "mcp"
+    classifyToolKind(toolName) === "mcp"
       ? ""
       : ' If this was intended as an MCP server tool, call the registered \'mcp\' tool when available (for example: {"tool":"server:tool"}).';
 
@@ -37,7 +38,7 @@ export function formatAskPrompt(
 ): string {
   const subject = agentName ? `Agent '${agentName}'` : "Current agent";
 
-  if (result.toolName === "bash") {
+  if (classifyToolKind(result.toolName) === "bash") {
     const subCommand = result.command ?? "";
     const qualifier = matchQualifier(
       result.matchedPattern,
@@ -52,7 +53,7 @@ export function formatAskPrompt(
     return `${subject} requested bash command '${subCommand}'${qualifierInfo}${fullCommandInfo}. Allow this command?`;
   }
 
-  if ((result.source === "mcp" || result.toolName === "mcp") && result.target) {
+  if (isMcpCheck(result) && result.target) {
     const patternInfo = result.matchedPattern
       ? ` (matched '${result.matchedPattern}')`
       : "";

package/src/permission-session.ts

@@ -1,4 +1,5 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ForwardingController } from "#src/authority/forwarding-manager";
 import {
   getActiveAgentName,
   getActiveAgentNameFromSystemPrompt,
@@ -7,8 +8,8 @@ import type { AuthorizerSelectionLifecycle } from "./authority/authorizer-select
 import type { SessionConfigStore } from "./config-store";
 import type { PermissionSystemExtensionConfig } from "./extension-config";
 import type { ExtensionPaths } from "./extension-paths";
-import type { ForwardingController } from "./forwarding-manager";
 import type { ToolCallGateInputs } from "./handlers/gates/tool-call-gate-pipeline";
+import type { PathFlavor } from "./path/path-flavor";
 import { PathNormalizer } from "./path-normalizer";
 import type { ScopedPermissionManager } from "./permission-manager";
 
@@ -47,12 +48,12 @@ export class PermissionSession implements ToolCallGateInputs {
     private readonly sessionRules: SessionRules,
     private readonly configStore: SessionConfigStore,
     private readonly authorizerSelection: AuthorizerSelectionLifecycle,
-    private readonly platform: NodeJS.Platform,
+    private readonly flavor: PathFlavor,
   ) {
     // Placeholder until the first activate(ctx) binds the real cwd; every gate
     // evaluate runs after activate (handleToolCall activates first), so this
     // empty-cwd value is never read.
-    this.pathNormalizer = new PathNormalizer(platform, "");
+    this.pathNormalizer = new PathNormalizer(flavor, "");
   }
 
   // ── Context lifecycle ──────────────────────────────────────────────────
@@ -68,7 +69,7 @@ export class PermissionSession implements ToolCallGateInputs {
    */
   activate(ctx: ExtensionContext): void {
     this.context = ctx;
-    this.pathNormalizer = new PathNormalizer(this.platform, ctx.cwd);
+    this.pathNormalizer = new PathNormalizer(this.flavor, ctx.cwd);
     this.forwarding.start(ctx);
     this.authorizerSelection.activate(ctx);
   }
@@ -207,7 +208,7 @@ export class PermissionSession implements ToolCallGateInputs {
   // ── Path normalization ────────────────────────────────────────────────
 
   /**
-   * The session's {@link PathNormalizer}, carrying the host platform and the
+   * The session's {@link PathNormalizer}, carrying the host path flavor and the
    * session cwd. Rebuilt on every `resetForNewSession` so a session switch
    * rebinds the cwd.
    */

package/src/permissions-service.ts

@@ -1,4 +1,5 @@
 import type { AccessIntent } from "./access-intent/access-intent";
+import { resolveBashAdvisoryCheck } from "./bash-advisory-check";
 import { buildAccessIntentForSurface } from "./input-normalizer";
 import type { PathNormalizer } from "./path-normalizer";
 import type { PermissionsService } from "./service";
@@ -50,6 +51,13 @@ export class LocalPermissionsService implements PermissionsService {
     value?: string,
     agentName?: string,
   ): ReturnType<PermissionsService["checkPermission"]> {
+    // Bash decomposes at gate parity: a chained/nested command is split into
+    // its command-pattern units and resolved most-restrictive, matching what
+    // the enforcement gate enforces (#309). A cold parser falls back to the
+    // whole-string match inside resolveBashAdvisoryCheck.
+    if (surface === "bash") {
+      return resolveBashAdvisoryCheck(value ?? "", agentName, this.resolver);
+    }
     const intent = buildAccessIntentForSurface(
       surface,
       value,