@gotgenes/pi-permission-system 3.10.0 → 4.0.0

package/src/permission-manager.ts

@@ -9,15 +9,23 @@ import {
   parseSimpleYamlMap,
   toRecord,
 } from "./common";
-import { loadUnifiedConfig, stripJsonComments } from "./config-loader";
+import {
+  loadUnifiedConfig,
+  normalizeUnifiedConfig,
+  stripJsonComments,
+} from "./config-loader";
 import { getGlobalConfigPath } from "./config-paths";
-import { mergeDefaults } from "./defaults";
-import { normalizeConfig } from "./normalize";
-import type { Ruleset } from "./rule";
+import { normalizeFlatConfig } from "./normalize";
+import type { Rule, Ruleset } from "./rule";
 import { evaluate } from "./rule";
+import {
+  composeRuleset,
+  synthesizeBaseline,
+  synthesizeDefaults,
+} from "./synthesize";
 import type {
+  FlatPermissionConfig,
   PermissionCheckResult,
-  PermissionDefaultPolicy,
   PermissionState,
   ScopeConfig,
 } from "./types";
@@ -42,79 +50,37 @@ const BUILT_IN_TOOL_PERMISSION_NAMES = new Set([
   "ls",
 ]);
 const SPECIAL_PERMISSION_KEYS = new Set(["external_directory"]);
-const MCP_BASELINE_TARGETS = new Set([
-  "mcp_status",
-  "mcp_list",
-  "mcp_search",
-  "mcp_describe",
-  "mcp_connect",
-]);
-
-const DEFAULT_POLICY: PermissionDefaultPolicy = {
-  tools: "ask",
-  bash: "ask",
-  mcp: "ask",
-  skills: "ask",
-  special: "ask",
-};
-
-function normalizePolicy(value: unknown): PermissionDefaultPolicy {
-  const record = toRecord(value);
-  return {
-    tools: isPermissionState(record.tools)
-      ? record.tools
-      : DEFAULT_POLICY.tools,
-    bash: isPermissionState(record.bash) ? record.bash : DEFAULT_POLICY.bash,
-    mcp: isPermissionState(record.mcp) ? record.mcp : DEFAULT_POLICY.mcp,
-    skills: isPermissionState(record.skills)
-      ? record.skills
-      : DEFAULT_POLICY.skills,
-    special: isPermissionState(record.special)
-      ? record.special
-      : DEFAULT_POLICY.special,
-  };
-}
-
-function normalizePartialPolicy(
-  value: unknown,
-): Partial<PermissionDefaultPolicy> {
-  const record = toRecord(value);
-  const normalized: Partial<PermissionDefaultPolicy> = {};
-
-  if (isPermissionState(record.tools)) {
-    normalized.tools = record.tools;
-  }
-
-  if (isPermissionState(record.bash)) {
-    normalized.bash = record.bash;
-  }
-
-  if (isPermissionState(record.mcp)) {
-    normalized.mcp = record.mcp;
-  }
-
-  if (isPermissionState(record.skills)) {
-    normalized.skills = record.skills;
-  }
-
-  if (isPermissionState(record.special)) {
-    normalized.special = record.special;
-  }
-
-  return normalized;
-}
 
