@gotgenes/pi-permission-system 20.2.0 → 20.4.0

package/src/pattern-suggest.ts

@@ -62,6 +62,35 @@ export function suggestMcpPattern(target: string): string {
   return "*";
 }
 
+/** Scope labels for the forwarded-approval two-step scope select. */
+export interface ForwardedScopeLabels {
+  /** Least-privilege default: record on the requesting subagent only. */
+  subagentLabel: string;
+  /** Record on the serving node — covers the parent and all subagents. */
+  servingSessionLabel: string;
+}
+
+/**
+ * Build the two scope labels shown when a human grants a forwarded request
+ * "for this session."
+ *
+ * The subagent option names the requester (least privilege); the whole-session
+ * option restates the surface + pattern being granted session-wide.
+ */
+export function buildForwardedScopeLabels(
+  agentName: string | null,
+  surface: string,
+  pattern: string,
+): ForwardedScopeLabels {
+  const subagentLabel = agentName
+    ? `This subagent ('${agentName}') only`
+    : "This subagent only";
+  return {
+    subagentLabel,
+    servingSessionLabel: `The whole session — allow ${surface} "${pattern}" for parent and all subagents`,
+  };
+}
+
 /** Surface-aware human-readable labels for the session-approval option. */
 function buildLabel(pattern: string, surface: string): string {
   switch (surface) {

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,

package/src/rule.ts

@@ -1,6 +1,8 @@
+import type { PathFlavor } from "#src/path/path-flavor";
+
 import { PATH_SURFACES } from "./path-surfaces";
 import type { PermissionState } from "./types";
-import { wildcardMatch } from "./wildcard-matcher";
+import { type WildcardMatchOptions, wildcardMatch } from "./wildcard-matcher";
 
 /**
  * Provenance of a rule — which source contributed it.
@@ -74,12 +76,10 @@ export function evaluate(
   surface: string,
   pattern: string,
   rules: Ruleset,
-  platform: NodeJS.Platform,
+  flavor: PathFlavor,
   defaultAction?: PermissionState,
 ): Rule {
-  const rule = rules.findLast((r) =>
-    ruleMatches(r, surface, pattern, platform),
-  );
+  const rule = rules.findLast((r) => ruleMatches(r, surface, pattern, flavor));
   if (rule !== undefined) return rule;
   return {
     surface,
@@ -96,20 +96,18 @@ export function evaluate(
  */
 export function pathMatchOptions(
   surface: string,
-  platform: NodeJS.Platform,
-): { caseInsensitive: true; windowsSeparators: true } | undefined {
-  return platform === "win32" && PATH_SURFACES.has(surface)
-    ? { caseInsensitive: true, windowsSeparators: true }
-    : undefined;
+  flavor: PathFlavor,
+): WildcardMatchOptions | undefined {
+  return PATH_SURFACES.has(surface) ? flavor.matchOptions : undefined;
 }
 
 function ruleMatches(
   rule: Rule,
   surface: string,
   value: string,
-  platform: NodeJS.Platform,
+  flavor: PathFlavor,
 ): boolean {
-  const matchOptions = pathMatchOptions(surface, platform);
+  const matchOptions = pathMatchOptions(surface, flavor);
   return (
     wildcardMatch(rule.surface, surface) &&
     wildcardMatch(rule.pattern, value, matchOptions)
@@ -144,11 +142,11 @@ export function evaluateMostRestrictive(
   surface: string,
   values: string[],
   rules: Ruleset,
-  platform: NodeJS.Platform,
+  flavor: PathFlavor,
 ): { rule: Rule; value: string } | null {
   let worst: { rule: Rule; value: string } | null = null;
   for (const value of values) {
-    const rule = evaluate(surface, value, rules, platform);
+    const rule = evaluate(surface, value, rules, flavor);
     if (rule.action === "deny") return { rule, value };
     if (rule.action === "ask" && worst?.rule.action !== "ask") {
       worst = { rule, value };
@@ -161,10 +159,10 @@ export function evaluateFirst(
   surface: string,
   values: string[],
   rules: Ruleset,
-  platform: NodeJS.Platform,
+  flavor: PathFlavor,
 ): { rule: Rule; value: string } {
   for (const value of values) {
-    const rule = evaluate(surface, value, rules, platform);
+    const rule = evaluate(surface, value, rules, flavor);
     if (rule.layer !== "default") {
       return { rule, value };
     }
@@ -172,7 +170,7 @@ export function evaluateFirst(
   // All candidates matched only the synthesized default — use the first.
   const fallbackValue = values[0] ?? "*";
   return {
-    rule: evaluate(surface, fallbackValue, rules, platform),
+    rule: evaluate(surface, fallbackValue, rules, flavor),
     value: fallbackValue,
   };
 }
@@ -189,22 +187,22 @@ export function evaluateAnyValue(
   surface: string,
   values: string[],
   rules: Ruleset,
-  platform: NodeJS.Platform,
+  flavor: PathFlavor,
 ): { rule: Rule; value: string } {
   const fallbackValue = values[0] ?? "*";
   const rule = rules.findLast((r) =>
-    values.some((value) => ruleMatches(r, surface, value, platform)),
+    values.some((value) => ruleMatches(r, surface, value, flavor)),
   );
   if (rule !== undefined) {
     return {
       rule,
       value:
-        values.find((value) => ruleMatches(rule, surface, value, platform)) ??
+        values.find((value) => ruleMatches(rule, surface, value, flavor)) ??
         fallbackValue,
     };
   }
   return {
-    rule: evaluate(surface, fallbackValue, rules, platform),
+    rule: evaluate(surface, fallbackValue, rules, flavor),
     value: fallbackValue,
   };
 }

package/src/session-approval.ts

@@ -1,3 +1,5 @@
+import type { ForwardedSessionApproval } from "#src/authority/permission-forwarding";
+
 /**
  * Value object for a session-scoped approval: one surface, one-or-more patterns.
  *
@@ -40,4 +42,13 @@ export class SessionApproval {
     if (pattern === undefined) return undefined;
     return { surface: this.surface, pattern };
   }
+
+  /**
+   * Plain data shape for relaying this approval on a forwarded request, so the
+   * serving node can record the same pattern(s) as a whole-session grant.
+   * Returns a defensive copy of the patterns.
+   */
+  toForwardedData(): ForwardedSessionApproval {
+    return { surface: this.surface, patterns: [...this.patterns] };
+  }
 }

package/src/tool-input-path.ts

@@ -1,4 +1,4 @@
-import { PATH_BEARING_TOOLS } from "./path-surfaces";
+import { classifyToolKind } from "./access-intent/tool-kind";
 import type { ToolAccessExtractorLookup } from "./tool-access-extractor-registry";
 import { getNonEmptyString, toRecord } from "./value-guards";
 
@@ -6,7 +6,7 @@ export function getPathBearingToolPath(
   toolName: string,
   input: unknown,
 ): string | null {
-  if (!PATH_BEARING_TOOLS.has(toolName)) {
+  if (classifyToolKind(toolName) !== "path") {
     return null;
   }
 
@@ -31,24 +31,22 @@ export function getToolInputPath(
   input: unknown,
   extractors?: ToolAccessExtractorLookup,
 ): string | null {
-  if (toolName === "bash") {
-    return null;
-  }
-
   const record = toRecord(input);
 
-  if (PATH_BEARING_TOOLS.has(toolName)) {
-    return getNonEmptyString(record.path);
-  }
-
-  if (toolName === "mcp") {
-    return getNonEmptyString(toRecord(record.arguments).path);
-  }
-
-  const custom = extractors?.get(toolName);
-  if (custom) {
-    return getNonEmptyString(custom(record));
+  switch (classifyToolKind(toolName)) {
+    case "bash":
+      return null;
+    case "path":
+      return getNonEmptyString(record.path);
+    case "mcp":
+      return getNonEmptyString(toRecord(record.arguments).path);
+    case "skill":
+    case "extension": {
+      const custom = extractors?.get(toolName);
+      if (custom) {
+        return getNonEmptyString(custom(record));
+      }
+      return getNonEmptyString(record.path);
+    }
   }
-
-  return getNonEmptyString(record.path);
 }

package/src/tool-preview-formatter.ts

@@ -1,3 +1,4 @@
+import { classifyToolKind, isMcpCheck } from "./access-intent/tool-kind";
 import type { PermissionSystemExtensionConfig } from "./extension-config";
 import type { ToolInputFormatterLookup } from "./tool-input-formatter-registry";
 import {
@@ -158,11 +159,7 @@ export class ToolPreviewFormatter {
     input: unknown,
     pathBearingTools: ReadonlySet<string>,
   ): string | undefined {
-    if (
-      result.toolName === "bash" ||
-      result.toolName === "mcp" ||
-      result.source === "mcp"
-    ) {
+    if (classifyToolKind(result.toolName) === "bash" || isMcpCheck(result)) {
       return undefined;
     }
 

package/src/path-containment.ts

@@ -1,56 +0,0 @@
-import { posix as posixPath, win32 as winPath } from "node:path";
-
-import { isSafeSystemPath } from "./safe-system-paths";
-
-/**
- * Returns true when `pathValue` is `directory` itself or nested inside it.
- *
- * Containment is decided with Node's platform-native `path.relative` rather
- * than a hand-rolled prefix check: on `win32` the comparison folds case (and
- * tolerates either separator), matching the case-insensitive filesystem.
- * `platform` is injected from the composition root so Windows behavior is
- * testable on a POSIX CI.
- */
-export function isPathWithinDirectory(
-  pathValue: string,
-  directory: string,
-  platform: NodeJS.Platform,
-): boolean {
-  if (!pathValue || !directory) {
-    return false;
-  }
-
-  if (pathValue === directory) {
-    return true;
-  }
-
-  const impl = platform === "win32" ? winPath : posixPath;
-  const rel = impl.relative(directory, pathValue);
-  return (
-    rel !== "" &&
-    rel !== ".." &&
-    !rel.startsWith(`..${impl.sep}`) &&
-    !impl.isAbsolute(rel)
-  );
-}
-
-/**
- * Pure geometry: is `canonicalPath` outside `canonicalCwd`?
- *
- * Both operands must already be canonical (symlink-resolved, win32-lowercased)
- * — the caller prepares them (see {@link PathNormalizer.isOutsideWorkingDirectory}).
- * This predicate touches no filesystem and does no derivation.
- */
-export function isPathOutsideWorkingDirectory(
-  canonicalPath: string,
-  canonicalCwd: string,
-  platform: NodeJS.Platform,
-): boolean {
-  if (!canonicalCwd || !canonicalPath) {
-    return false;
-  }
-  if (isSafeSystemPath(canonicalPath)) {
-    return false;
-  }
-  return !isPathWithinDirectory(canonicalPath, canonicalCwd, platform);
-}