fix(permission): alias tool names and grant trusted plugin reads

Classify, grants, and the execution cache use the same canonical name as dispatch so a default. prefix cannot force a second ask. Reads under trusted user plugin roots are not path-escape hard-denies; writes still are.

Author: TheGreatAxios

docs/PLUGINS.md

@@ -176,8 +176,7 @@ Discovered modules still require `settings.plugins[id].enabled` before agents or
 tools wire into the session. `search_agents` labels those profiles with
 `[source: claude]`. Default results are id, description, and spawn metadata;
 pass `include_body=true` to include the loaded system prompt / body so the
-parent never needs `read_file` on `~/.claude/plugins/...` (path-escape still
-blocks those roots for path tools; writes/deletes outside cwd stay denied). JS
+parent never needs `read_file` on `~/.claude/plugins/...` for profile bodies (`include_body=true`). Writes/deletes outside cwd stay denied. Reads of trusted user plugin dirs (`~/.corbits/plugins`) can be granted — path-escape does not hard-deny those reads before grants; writes remain denied. JS
 Claude plugins (if any) stay on explicit `pluginPaths`.
 
 `settings.workflowPlugins` / `settings.agentPlugins` (specifier arrays) are

src/agent/canonical-tool-name.ts

@@ -0,0 +1,20 @@
+const DEFAULT_PREFIX = "default.";
+
+// Muse Spark emits `default.<name>` and duplicated `<name>.<name>`. Dispatch
+// already strips those onto catalog keys; classify, grants, and the execution
+// cache must use the same name so an alias cannot force a second ask/deny.
+export function canonicalToolName(requested: string): string {
+  let name = requested;
+  if (name.startsWith(DEFAULT_PREFIX)) {
+    const stripped = name.slice(DEFAULT_PREFIX.length);
+    if (stripped.length > 0) name = stripped;
+  }
+  return undoubledName(name) ?? name;
+}
+
+function undoubledName(requested: string): string | undefined {
+  if (requested.length < 3 || requested.length % 2 === 0) return undefined;
+  const name = requested.slice(0, (requested.length - 1) / 2);
+  if (requested !== `${name}.${name}`) return undefined;
+  return name;
+}

src/agent/posix-tool-plugins.ts