-function normalizePermissionRecord(
-  value: unknown,
-): Record<string, PermissionState> {
-  const record = toRecord(value);
-  const normalized: Record<string, PermissionState> = {};
-  for (const [key, state] of Object.entries(record)) {
-    if (isPermissionState(state)) {
-      normalized[key] = state;
+/** Universal fallback when permission["*"] is absent from all scopes. */
+const DEFAULT_UNIVERSAL_FALLBACK: PermissionState = "ask";
+
+/**
+ * Deep-shallow merge two flat permission configs.
+ * Both objects → shallow-merge the pattern maps.
+ * Otherwise → override replaces base.
+ */
+function mergeFlatPermissions(
+  base: FlatPermissionConfig,
+  override: FlatPermissionConfig,
+): FlatPermissionConfig {
+  const merged: FlatPermissionConfig = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    const baseVal = merged[key];
+    if (
+      typeof baseVal === "object" &&
+      baseVal !== null &&
+      typeof value === "object" &&
+      value !== null
+    ) {
+      merged[key] = {
+        ...(baseVal as Record<string, PermissionState>),
+        ...(value as Record<string, PermissionState>),
+      };
+    } else {
+      merged[key] = value;
     }
   }
-  return normalized;
+  return merged;
 }
 
 function readConfiguredMcpServerNamesFromConfigPath(
@@ -150,208 +116,6 @@ function getConfiguredMcpServerNamesFromPaths(
   );
 }
 
-const DEPRECATED_SPECIAL_KEYS: ReadonlySet<string> = new Set([
-  "doom_loop",
-  "tool_call_limit",
-]);
-
-export interface NormalizeResult {
-  permissions: ScopeConfig;
-  configIssues: string[];
-}
-
-export function normalizeRawPermission(raw: unknown): NormalizeResult {
-  const record = toRecord(raw);
-  const configIssues: string[] = [];
-  const normalizedTools = normalizePermissionRecord(record.tools);
-
-  const normalized: ScopeConfig = {
-    defaultPolicy: normalizePartialPolicy(record.defaultPolicy),
-    tools: normalizedTools,
-    bash: normalizePermissionRecord(record.bash),
-    mcp: normalizePermissionRecord(record.mcp),
-    skills: normalizePermissionRecord(record.skills),
-    special: normalizePermissionRecord(record.special),
-  };
-
-  // Detect deprecated keys in the raw special sub-object before discarding.
-  const rawSpecial = toRecord(record.special);
-  for (const key of DEPRECATED_SPECIAL_KEYS) {
-    if (key in rawSpecial) {
-      configIssues.push(
-        `special.${key} is deprecated and ignored — remove it from your policy file.`,
-      );
-      // Ensure the key is stripped even if its value was a valid PermissionState.
-      if (normalized.special) {
-        delete normalized.special[key];
-      }
-    }
-  }
-
-  for (const [key, value] of Object.entries(record)) {
-    if (!isPermissionState(value)) {
-      continue;
-    }
-
-    if (BUILT_IN_TOOL_PERMISSION_NAMES.has(key)) {
-      normalized.tools = { ...(normalized.tools || {}), [key]: value };
-      continue;
-    }
-
-    if (SPECIAL_PERMISSION_KEYS.has(key)) {
-      normalized.special = { ...(normalized.special || {}), [key]: value };
-    }
-  }
-
-  return { permissions: normalized, configIssues };
-}
-
-function parseQualifiedMcpToolName(
-  value: string,
-): { server: string; tool: string } | null {
-  const trimmed = value.trim();
-  if (!trimmed) {
-    return null;
-  }
-
-  const colonIndex = trimmed.indexOf(":");
-  if (colonIndex <= 0 || colonIndex >= trimmed.length - 1) {
-    return null;
-  }
-
-  const server = trimmed.slice(0, colonIndex).trim();
-  const tool = trimmed.slice(colonIndex + 1).trim();
-  if (!server || !tool) {
-    return null;
-  }
-
-  return { server, tool };
-}
-
-function addDerivedMcpServerTargets(
-  toolName: string,
-  configuredServerNames: readonly string[],
-  pushTarget: (value: string | null) => void,
-): void {
-  const trimmedToolName = toolName.trim();
-  if (!trimmedToolName) {
-    return;
-  }
-
-  for (const serverName of configuredServerNames) {
-    const trimmedServerName = serverName.trim();
-    if (!trimmedServerName) {
-      continue;
-    }
-
-    if (!trimmedToolName.endsWith(`_${trimmedServerName}`)) {
-      continue;
-    }
-
-    if (trimmedToolName.startsWith(`${trimmedServerName}_`)) {
-      continue;
-    }
-
-    pushTarget(`${trimmedServerName}_${trimmedToolName}`);
-    pushTarget(`${trimmedServerName}:${trimmedToolName}`);
-    pushTarget(trimmedServerName);
-  }
-}
-
-function pushMcpToolPermissionTargets(
-  rawReference: string,
-  serverHint: string | null,
-  configuredServerNames: readonly string[],
-  pushTarget: (value: string | null) => void,
-): void {
-  const qualified = parseQualifiedMcpToolName(rawReference);
-  const resolvedServer = serverHint ?? qualified?.server ?? null;
-  const resolvedTool = qualified?.tool ?? rawReference;
-
-  if (resolvedServer) {
-    pushTarget(`${resolvedServer}_${resolvedTool}`);
-    pushTarget(`${resolvedServer}:${resolvedTool}`);
-    pushTarget(resolvedServer);
-  } else {
-    addDerivedMcpServerTargets(resolvedTool, configuredServerNames, pushTarget);
-  }
-
-  pushTarget(resolvedTool);
-  pushTarget(rawReference);
-}
-
-function createMcpPermissionTargets(
-  input: unknown,
-  configuredServerNames: readonly string[] = [],
-): string[] {
-  const record = toRecord(input);
-  const tool = getNonEmptyString(record.tool);
-  const server = getNonEmptyString(record.server);
-  const connect = getNonEmptyString(record.connect);
-  const describe = getNonEmptyString(record.describe);
-  const search = getNonEmptyString(record.search);
-
-  const targets: string[] = [];
-  const pushTarget = (value: string | null) => {
-    if (!value) {
-      return;
-    }
-    if (!targets.includes(value)) {
-      targets.push(value);
-    }
-  };
-
-  if (tool) {
-    pushMcpToolPermissionTargets(
-      tool,
-      server,
-      configuredServerNames,
-      pushTarget,
-    );
-    pushTarget("mcp_call");
-    return targets;
-  }
-
-  if (connect) {
-    pushTarget(`mcp_connect_${connect}`);
-    pushTarget(connect);
-    pushTarget("mcp_connect");
-    return targets;
-  }
-
-  if (describe) {
-    pushMcpToolPermissionTargets(
-      describe,
-      server,
-      configuredServerNames,
-      pushTarget,
-    );
-    pushTarget("mcp_describe");
-    return targets;
-  }
-
-  if (search) {
-    if (server) {
-      pushTarget(`mcp_server_${server}`);
-      pushTarget(server);
-    }
-
-    pushTarget(search);
-    pushTarget("mcp_search");
-    return targets;
-  }
-
-  if (server) {
-    pushTarget(`mcp_server_${server}`);
-    pushTarget(server);
-    pushTarget("mcp_list");
-    return targets;
-  }
-
-  pushTarget("mcp_status");
-  return targets;
-}
-
 export interface ResolvedPolicyPaths {
   globalConfigPath: string;
   globalConfigExists: boolean;
@@ -364,13 +128,11 @@ export interface ResolvedPolicyPaths {
 }
 
 type ResolvedPermissions = {
-  rules: Ruleset;
-  defaults: PermissionDefaultPolicy;
-  /** tools.bash fallback: tools.bash || defaults.bash */
-  bashDefault: PermissionState;
-  /** tools.mcp fallback (undefined = no explicit tools.mcp) */
-  mcpToolLevel: PermissionState | undefined;
-  hasAnyMcpAllowRule: boolean;
+  /**
+   * Fully composed ruleset: synthesized defaults → baseline → config.
+   * Session rules are appended at call-time inside checkPermission().
+   */
+  composedRules: Ruleset;
 };
 
 type FileCacheEntry<TValue> = {
@@ -464,12 +226,7 @@ export class PermissionManager {
     this.accumulateConfigIssues(issues);
 
     const value: ScopeConfig = {
-      defaultPolicy: normalizePolicy(config.defaultPolicy),
-      tools: config.tools || {},
-      bash: config.bash || {},
-      mcp: config.mcp || {},
-      skills: config.skills || {},
-      special: config.special || {},
+      permission: config.permission,
     };
 
     this.globalConfigCache = { stamp, value };
@@ -490,12 +247,7 @@ export class PermissionManager {
     this.accumulateConfigIssues(issues);
 
     const value: ScopeConfig = {
-      defaultPolicy: config.defaultPolicy,
-      tools: config.tools,
-      bash: config.bash,
-      mcp: config.mcp,
-      skills: config.skills,
-      special: config.special,
+      permission: config.permission,
     };
 
     this.projectGlobalConfigCache = { stamp, value };
@@ -526,9 +278,11 @@ export class PermissionManager {
         value = {};
       } else {
         const parsed = parseSimpleYamlMap(frontmatter);
-        const result = normalizeRawPermission(parsed.permission);
-        value = result.permissions;
-        this.accumulateConfigIssues(result.configIssues);
+        // Re-use the config-loader normalizer so the flat permission shape
+        // is validated the same way as on-disk config files.
+        const { config, issues } = normalizeUnifiedConfig(parsed);
+        this.accumulateConfigIssues(issues);
+        value = { permission: config.permission };
       }
     } catch {
       value = {};
@@ -599,50 +353,46 @@ export class PermissionManager {
     const agentConfig = this.loadScopeConfig(agentName);
     const projectAgentConfig = this.loadProjectScopeConfig(agentName);
 
-    // Normalize each scope into a flat Ruleset and concatenate.
-    // Later scopes appear last → higher priority via last-match-wins.
-    const rules: Ruleset = [
-      ...normalizeConfig(globalConfig),
-      ...normalizeConfig(projectConfig),
-      ...normalizeConfig(agentConfig),
-      ...normalizeConfig(projectAgentConfig),
-    ];
-
-    // Merge defaults separately (shallow spread, same precedence order).
-    const defaults = mergeDefaults(
-      globalConfig.defaultPolicy,
-      projectConfig.defaultPolicy,
-      agentConfig.defaultPolicy,
-      projectAgentConfig.defaultPolicy,
-    );
+    // Merge permission objects across scopes (lowest → highest precedence).
+    let mergedPermission: FlatPermissionConfig = {};
+    for (const scope of [
+      globalConfig,
+      projectConfig,
+      agentConfig,
+      projectAgentConfig,
+    ]) {
+      if (scope.permission) {
+        mergedPermission = mergeFlatPermissions(
+          mergedPermission,
+          scope.permission,
+        );
+      }
+    }
 
-    // tools.bash / tools.mcp are fallback overrides, not catch-all rules.
-    // Extract with last-scope-wins precedence.
-    const toolBash =
-      projectAgentConfig.tools?.bash ??
-      agentConfig.tools?.bash ??
-      projectConfig.tools?.bash ??
-      globalConfig.tools?.bash;
-    const bashDefault = toolBash ?? defaults.bash;
-
-    const mcpToolLevel =
-      projectAgentConfig.tools?.mcp ??
-      agentConfig.tools?.mcp ??
-      projectConfig.tools?.mcp ??
-      globalConfig.tools?.mcp;
-
-    const hasAnyMcpAllowRule = rules.some(
-      (r) => r.surface === "mcp" && r.action === "allow",
+    // Extract the universal fallback from permission["*"].
+    // The "*" key feeds synthesizeDefaults() only — it is NOT included as a
+    // config rule so that extension tools fall through to source:"default".
+    const universalFallback = isPermissionState(mergedPermission["*"])
+      ? (mergedPermission["*"] as PermissionState)
+      : DEFAULT_UNIVERSAL_FALLBACK;
+
+    // Build config rules from everything except the universal "*" key.
+    const permissionWithoutUniversal: FlatPermissionConfig = Object.fromEntries(
+      Object.entries(mergedPermission).filter(([k]) => k !== "*"),
     );
 
-    const value: ResolvedPermissions = {
-      rules,
-      defaults,
-      bashDefault,
-      mcpToolLevel,
-      hasAnyMcpAllowRule,
-    };
+    // Normalize to config rules, tagged with "config" layer.
+    const configRules: Ruleset = normalizeFlatConfig(
+      permissionWithoutUniversal,
+    ).map((r): Rule => ({ ...r, layer: "config" }));
+
+    const composedRules = composeRuleset(
+      synthesizeDefaults(universalFallback),
+      synthesizeBaseline(configRules),
+      configRules,
+    );
 
+    const value: ResolvedPermissions = { composedRules };
     this.resolvedPermissionsCache.set(cacheKey, { stamp, value });
     return value;
   }
@@ -666,60 +416,75 @@ export class PermissionManager {
   }
 
   /**
-   * Get the tool-level permission state for a tool, without considering command-level rules.
-   * This is used for tool injection decisions where we need to know if a tool is allowed/denied
-   * at the tool level before checking specific command permissions.
-   *
-   * With tool-name-as-surface normalization, tools.bash becomes a bash catch-all
-   * { surface: "bash", pattern: "*", action } so getToolPermission("bash")
-   * naturally picks it up via evaluate("bash", "*", rules).
-   *
-   * @param toolName - The name of the tool (for example "bash", "read", or a third-party tool name)
-   * @param agentName - Optional agent name to check agent-specific permissions
-   * @returns The permission state for the tool at the tool level
+   * Get the tool-level permission state for a tool, without considering
+   * command-level rules. Used for tool injection decisions.
    */
   getToolPermission(toolName: string, agentName?: string): PermissionState {
-    const { rules, defaults, bashDefault, mcpToolLevel } =
-      this.resolvePermissions(agentName);
+    const { composedRules } = this.resolvePermissions(agentName);
     const normalizedToolName = toolName.trim();
 
-    // Special keys use the special default.
+    // Special surfaces (external_directory): evaluate directly by surface name.
     if (SPECIAL_PERMISSION_KEYS.has(normalizedToolName)) {
-      const rule = evaluate("special", normalizedToolName, rules);
-      if (rules.includes(rule)) return rule.action;
-      return defaults.special;
+      return evaluate(normalizedToolName, "*", composedRules).action;
     }
 
-    // Bash and MCP have dedicated fallback overrides from tools.bash / tools.mcp.
-    if (normalizedToolName === "bash") return bashDefault;
-    if (normalizedToolName === "mcp") return mcpToolLevel ?? defaults.mcp;
-
-    // Skills use the skills default.
-    if (normalizedToolName === "skill") return defaults.skills;
+    // Bash, MCP, skill: evaluate with "*" value — the per-surface catch-all
+    // (or universal default) handles this correctly.
+    if (normalizedToolName === "bash") {
+      return evaluate("bash", "*", composedRules).action;
+    }
+    if (normalizedToolName === "mcp") {
+      return evaluate("mcp", "*", composedRules).action;
+    }
+    if (normalizedToolName === "skill") {
+      return evaluate("skill", "*", composedRules).action;
+    }
 
-    // Tool-name surfaces: check rules, fall back to tools default.
-    const rule = evaluate(normalizedToolName, "*", rules);
-    if (rules.includes(rule)) return rule.action;
-    return defaults.tools;
+    // Tool-name surfaces (read, write, etc. and extension tools).
+    return evaluate(normalizedToolName, "*", composedRules).action;
   }
 
   checkPermission(
     toolName: string,
     input: unknown,
     agentName?: string,
+    sessionRules?: Ruleset,
   ): PermissionCheckResult {
-    const { rules, defaults, bashDefault, mcpToolLevel, hasAnyMcpAllowRule } =
-      this.resolvePermissions(agentName);
+    const { composedRules } = this.resolvePermissions(agentName);
     const normalizedToolName = toolName.trim();
 
     // --- Special surfaces (external_directory) ---
     if (SPECIAL_PERMISSION_KEYS.has(normalizedToolName)) {
-      const rule = evaluate("special", normalizedToolName, rules);
-      const explicit = rules.includes(rule);
+      const record = toRecord(input);
+      const pathValue = typeof record.path === "string" ? record.path : null;
+
+      // Session check: match by specific normalized path.
+      if (pathValue && sessionRules && sessionRules.length > 0) {
+        const sessionRule = evaluate(
+          "external_directory",
+          pathValue,
+          sessionRules,
+        );
+        if (sessionRules.includes(sessionRule)) {
+          return {
+            toolName,
+            state: "allow",
+            matchedPattern: sessionRule.pattern,
+            source: "session",
+          };
+        }
+      }
+
+      // Config/default check.
+      const rule = evaluate(
+        normalizedToolName,
+        pathValue ?? "*",
+        composedRules,
+      );
       return {
         toolName,
-        state: explicit ? rule.action : defaults.special,
-        matchedPattern: explicit ? rule.pattern : undefined,
+        state: rule.action,
+        matchedPattern: rule.layer === "config" ? rule.pattern : undefined,
         source: "special",
       };
     }
@@ -727,19 +492,12 @@ export class PermissionManager {
     // --- Skills ---
     if (normalizedToolName === "skill") {
       const skillName = toRecord(input).name;
-      if (typeof skillName === "string") {
-        const rule = evaluate("skill", skillName, rules);
-        const explicit = rules.includes(rule);
-        return {
-          toolName,
-          state: explicit ? rule.action : defaults.skills,
-          matchedPattern: explicit ? rule.pattern : undefined,
-          source: explicit ? "skill" : "skill",
-        };
-      }
+      const lookupValue = typeof skillName === "string" ? skillName : "*";
+      const rule = evaluate("skill", lookupValue, composedRules);
       return {
         toolName,
-        state: defaults.skills,
+        state: rule.action,
+        matchedPattern: rule.layer === "config" ? rule.pattern : undefined,
         source: "skill",
       };
     }
@@ -748,13 +506,12 @@ export class PermissionManager {
     if (normalizedToolName === "bash") {
       const record = toRecord(input);
       const command = typeof record.command === "string" ? record.command : "";
-      const rule = evaluate("bash", command, rules);
-      const explicit = rules.includes(rule);
+      const rule = evaluate("bash", command, composedRules);
       return {
         toolName,
-        state: explicit ? rule.action : bashDefault,
+        state: rule.action,
         command,
-        matchedPattern: explicit ? rule.pattern : undefined,
+        matchedPattern: rule.layer === "config" ? rule.pattern : undefined,
         source: "bash",
       };
     }
@@ -770,67 +527,34 @@ export class PermissionManager {
       ];
       const fallbackTarget = mcpTargets[0] || "mcp";
 
-      // Try each candidate target against the merged rules.
+      // Try each candidate target. Stop on the first non-default match.
       for (const target of mcpTargets) {
-        const rule = evaluate("mcp", target, rules);
-        if (rules.includes(rule)) {
+        const rule = evaluate("mcp", target, composedRules);
+        if (rule.layer !== "default") {
           return {
             toolName,
             state: rule.action,
-            matchedPattern: rule.pattern,
+            matchedPattern: rule.layer === "config" ? rule.pattern : undefined,
             target,
-            source: "mcp",
-          };
-        }
-      }
-
-      // tools.mcp fallback (e.g. tools: { mcp: "allow" }).
-      if (mcpToolLevel) {
-        return {
-          toolName,
-          state: mcpToolLevel,
-          target: fallbackTarget,
-          source: "tool",
-        };
-      }
-
-      // Baseline auto-allow: if this is a metadata operation and at least one
-      // MCP rule allows something (or the default is allow), auto-allow.
-      const baselineTarget = mcpTargets.find((target) =>
-        MCP_BASELINE_TARGETS.has(target),
-      );
-      if (baselineTarget) {
-        if (hasAnyMcpAllowRule || defaults.mcp === "allow") {
-          return {
-            toolName,
-            state: "allow",
-            target: baselineTarget,
-            source: "mcp",
+            source: rule.layer === "override" ? "tool" : "mcp",
           };
         }
       }
 
+      // All targets matched only the synthesized default.
+      const defaultRule = evaluate("mcp", fallbackTarget, composedRules);
       return {
         toolName,
-        state: defaults.mcp,
+        state: defaultRule.action,
         target: fallbackTarget,
         source: "default",
       };
     }
 
     // --- Tools (read, write, edit, grep, find, ls, extension tools) ---
-    const rule = evaluate(normalizedToolName, "*", rules);
-    const explicit = rules.includes(rule);
+    const rule = evaluate(normalizedToolName, "*", composedRules);
 
     if (BUILT_IN_TOOL_PERMISSION_NAMES.has(normalizedToolName)) {
-      return {
-        toolName,
-        state: explicit ? rule.action : defaults.tools,
-        source: "tool",
-      };
-    }
-
-    if (explicit) {
       return {
         toolName,
         state: rule.action,
@@ -840,8 +564,162 @@ export class PermissionManager {
 
     return {
       toolName,
-      state: defaults.tools,
-      source: "default",
+      state: rule.action,
+      source: rule.layer === "default" ? "default" : "tool",
     };
   }
 }
+
+// ---------------------------------------------------------------------------
+// MCP target derivation helpers (unchanged)
+// ---------------------------------------------------------------------------
+
+function parseQualifiedMcpToolName(
+  value: string,
+): { server: string; tool: string } | null {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  const colonIndex = trimmed.indexOf(":");
+  if (colonIndex <= 0 || colonIndex >= trimmed.length - 1) {
+    return null;
+  }
+
+  const server = trimmed.slice(0, colonIndex).trim();
+  const tool = trimmed.slice(colonIndex + 1).trim();
+  if (!server || !tool) {
+    return null;
+  }
+
+  return { server, tool };
+}
+
+function addDerivedMcpServerTargets(
+  toolName: string,
+  configuredServerNames: readonly string[],
+  pushTarget: (value: string | null) => void,
+): void {
+  const trimmedToolName = toolName.trim();
+  if (!trimmedToolName) {
+    return;
+  }
+
+  for (const serverName of configuredServerNames) {
+    const trimmedServerName = serverName.trim();
+    if (!trimmedServerName) {
+      continue;
+    }
+
+    if (!trimmedToolName.endsWith(`_${trimmedServerName}`)) {
+      continue;
+    }
+
+    if (trimmedToolName.startsWith(`${trimmedServerName}_`)) {
+      continue;
+    }
+
+    pushTarget(`${trimmedServerName}_${trimmedToolName}`);
+    pushTarget(`${trimmedServerName}:${trimmedToolName}`);
+    pushTarget(trimmedServerName);
+  }
+}
+
+function pushMcpToolPermissionTargets(
+  rawReference: string,
+  serverHint: string | null,
+  configuredServerNames: readonly string[],
+  pushTarget: (value: string | null) => void,
+): void {
+  const qualified = parseQualifiedMcpToolName(rawReference);
+  const resolvedServer = serverHint ?? qualified?.server ?? null;
+  const resolvedTool = qualified?.tool ?? rawReference;
+
+  if (resolvedServer) {
+    pushTarget(`${resolvedServer}_${resolvedTool}`);
+    pushTarget(`${resolvedServer}:${resolvedTool}`);
+    pushTarget(resolvedServer);
+  } else {
+    addDerivedMcpServerTargets(resolvedTool, configuredServerNames, pushTarget);
+  }
+
+  pushTarget(resolvedTool);
+  pushTarget(rawReference);
+}
+
+function createMcpPermissionTargets(
+  input: unknown,
+  configuredServerNames: readonly string[] = [],
+): string[] {
+  const record = toRecord(input);
+  const tool = getNonEmptyString(record.tool);
+  const server = getNonEmptyString(record.server);
+  const connect = getNonEmptyString(record.connect);
+  const describe = getNonEmptyString(record.describe);
+  const search = getNonEmptyString(record.search);
+
+  const targets: string[] = [];
+  const pushTarget = (value: string | null) => {
+    if (!value) {
+      return;
+    }
+    if (!targets.includes(value)) {
+      targets.push(value);
+    }
+  };
+
+  if (tool) {
+    pushMcpToolPermissionTargets(
+      tool,
+      server,
+      configuredServerNames,
+      pushTarget,
+    );
+    pushTarget("mcp_call");
+    return targets;
+  }
+
+  if (connect) {
+    pushTarget(`mcp_connect_${connect}`);
+    pushTarget(connect);
+    pushTarget("mcp_connect");
+    return targets;
+  }
+
+  if (describe) {
+    pushMcpToolPermissionTargets(
+      describe,
+      server,
+      configuredServerNames,
+      pushTarget,
+    );
+    pushTarget("mcp_describe");
+    return targets;
+  }
+
+  if (search) {
+    if (server) {
+      pushTarget(`mcp_server_${server}`);
+      pushTarget(server);
+    }
+
+    pushTarget(search);
+    pushTarget("mcp_search");
+    return targets;
+  }
+
+  if (server) {
+    pushTarget(`mcp_server_${server}`);
+    pushTarget(server);
+    pushTarget("mcp_list");
+    return targets;
+  }
+
+  pushTarget("mcp_status");
+  return targets;
+}
+
+// Keep isPermissionState and toRecord available for convenience — they are
+// used directly in some handler files that import from permission-manager.
+export { isPermissionState, toRecord };