@gotgenes/pi-permission-system 20.3.0 → 20.4.0

package/src/authority/subagent-context.ts

@@ -1,7 +1,6 @@
-import { posix as posixPath, win32 as winPath } from "node:path";
-
-import { SUBAGENT_ENV_HINT_KEYS } from "#src/permission-forwarding";
-import type { SubagentSessionRegistry } from "#src/subagent-registry";
+import { SUBAGENT_ENV_HINT_KEYS } from "#src/authority/permission-forwarding";
+import type { SubagentSessionRegistry } from "#src/authority/subagent-registry";
+import type { PathFlavor } from "#src/path/path-flavor";
 
 /**
  * Narrow context for subagent detection — the only session-manager readers
@@ -17,17 +16,15 @@ export interface SubagentDetectionContext {
 
 export function normalizeFilesystemPath(
   pathValue: string,
-  platform: NodeJS.Platform,
+  flavor: PathFlavor,
 ): string {
-  const impl = platform === "win32" ? winPath : posixPath;
-  const normalizedPath = impl.normalize(pathValue);
-  return platform === "win32" ? normalizedPath.toLowerCase() : normalizedPath;
+  return flavor.fold(flavor.impl.normalize(pathValue));
 }
 
 function isPathWithinDirectoryForSubagent(
   pathValue: string,
   directory: string,
-  platform: NodeJS.Platform,
+  flavor: PathFlavor,
 ): boolean {
   if (!pathValue || !directory) {
     return false;
@@ -37,7 +34,7 @@ function isPathWithinDirectoryForSubagent(
     return true;
   }
 
-  const sep = platform === "win32" ? "\\" : "/";
+  const sep = flavor.impl.sep;
   const prefix = directory.endsWith(sep) ? directory : `${directory}${sep}`;
   return pathValue.startsWith(prefix);
 }
@@ -71,7 +68,7 @@ export function isRegisteredSubagentChild(
 export function isSubagentExecutionContext(
   ctx: SubagentDetectionContext,
   subagentSessionsDir: string,
-  platform: NodeJS.Platform,
+  flavor: PathFlavor,
   registry?: SubagentSessionRegistry,
 ): boolean {
   // 1. Explicit registry — in-process subagent extensions register by child
@@ -99,14 +96,14 @@ export function isSubagentExecutionContext(
     return false;
   }
 
-  const normalizedSessionDir = normalizeFilesystemPath(sessionDir, platform);
+  const normalizedSessionDir = normalizeFilesystemPath(sessionDir, flavor);
   const normalizedSubagentRoot = normalizeFilesystemPath(
     subagentSessionsDir,
-    platform,
+    flavor,
   );
   return isPathWithinDirectoryForSubagent(
     normalizedSessionDir,
     normalizedSubagentRoot,
-    platform,
+    flavor,
   );
 }

package/src/authority/subagent-detection.ts

@@ -3,7 +3,8 @@ import {
   isSubagentExecutionContext,
   type SubagentDetectionContext,
 } from "#src/authority/subagent-context";
-import type { SubagentSessionRegistry } from "#src/subagent-registry";
+import type { SubagentSessionRegistry } from "#src/authority/subagent-registry";
+import type { PathFlavor } from "#src/path/path-flavor";
 
 /**
  * Narrow seam for the ask-path consumers: "is the current session a subagent?"
@@ -30,7 +31,7 @@ export interface RegisteredChildDetector {
 /** Composition-root inputs for {@link SubagentDetection}. */
 export interface SubagentDetectionDeps {
   subagentSessionsDir: string;
-  platform: NodeJS.Platform;
+  flavor: PathFlavor;
   registry?: SubagentSessionRegistry;
 }
 
@@ -38,7 +39,7 @@ export interface SubagentDetectionDeps {
  * Single owner of subagent detection.
  *
  * Constructed once in the composition root with the detection inputs
- * (`subagentSessionsDir`, `platform`, `registry`) and shared across every
+ * (`subagentSessionsDir`, `flavor`, `registry`) and shared across every
  * consumer, replacing the dep triple those consumers previously threaded
  * individually. Delegates to the pure detection functions in
  * {@link ./subagent-context}, holding only the deps.
@@ -52,7 +53,7 @@ export class SubagentDetection
     return isSubagentExecutionContext(
       ctx,
       this.deps.subagentSessionsDir,
-      this.deps.platform,
+      this.deps.flavor,
       this.deps.registry,
     );
   }

