@gotgenes/pi-permission-system 20.3.0 → 20.4.1

package/src/access-intent/tool-kind.ts

@@ -0,0 +1,57 @@
+import { PATH_BEARING_TOOLS } from "#src/path-surfaces";
+
+/**
+ * What a tool invocation accesses — decided once from the tool name at the
+ * point an invocation enters the system.
+ *
+ * This is the single dispatch point that replaces the scattered
+ * `toolName === "bash"`/`"mcp"` re-derivation across the extraction consumers
+ * (`input-normalizer`, `tool-input-path`, the tool-call gate pipeline, and
+ * `permission-manager`'s source derivation) and the presentation consumers
+ * (`tool-preview-formatter`, `permission-prompts`, `denial-messages`, and
+ * `deriveDecisionValue`), which dispatch on {@link classifyToolKind} or
+ * {@link isMcpCheck}. Adding a tool kind means editing {@link classifyToolKind}
+ * plus the exhaustive switches the compiler flags — an OCP win over silent
+ * `===` comparisons a new variant sails past (#561).
+ *
+ * The value is plain data (a string union): `tool-kind.ts` imports no
+ * `AccessPath`, so `permission-manager.ts` may consume it without breaching the
+ * string boundary formalized in ADR-0002
+ * (`docs/decisions/0002-path-values-string-boundary.md`).
+ *
+ * - `bash` — its own token-based path gates; extraction product is the command.
+ * - `mcp` — extraction product is the qualified target.
+ * - `skill` — a distinct surface `normalizeInput`/`deriveSource` treat specially.
+ * - `path` — a path-bearing built-in (`read`/`write`/`edit`/`grep`/`find`/`ls`);
+ *   extraction product is `input.path`.
+ * - `extension` — every other tool, plus the `external_directory`/`path` special
+ *   surfaces that reach `deriveSource` as normalized names.
+ */
+export type ToolKind = "bash" | "mcp" | "skill" | "path" | "extension";
+
+/** Classify a tool name into its {@link ToolKind}. */
+export function classifyToolKind(toolName: string): ToolKind {
+  const name = toolName.trim();
+  if (name === "bash") return "bash";
+  if (name === "mcp") return "mcp";
+  if (name === "skill") return "skill";
+  if (PATH_BEARING_TOOLS.has(name)) return "path";
+  return "extension";
+}
+
+/** The resolved-check fields that decide MCP-ness. */
+interface McpKindFields {
+  toolName: string;
+  source: string;
+}
+
+/**
+ * True when a resolved check concerns an MCP call — either the invoked tool is
+ * `mcp`, or the winning rule matched on the `mcp` surface (`source`). The
+ * `source` disjunct is why this cannot reduce to `classifyToolKind(toolName)`:
+ * `deriveSource` can set `source` to `mcp` on a result whose `toolName` is a
+ * server-qualified string.
+ */
+export function isMcpCheck(check: McpKindFields): boolean {
+  return check.source === "mcp" || classifyToolKind(check.toolName) === "mcp";
+}

package/src/authority/approval-escalator.ts

@@ -18,7 +18,7 @@ import {
   sleep,
   writeJsonFileAtomic,
 } from "#src/authority/forwarding-io";
-import type { PermissionPromptDecision } from "#src/permission-dialog";
+import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 import {
   type ForwardedPermissionRequest,
   type ForwardedPromptDisplay,
@@ -28,10 +28,10 @@ import {
   type PermissionForwardingLocation,
   resolvePermissionForwardingTargetSessionId,
   SUBAGENT_PARENT_SESSION_ENV_CANDIDATES,
-} from "#src/permission-forwarding";
+} from "#src/authority/permission-forwarding";
+import type { SubagentSessionRegistry } from "#src/authority/subagent-registry";
 import { buildUiPrompt } from "#src/permission-ui-prompt";
 import type { DebugReviewLogger } from "#src/session-logger";
-import type { SubagentSessionRegistry } from "#src/subagent-registry";
 import { toRecord } from "#src/value-guards";
 import type { Authorizer } from "./authorizer";
 import type { PromptPermissionDetails } from "./permission-prompter";

package/src/authority/authorizer-selection.ts