@@ -114,7 +114,10 @@ export function buildCorePosixToolPlugins(
   return [
     resultTruncationPlugin(truncationOptions),
     toolResultSecretScrubPlugin(),
-    pathEscapePlugin(cwd, rootsProvider, { allowOutside }),
+    pathEscapePlugin(cwd, rootsProvider, {
+      allowOutside,
+      trustedPluginRoots: () => [...permissionGate.getTrustedPluginRoots()],
+    }),
     evidenceArchivePathGuardPlugin(),
     deleteFilePlugin(cwd, { allowOutside, rootsProvider }),
     toolOutputUriPlugin(),

src/permission/authz-grants.ts

@@ -1,5 +1,6 @@
 import { evaluateGrants, type GrantRule } from "@intx/authz";
 
+import { canonicalToolName } from "../agent/canonical-tool-name.js";
 import type { Approval } from "./types.js";
 import { matchesPattern } from "./matcher.js";
 import { realpathOr } from "./worktree-roots.js";
@@ -23,7 +24,7 @@ export function approvalToGrantRule(
     origin: "invoker",
     // resource = subject pattern (command or path); action = tool name.
     resource: approval.pattern,
-    action: approval.tool,
+    action: canonicalToolName(approval.tool),
     conditions: null,
     expiresAt: null,
   };
@@ -81,7 +82,7 @@ export function grantScopeMatches(
   workspace: GrantWorkspace,
 ): boolean {
   return (
-    approval.tool === tool &&
+    canonicalToolName(approval.tool) === canonicalToolName(tool) &&
     (approval.providerModel === undefined ||
       approval.providerModel === activeProviderModel) &&
     cwdMatchesGrant(approval.cwd, requestCwd, workspace)
@@ -115,8 +116,9 @@ export async function approvalCoversSubject(
     requestCwd,
     workspace,
   } = input;
+  const action = canonicalToolName(tool);
   const scoped = approvals.filter((a) =>
-    grantScopeMatches(a, tool, activeProviderModel, requestCwd, workspace),
+    grantScopeMatches(a, action, activeProviderModel, requestCwd, workspace),
   );
   if (scoped.length === 0) return false;
 
@@ -134,7 +136,7 @@ export async function approvalCoversSubject(
     .map((a, i) => approvalToGrantRule(a, i));
   if (grants.length === 0) return false;
 
-  const decision = await evaluateGrants(grants, subject, tool);
+  const decision = await evaluateGrants(grants, subject, action);
   return decision.effect === "allow";
 }
 

src/permission/classify.ts

@@ -29,6 +29,7 @@ import {
   productMutationPaths,
 } from "../agent/product-mutation-tools.js";
 import { AUTO_ALLOW_READ_TOOLS as READ_ONLY_TOOLS } from "../agent/tool-classification.js";
+import { canonicalToolName } from "../agent/canonical-tool-name.js";
 
 // Read-only tools never need approval as long as they don't touch a restricted
 // path; they cannot change the workspace. `lsp` is included here even though
@@ -91,11 +92,12 @@ export function classifyTool(
   toolName: string,
   mcpTiers?: McpToolPermissionRegistry,
 ): Tier {
-  if (READ_ONLY_TOOLS.has(toolName)) return "allow";
-  if (isMcpToolName(toolName)) {
-    const registered = mcpTiers?.tierFor(toolName);
+  const name = canonicalToolName(toolName);
+  if (READ_ONLY_TOOLS.has(name)) return "allow";
+  if (isMcpToolName(name)) {
+    const registered = mcpTiers?.tierFor(name);
     if (registered !== undefined) return registered;
-    if (isReadOnlyMcpTool(toolName)) return "allow";
+    if (isReadOnlyMcpTool(name)) return "allow";
     return "ask";
   }
   return "ask";
@@ -109,10 +111,12 @@ export function restrictedPathArg(
   call: ToolCall,
   isRestricted: (path: string, isWrite: boolean) => boolean,
 ): string | undefined {
-  if (!PATH_ARG_TOOLS.has(call.name)) return undefined;
-  const path = stringArg(call, pathArgKey(call.name));
+  if (!PATH_ARG_TOOLS.has(canonicalToolName(call.name))) return undefined;
+  const path = stringArg(call, pathArgKey(canonicalToolName(call.name)));
   if (path.length === 0) return undefined;
-  return isRestricted(path, isWriteTool(call.name)) ? path : undefined;
+  return isRestricted(path, isWriteTool(canonicalToolName(call.name)))
+    ? path
+    : undefined;
 }
 
 // Outside-workspace path arguments are fine for pure-listing programs — listing
@@ -256,10 +260,11 @@ export function callTargetsRestricted(
   call: ToolCall,
   isRestricted: (path: string, isWrite: boolean) => boolean,
 ): boolean {
-  if (call.name === "run_shell")
+  const name = canonicalToolName(call.name);
+  if (name === "run_shell")
     return commandTargetsRestricted(stringArg(call, "command"), isRestricted);
-  if (call.name === "apply_patch") {
-    return productMutationPaths(call.name, call.arguments).some((path) =>
+  if (name === "apply_patch") {
+    return productMutationPaths(name, call.arguments).some((path) =>
       isRestricted(path, true),
     );
   }
@@ -481,7 +486,7 @@ export function isAutoAllowedShellCall(
   cwd: string = process.cwd(),
   rootsProvider: RootsProvider = NO_ROOTS,
 ): boolean {
-  if (call.name !== "run_shell") return false;
+  if (canonicalToolName(call.name) !== "run_shell") return false;
   return isAutoAllowedShellCommand(
     stringArg(call, "command"),
     cwd,

src/permission/denial-memory.ts

@@ -52,8 +52,14 @@ export function stableRequestId(
   call: ToolCall,
   cwd: string = process.cwd(),
   rootsProvider: RootsProvider = () => [],
+  trustedPluginRoots?: RootsProvider,
 ): string {
-  const identity = normalizePathArguments(call.arguments, cwd, rootsProvider);
+  const identity = normalizePathArguments(
+    call.arguments,
+    cwd,
+    rootsProvider,
+    trustedPluginRoots,
+  );
   return (
     call.name +
     NULL_SEPARATOR +

src/permission/gate.ts

@@ -47,6 +47,7 @@ import { OPERATOR_DECLINED_PREFIX } from "./decline-markers.js";
 import { DenialMemory, stableRequestId } from "./denial-memory.js";
 import { getSubAgentIdentity } from "../subagent/identity-context.js";
 import { PRODUCT_MUTATION_TOOLS } from "../agent/product-mutation-tools.js";
+import { canonicalToolName } from "../agent/canonical-tool-name.js";
 
 import {
   createMcpToolPermissionRegistry,
@@ -368,6 +369,11 @@ export interface PermissionGateOptions {
   // already knows about — so a worktree created mid-session is picked up
   // without a restart.
   rootsProvider?: RootsProvider;
+  // Directories of trusted (fully loaded) plugins. Reads under these roots are
+  // not path-escape hard-denies — they stay restricted and can be granted.
+  // Writes and deletes remain path-escape denies; plugin trust is not write
+  // consent.
+  trustedPluginRoots?: RootsProvider;
   // Tiers learned from connected MCP servers (tools/list annotations). Tests may
   // inject a shared registry; production gates create one when omitted.
   mcpTiers?: McpToolPermissionRegistry;
@@ -470,6 +476,10 @@ export interface PermissionGate {
   setProviderIdentity: (providerName: string, model: string) => void;
   registerMcpClient: (client: MCPClient) => void;
   unregisterMcpServer: (serverName: string) => void;
+  // Live trusted plugin directories for path-escape's read exception. The
+  // posix plugin stack reads this so authorize-time and execution-time
+  // containment share one list.
+  getTrustedPluginRoots: () => readonly string[];
 }
 
 // True when splitChainedCommand can be trusted to yield only real segments for
@@ -489,8 +499,16 @@ function identityArguments(
   args: ToolCall["arguments"],
   cwd: string,
   rootsProvider: RootsProvider,
+  trustedPluginRoots?: RootsProvider,
 ): string {
-  return JSON.stringify(normalizePathArguments(args, cwd, rootsProvider));
+  return JSON.stringify(
+    normalizePathArguments(args, cwd, rootsProvider, trustedPluginRoots),
+  );
+}
+
+function withCanonicalToolName(call: ToolCall): ToolCall {
+  const name = canonicalToolName(call.name);
+  return name === call.name ? call : { ...call, name };
 }
 
 export function createPermissionGate(
@@ -505,6 +523,7 @@ export function createPermissionGate(
   const resolvedCwd = cwd ?? process.cwd();
   const rootsProvider =
     options.rootsProvider ?? createWorktreeRootsProvider(resolvedCwd);
+  const trustedPluginRoots = options.trustedPluginRoots ?? (() => []);
   const pathRestriction = createPathRestriction(resolvedCwd, rootsProvider);
   const isRestricted = pathRestriction.isRestricted;
   // This gate's project boundary for grant matching (see cwdMatchesGrant):
@@ -659,7 +678,8 @@ export function createPermissionGate(
         segmentCount: number;
       };
 
-  const decide = async (call: ToolCall): Promise<GateDecision> => {
+  const decide = async (rawCall: ToolCall): Promise<GateDecision> => {
+    const call = withCanonicalToolName(rawCall);
     // Catastrophic shell commands are hard-denied here, at the top of the
     // single verdict path every entry (evaluate, authorizeCall,
     // executionVerdict) flows through — this is the owning enforcement point
@@ -692,7 +712,12 @@ export function createPermissionGate(
     // deny below: the decision is the same deny either way, but the reason
     // text is the originally recorded one, not a freshly computed escape
     // reason.
-    const stableId = stableRequestId(call, effectiveCwd, rootsProvider);
+    const stableId = stableRequestId(
+      call,
+      effectiveCwd,
+      rootsProvider,
+      trustedPluginRoots,
+    );
     const cachedDenial = denialMemory.isDenied(stableId);
     if (cachedDenial !== undefined)
       return { kind: "deny", reason: cachedDenial };
@@ -711,6 +736,7 @@ export function createPermissionGate(
       effectiveCwd,
       escapeRoots,
       call.name,
+      trustedPluginRoots,
     );
     if (escapeReason !== undefined) {
       return { kind: "deny", reason: escapeReason };
@@ -1037,8 +1063,13 @@ export function createPermissionGate(
     const verdict = mapAuthorizeVerdict(await decide(call));
     const identityCwd = getSubAgentIdentity()?.cwd ?? resolvedCwd;
     authorizedByCallId.set(call.id, {
-      name: call.name,
-      arguments: identityArguments(call.arguments, identityCwd, rootsProvider),
+      name: canonicalToolName(call.name),
+      arguments: identityArguments(
+        call.arguments,
+        identityCwd,
+        rootsProvider,
+        trustedPluginRoots,
+      ),
       verdict,
     });
     return verdict;
@@ -1051,9 +1082,14 @@ export function createPermissionGate(
     const identityCwd = getSubAgentIdentity()?.cwd ?? resolvedCwd;
     if (
       cached !== undefined &&
-      cached.name === call.name &&
+      cached.name === canonicalToolName(call.name) &&
       cached.arguments ===
-        identityArguments(call.arguments, identityCwd, rootsProvider)
+        identityArguments(
+          call.arguments,
+          identityCwd,
+          rootsProvider,
+          trustedPluginRoots,
+        )
     ) {
       authorizedByCallId.delete(call.id);
       return cached.verdict;
@@ -1185,5 +1221,6 @@ export function createPermissionGate(
     },
     registerMcpClient,
     unregisterMcpServer,
+    getTrustedPluginRoots: () => trustedPluginRoots(),
   };
 }