package/src/bash-advisory-check.ts

@@ -0,0 +1,38 @@
+import { parseBashCommandsSync } from "#src/access-intent/bash/sync-commands";
+import { resolveBashCommandCheck } from "#src/handlers/gates/bash-command";
+import type { ScopedPermissionResolver } from "#src/permission-resolver";
+import type { PermissionCheckResult } from "#src/types";
+
+/**
+ * Resolve an advisory bash query at the gate's decomposed fidelity.
+ *
+ * When the tree-sitter parser is warm, the command is decomposed into its
+ * command-pattern units and routed through the same shared orchestrator the
+ * enforcement gate uses (`resolveBashCommandCheck`) — so a chained/nested
+ * command returns the most-restrictive decision (`deny > ask > allow`) and
+ * inherits the opaque-wrapper floor (#481) and the fail-closed
+ * `<unparseable-bash-command>` sentinel (#452), at parity with the gate.
+ *
+ * In the pre-warm window (`parseBashCommandsSync` returns `null`) it falls back
+ * to the pre-#309 whole-string match, so the advisory answer is never *weaker*
+ * than before — only strengthened once warm.
+ *
+ * Synchronous, preserving `PermissionsService.checkPermission`'s sync contract:
+ * the only async step (parser init) happens earlier, at `before_agent_start`.
+ */
+export function resolveBashAdvisoryCheck(
+  command: string,
+  agentName: string | undefined,
+  resolver: ScopedPermissionResolver,
+): PermissionCheckResult {
+  const commands = parseBashCommandsSync(command);
+  if (commands === null) {
+    return resolver.resolve({
+      kind: "tool",
+      surface: "bash",
+      input: { command },
+      agentName,
+    });
+  }
+  return resolveBashCommandCheck(command, commands, agentName, resolver);
+}

package/src/denial-messages.ts

@@ -1,3 +1,4 @@
+import { classifyToolKind, isMcpCheck } from "./access-intent/tool-kind";
 import { EXTENSION_ID } from "./extension-config";
 import type { BashCommandContext, PermissionCheckResult } from "./types";
 
@@ -127,7 +128,7 @@ function buildToolDenyBody(
     parts.push(`Agent '${agentName}'`);
   }
 