@@ -1,5 +1,5 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { PermissionPromptDecision } from "#src/permission-dialog";
+import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 import {
   type Authorizer,
   type AuthorizerSelectionDeps,

package/src/authority/authorizer.ts

@@ -2,10 +2,10 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type {
   PermissionPromptDecision,
   requestPermissionDecisionFromUi,
-} from "#src/permission-dialog";
+} from "#src/authority/permission-dialog";
+import type { SubagentSessionRegistry } from "#src/authority/subagent-registry";
 import type { PermissionEventBus } from "#src/permission-events";
 import type { DebugReviewLogger } from "#src/session-logger";
-import type { SubagentSessionRegistry } from "#src/subagent-registry";
 import { ParentAuthorizer } from "./approval-escalator";
 import { DenyingAuthorizer } from "./denying-authorizer";
 import { LocalUserAuthorizer } from "./local-user-authorizer";

package/src/authority/denying-authorizer.ts

@@ -1,4 +1,4 @@
-import type { PermissionPromptDecision } from "#src/permission-dialog";
+import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 import type { Authorizer } from "./authorizer";
 
 /**

package/src/authority/forwarded-request-server.ts

@@ -3,17 +3,17 @@ import {
   type ForwarderContext,
   getSessionId,
 } from "#src/authority/forwarder-context";
-import type { PermissionPromptDecision } from "#src/permission-dialog";
+import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 import {
   type ForwardedPermissionRequest,
   type ForwardedPermissionResponse,
   isForwardedPermissionRequestForSession,
   type PermissionForwardingLocation,
-} from "#src/permission-forwarding";
+} from "#src/authority/permission-forwarding";
+import type { SubagentSessionRegistry } from "#src/authority/subagent-registry";
 import { SessionApproval } from "#src/session-approval";
 import type { SessionApprovalRecorder } from "#src/session-approval-recorder";
 import type { DebugReviewLogger } from "#src/session-logger";
-import type { SubagentSessionRegistry } from "#src/subagent-registry";
 import type { PermissionCheckResult } from "#src/types";
 import type { AskEscalator } from "./authorizer-selection";
 import {

package/src/authority/forwarder-context.ts

@@ -1,5 +1,5 @@
 import type { SessionEntryView } from "#src/active-agent";
-import type { PermissionDecisionUi } from "#src/permission-dialog";
+import type { PermissionDecisionUi } from "#src/authority/permission-dialog";
 
 /**
  * Narrow context the forwarding subsystem reads: the UI gate (`hasUI`), the

package/src/authority/forwarding-io.ts

@@ -9,15 +9,15 @@ import {
   writeFileSync,
 } from "node:fs";
 
-import { isPermissionDecisionState } from "#src/permission-dialog";
-import type { PermissionUiPromptSource } from "#src/permission-events";
+import { isPermissionDecisionState } from "#src/authority/permission-dialog";
 import {
   createPermissionForwardingLocation,
   type ForwardedPermissionRequest,
   type ForwardedPermissionResponse,
   type ForwardedSessionApproval,
   type PermissionForwardingLocation,
-} from "#src/permission-forwarding";
+} from "#src/authority/permission-forwarding";
+import type { PermissionUiPromptSource } from "#src/permission-events";
 import type { DebugReviewLogger } from "#src/session-logger";
 
 /** Valid `permissions:ui_prompt` source values, for tolerant request reads. */

package/src/{forwarding-manager.ts → authority/forwarding-manager.ts}

@@ -1,7 +1,7 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { InboxProcessor } from "./authority/forwarded-request-server";
-import type { SubagentDetector } from "./authority/subagent-detection";
+import type { InboxProcessor } from "./forwarded-request-server";
 import { PERMISSION_FORWARDING_POLL_INTERVAL_MS } from "./permission-forwarding";
+import type { SubagentDetector } from "./subagent-detection";
 
 /**
  * Narrow interface for the forwarding lifecycle used by `PermissionSession`.

package/src/authority/local-user-authorizer.ts

@@ -1,10 +1,10 @@
-import { buildForwardedScopeLabels } from "#src/pattern-suggest";
 import type {
   PermissionDecisionUi,
   PermissionPromptDecision,
   RequestPermissionOptions,
   requestPermissionDecisionFromUi,
-} from "#src/permission-dialog";
+} from "#src/authority/permission-dialog";
+import { buildForwardedScopeLabels } from "#src/pattern-suggest";
 import {
   emitUiPromptEvent,
   type PermissionEventBus,

package/src/{permission-forwarding.ts → authority/permission-forwarding.ts}

@@ -1,7 +1,6 @@
 import { join } from "node:path";
-
+import type { PermissionUiPromptSource } from "#src/permission-events";
 import type { PermissionDecisionState } from "./permission-dialog";
-import type { PermissionUiPromptSource } from "./permission-events";
 import type { SubagentSessionRegistry } from "./subagent-registry";
 
 export const PERMISSION_FORWARDING_POLL_INTERVAL_MS = 250;

package/src/authority/permission-prompter.ts

@@ -1,5 +1,5 @@
-import type { PermissionPromptDecision } from "#src/permission-dialog";
-import type { ForwardedSessionApproval } from "#src/permission-forwarding";
+import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
+import type { ForwardedSessionApproval } from "#src/authority/permission-forwarding";
 import type { ReviewLogger } from "#src/session-logger";
 import type { Authorizer } from "./authorizer";
 

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/bash-command.ts

@@ -1,4 +1,7 @@
-import type { BashCommand } from "#src/access-intent/bash/command-enumeration";
+import type {
+  BashCommand,
+  WrapperKind,
+} from "#src/access-intent/bash/command-enumeration";
 import { pickMostRestrictive } from "#src/handlers/gates/candidate-check";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import type { PermissionCheckResult } from "#src/types";
@@ -19,11 +22,13 @@ import type { PermissionCheckResult } from "#src/types";
  * `commandContext` (set only for a nested command), so the prompt,
  * session-approval suggestion, and decision event scope to that command.
  *
- * An opaque-payload wrapper unit (`bash -c`/`eval`, flagged `opaque` by the
- * enumerator) has its inner program hidden behind a quoted argument, so an
- * `allow` is floored up to a synthetic `ask` (the `<opaque-bash-wrapper>`
- * pattern) to keep it from riding a permissive rule; an explicit `deny`/`ask`
- * on the wrapper is left untouched (`deny > ask > allow`).
+ * A wrapper unit (flagged with a `wrapperKind` by the enumerator) hides or
+ * indirects the command that should be gated, so an `allow` is floored up to a
+ * synthetic `ask` — the `<opaque-bash-wrapper>` pattern for an inline-shell
+ * payload (`bash -c`/`eval`, #481) or `<indirection-bash-wrapper>` for a
+ * prefix/exec wrapper (`sudo`/`env`/`xargs`/`find -exec`/…, #490) — to keep it
+ * from riding a permissive rule; an explicit `deny`/`ask` on the wrapper is left
+ * untouched (`deny > ask > allow`).
  *
  * When `commands` is empty there are two cases. A trivially-empty command (an
  * empty, whitespace-only, or comment-only line) has genuinely nothing to gate,
@@ -36,6 +41,15 @@ import type { PermissionCheckResult } from "#src/types";
  * Pure and synchronous: the (async, tree-sitter) parse happens once in the
  * handler, which passes the decomposed `commands` here.
  */
+/**
+ * The synthetic `matchedPattern` recorded when a wrapper unit's `allow` is
+ * floored to `ask`, keyed by the wrapper kind that caused the floor.
+ */
+const WRAPPER_SENTINEL: Record<WrapperKind, string> = {
+  "opaque-payload": "<opaque-bash-wrapper>",
+  indirection: "<indirection-bash-wrapper>",
+};
+
 export function resolveBashCommandCheck(
   command: string,
   commands: BashCommand[],
@@ -69,11 +83,11 @@ export function resolveBashCommandCheck(
       agentName,
     });
     const result =
-      cmd.opaque && base.state === "allow"
+      cmd.wrapperKind && base.state === "allow"
         ? {
             ...base,
             state: "ask" as const,
-            matchedPattern: "<opaque-bash-wrapper>",
+            matchedPattern: WRAPPER_SENTINEL[cmd.wrapperKind],
           }
         : base;
     return cmd.context ? { ...result, commandContext: cmd.context } : result;

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() : "*";
+  }
 }
 
 /**