-  if (isMcpCheck(check)) {
+  if (isMcpCheck(check) && check.target) {
     parts.push(`is not permitted to run MCP target '${check.target}'`);
   } else {
     parts.push(`is not permitted to run '${check.toolName}'`);
@@ -190,10 +191,10 @@ function buildUnavailableBody(ctx: DenialContext): string {
   switch (ctx.kind) {
     case "tool": {
       const { check } = ctx;
-      if (check.toolName === "bash" && check.command) {
+      if (classifyToolKind(check.toolName) === "bash" && check.command) {
         return `Running bash command '${check.command}' requires approval, but no interactive UI is available.`;
       }
-      if (isMcpCheck(check)) {
+      if (isMcpCheck(check) && check.target) {
         return "Using tool 'mcp' requires approval, but no interactive UI is available.";
       }
       return `Using tool '${check.toolName}' requires approval, but no interactive UI is available.`;
@@ -220,10 +221,10 @@ function buildUserDeniedBody(
   switch (ctx.kind) {
     case "tool": {
       const { check } = ctx;
-      if (isMcpCheck(check)) {
+      if (isMcpCheck(check) && check.target) {
         return `User denied MCP target '${check.target}'.${reasonSuffix(denialReason)}`;
       }
-      if (check.toolName === "bash" && check.command) {
+      if (classifyToolKind(check.toolName) === "bash" && check.command) {
         return `User denied bash command '${check.command}'.${reasonSuffix(denialReason)}`;
       }
       return `User denied tool '${check.toolName}'.${reasonSuffix(denialReason)}`;
@@ -243,10 +244,6 @@ function buildUserDeniedBody(
   }
 }
 
-function isMcpCheck(check: PermissionCheckResult): boolean {
-  return (check.source === "mcp" || check.toolName === "mcp") && !!check.target;
-}
-
 /** Render an external-path disclosure list for the bash deny body's path clause. */
 function formatExternalPathList(paths: ExternalPathDisclosure[]): string {
   return paths

package/src/handlers/before-agent-start.ts

@@ -40,12 +40,16 @@ export function shouldExposeTool(
  * - `session` — encapsulates all mutable session state and lifecycle operations
  * - `resolver` — owns permission-query surface: `getToolPermission`, skill check
  * - `toolRegistry` — Pi tool API subset (getActive + setActive)
+ * - `warmParser` — warms the tree-sitter parser so the synchronous advisory
+ *   bash path can decompose at gate parity; `before_agent_start` precedes any
+ *   tool call, so triggering it here closes the pre-warm window (#309)
  */
 export class AgentPrepHandler {
   constructor(
     private readonly session: PermissionSession,
     private readonly resolver: PermissionResolver,
     private readonly toolRegistry: ToolRegistry,
+    private readonly warmParser: () => void,
   ) {}
 
   // eslint-disable-next-line @typescript-eslint/require-await
@@ -53,6 +57,10 @@ export class AgentPrepHandler {
     event: BeforeAgentStartPayload,
     ctx: ExtensionContext,
   ): Promise<BeforeAgentStartEventResult> {
+    // Fire-and-forget: warming is idempotent and best-effort, so it never
+    // delays agent start. A bash advisory query before it completes falls back
+    // to whole-string matching.
+    this.warmParser();
     this.session.activate(ctx);
     this.session.refreshConfig(ctx);
 

package/src/handlers/gates/helpers.ts

@@ -1,3 +1,4 @@
+import { classifyToolKind } from "#src/access-intent/tool-kind";
 import type {
   PermissionDecisionEvent,
   PermissionDecisionResolution,
@@ -14,10 +15,17 @@ export function deriveDecisionValue(
   check: Pick<PermissionCheckResult, "command" | "target">,
   path?: string,
 ): string {
-  if (toolName === "bash") return check.command ?? toolName;
-  if (toolName === "mcp") return check.target ?? toolName;
-  if (path) return path;
-  return toolName;
+  switch (classifyToolKind(toolName)) {
+    case "bash":
+      return check.command ?? toolName;
+    case "mcp":
+      return check.target ?? toolName;
+    case "path":
+    case "skill":
+    case "extension":
+      // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- || intentional: an empty path falls through to toolName (the original `if (path)` truthiness)
+      return path || toolName;
+  }
 }
 
 /**

package/src/handlers/gates/runner.ts

@@ -1,11 +1,11 @@
 import type { AskEscalator } from "#src/authority/authorizer-selection";
+import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 import type { DecisionReporter } from "#src/decision-reporter";
 import {
   formatDenyReason,
   formatUnavailableReason,
   formatUserDeniedReason,
 } from "#src/denial-messages";
-import type { PermissionPromptDecision } from "#src/permission-dialog";
 import { applyPermissionGate } from "#src/permission-gate";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import type { SessionApprovalRecorder } from "#src/session-approval-recorder";

package/src/handlers/gates/tool-call-gate-pipeline.ts

@@ -1,5 +1,6 @@
 import type { AccessPath } from "#src/access-intent/access-path";
 import { BashProgram } from "#src/access-intent/bash/program";
+import { classifyToolKind } from "#src/access-intent/tool-kind";
 import type { PathNormalizer } from "#src/path-normalizer";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
@@ -77,7 +78,7 @@ export class ToolCallGatePipeline {
     const command = getNonEmptyString(toRecord(tcc.input).command);
     const normalizer = this.inputs.getPathNormalizer();
     const bashProgram =
-      tcc.toolName === "bash" && command
+      classifyToolKind(tcc.toolName) === "bash" && command
         ? await BashProgram.parse(
             command,
             normalizer,
@@ -159,7 +160,7 @@ export class ToolCallGatePipeline {
     command: string | null,
     normalizer: PathNormalizer,
   ): { toolCheck: PermissionCheckResult; accessPath?: AccessPath } {
-    if (tcc.toolName === "bash" && bashProgram) {
+    if (classifyToolKind(tcc.toolName) === "bash" && bashProgram) {
       return {
         toolCheck: resolveBashCommandCheck(
           command ?? "",

package/src/handlers/gates/tool.ts

@@ -1,4 +1,5 @@
 import type { AccessPath } from "#src/access-intent/access-path";
+import { classifyToolKind } from "#src/access-intent/tool-kind";
 import { PATH_BEARING_TOOLS } from "#src/path-surfaces";
 import { suggestSessionPattern } from "#src/pattern-suggest";
 import { formatAskPrompt } from "#src/permission-prompts";
@@ -23,10 +24,14 @@ function deriveSuggestionValue(
   check: PermissionCheckResult,
   accessPath?: AccessPath,
 ): string {
-  if (tcc.toolName === "bash") return check.command ?? "";
-  if (tcc.toolName === "mcp") return check.target ?? "mcp";
-  if (accessPath) return accessPath.value();
-  return "*";
+  switch (classifyToolKind(tcc.toolName)) {
+    case "bash":
+      return check.command ?? "";
+    case "mcp":
+      return check.target ?? "mcp";
+    default:
+      return accessPath ? accessPath.value() : "*";
+  }
 }
 
 /**

package/src/index.ts

@@ -1,12 +1,17 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { getAgentDir, getPackageDir } from "@earendil-works/pi-coding-agent";
+import { warmBashParser } from "./access-intent/bash/parser";
 import { AuthorizerSelection } from "./authority/authorizer-selection";
 import {
   ForwardedRequestServer,
   type ServingPolicy,
 } from "./authority/forwarded-request-server";
+import { ForwardingManager } from "./authority/forwarding-manager";
+import { requestPermissionDecisionFromUi } from "./authority/permission-dialog";
 import { PermissionPrompter } from "./authority/permission-prompter";
 import { SubagentDetection } from "./authority/subagent-detection";
+import { subscribeSubagentLifecycle } from "./authority/subagent-lifecycle-events";
+import { getSubagentSessionRegistry } from "./authority/subagent-registry";
 import { registerBuiltinToolInputFormatters } from "./builtin-tool-input-formatters";
 import { registerPermissionSystemCommand } from "./config-modal";
 import { getGlobalConfigPath } from "./config-paths";
@@ -15,7 +20,6 @@ import { DecisionAudit } from "./decision-audit";
 import { GateDecisionReporter } from "./decision-reporter";
 import { isYoloModeEnabled } from "./extension-config";
 import { computeExtensionPaths } from "./extension-paths";
-import { ForwardingManager } from "./forwarding-manager";
 import {
   AgentPrepHandler,
   PermissionGateHandler,
@@ -26,7 +30,7 @@ import { SkillInputGatePipeline } from "./handlers/gates/skill-input-gate-pipeli
 import { ToolCallGatePipeline } from "./handlers/gates/tool-call-gate-pipeline";
 import { createFailClosedToolCall } from "./handlers/tool-call-boundary";
 import { buildAccessIntentForSurface } from "./input-normalizer";
-import { requestPermissionDecisionFromUi } from "./permission-dialog";
+import { pathFlavorForPlatform } from "./path/path-flavor";
 import { PermissionManager } from "./permission-manager";
 import { PermissionResolver } from "./permission-resolver";
 import { PermissionSession } from "./permission-session";
@@ -34,8 +38,6 @@ import { LocalPermissionsService } from "./permissions-service";
 import { PermissionServiceLifecycle } from "./service-lifecycle";
 import { PermissionSessionLogger } from "./session-logger";
 import { SessionRules } from "./session-rules";
-import { subscribeSubagentLifecycle } from "./subagent-lifecycle-events";
-import { getSubagentSessionRegistry } from "./subagent-registry";
 import { ToolAccessExtractorRegistry } from "./tool-access-extractor-registry";
 import { ToolInputFormatterRegistry } from "./tool-input-formatter-registry";
 
@@ -44,17 +46,19 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   // getPackageDir() is Pi's own install dir; auto-allow it for read-only tools
   // so the agent can read Pi's bundled docs/examples regardless of layout.
   const paths = computeExtensionPaths(agentDir, getPackageDir());
-  // The single process.platform read for the whole extension; injected into the
-  // session (PathNormalizer) and, later, rule evaluation. Interior modules must
-  // not read process.platform (enforced by the eslint guard scoped to src/).
-  const hostPlatform = process.platform;
+  // The single process.platform read for the whole extension, resolved once
+  // into the path-language flavor that every consumer shares (the session's
+  // PathNormalizer, rule evaluation, and subagent detection). Interior modules
+  // must not read process.platform (enforced by the eslint guard scoped to
+  // src/) and never re-derive the win32 flavor — they receive this product.
+  const hostFlavor = pathFlavorForPlatform(process.platform);
   const sessionRules = new SessionRules();
   const subagentRegistry = getSubagentSessionRegistry();
   // Single owner of subagent detection, shared across every consumer instead of
   // threading the (subagentSessionsDir, platform, registry) triple into each.
   const subagentDetection = new SubagentDetection({
     subagentSessionsDir: paths.subagentSessionsDir,
-    platform: hostPlatform,
+    flavor: hostFlavor,
     registry: subagentRegistry,
   });
   const formatterRegistry = new ToolInputFormatterRegistry();
@@ -75,7 +79,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   // assigned below. yolo becomes a composition-stage ask→allow rewrite (#526).
   const permissionManager = new PermissionManager({
     agentDir,
-    platform: hostPlatform,
+    flavor: hostFlavor,
     isYoloEnabled: () => isYoloModeEnabled(configStore.current()),
   });
 
@@ -146,7 +150,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     sessionRules,
     configStore,
     authorizerSelection,
-    hostPlatform,
+    hostFlavor,
   );
 
   // refresh() must run after `session` is assigned: a debug-write IO failure
@@ -204,7 +208,14 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     logger,
     audit,
   );
-  const agentPrep = new AgentPrepHandler(session, resolver, toolRegistry);
+  const agentPrep = new AgentPrepHandler(
+    session,
+    resolver,
+    toolRegistry,
+    () => {
+      void warmBashParser();
+    },
+  );
 
   const reporter = new GateDecisionReporter(logger, pi.events);
   const gateRunner = new GateRunner(

package/src/input-normalizer.ts

@@ -1,4 +1,5 @@
 import type { AccessIntent } from "./access-intent/access-intent";
+import { classifyToolKind } from "./access-intent/tool-kind";
 import { stripBashCommentLines } from "./bash-arity";
 import { createMcpPermissionTargets } from "./mcp-targets";
 import type { PathNormalizer } from "./path-normalizer";
@@ -106,55 +107,59 @@ export function normalizeInput(
   input: unknown,
   configuredMcpServerNames: readonly string[],
 ): NormalizedInput {
-  // --- Skill ---
-  if (toolName === "skill") {
-    const record = toRecord(input);
-    const skillName = record.name;
-    const lookupValue = typeof skillName === "string" ? skillName : "*";
-    return {
-      surface: "skill",
-      values: [lookupValue],
-      resultExtras: {},
-    };
-  }
+  switch (classifyToolKind(toolName)) {
+    // --- Skill ---
+    case "skill": {
+      const record = toRecord(input);
+      const skillName = record.name;
+      const lookupValue = typeof skillName === "string" ? skillName : "*";
+      return {
+        surface: "skill",
+        values: [lookupValue],
+        resultExtras: {},
+      };
+    }
 
-  // --- Bash ---
-  if (toolName === "bash") {
-    const record = toRecord(input);
-    const command = typeof record.command === "string" ? record.command : "";
-    // Strip leading shell comment lines so pattern matching operates on the
-    // actual command, not a `# description` prefix agents often prepend.
-    // Fall back to the raw command when stripping leaves nothing, so an
-    // all-comment command still evaluates against its literal text.
-    const matchValue = stripBashCommentLines(command) || command;
-    return {
-      surface: "bash",
-      values: [matchValue],
-      resultExtras: { command },
-    };
-  }
+    // --- Bash ---
+    case "bash": {
+      const record = toRecord(input);
+      const command = typeof record.command === "string" ? record.command : "";
+      // Strip leading shell comment lines so pattern matching operates on the
+      // actual command, not a `# description` prefix agents often prepend.
+      // Fall back to the raw command when stripping leaves nothing, so an
+      // all-comment command still evaluates against its literal text.
+      const matchValue = stripBashCommentLines(command) || command;
+      return {
+        surface: "bash",
+        values: [matchValue],
+        resultExtras: { command },
+      };
+    }
 
-  // --- MCP ---
-  if (toolName === "mcp") {
-    const mcpTargets = [
-      ...createMcpPermissionTargets(input, configuredMcpServerNames),
-      "mcp",
-    ];
-    const fallbackTarget = mcpTargets[0] ?? "mcp";
-    return {
-      surface: "mcp",
-      values: mcpTargets,
-      resultExtras: { target: fallbackTarget },
-    };
-  }
+    // --- MCP ---
+    case "mcp": {
+      const mcpTargets = [
+        ...createMcpPermissionTargets(input, configuredMcpServerNames),
+        "mcp",
+      ];
+      const fallbackTarget = mcpTargets[0] ?? "mcp";
+      return {
+        surface: "mcp",
+        values: mcpTargets,
+        resultExtras: { target: fallbackTarget },
+      };
+    }
 
-  // --- All other surfaces (path-bearing tools and extension tools) ---
-  // Path-bearing tools with a present path never reach here — the gate emits
-  // an access-path intent (#502). Missing-path and extension-tool cases both
-  // collapse to the surface catch-all.
-  return {
-    surface: toolName,
-    values: ["*"],
-    resultExtras: {},
-  };
+    // --- All other surfaces (path-bearing tools and extension tools) ---
+    // Path-bearing tools with a present path never reach here — the gate emits
+    // an access-path intent (#502). Missing-path and extension-tool cases both
+    // collapse to the surface catch-all.
+    case "path":
+    case "extension":
+      return {
+        surface: toolName,
+        values: ["*"],
+        resultExtras: {},
+      };
+  }
 }

package/src/{canonicalize-path.ts → path/canonicalize-path.ts}

@@ -1,5 +1,6 @@
 import { realpathSync } from "node:fs";
-import { posix as posixPath, win32 as winPath } from "node:path";
+
+import type { PathFlavor } from "#src/path/path-flavor";
 
 /**
  * Resolve symlinks in an absolute path, best-effort.
@@ -13,11 +14,11 @@ import { posix as posixPath, win32 as winPath } from "node:path";
  */
 export function canonicalizePath(
   absolutePath: string,
-  platform: NodeJS.Platform,
+  flavor: PathFlavor,
 ): string {
   if (!absolutePath) return absolutePath;
 
-  const impl = platform === "win32" ? winPath : posixPath;
+  const { impl } = flavor;
   const root = impl.parse(absolutePath).root;
   const rest = absolutePath.slice(root.length);
   const parts = rest.split(impl.sep).filter(Boolean);

package/src/path/path-containment.ts

@@ -0,0 +1,24 @@
+import type { PathFlavor } from "#src/path/path-flavor";
+import { isSafeSystemPath } from "#src/safe-system-paths";
+
+/**
+ * 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; the containment
+ * geometry lives on {@link PathFlavor.isWithin}.
+ */
+export function isPathOutsideWorkingDirectory(
+  canonicalPath: string,
+  canonicalCwd: string,
+  flavor: PathFlavor,
+): boolean {
+  if (!canonicalCwd || !canonicalPath) {
+    return false;
+  }
+  if (isSafeSystemPath(canonicalPath)) {
+    return false;
+  }
+  return !flavor.isWithin(canonicalPath, canonicalCwd);
+}