@moretea-labs/forge 1.7.2 → 1.8.1

package/adapters/mcp/tool-mapping/tools.ts

@@ -0,0 +1,9 @@
+/**
+ * Legacy Controller MCP compatibility facade.
+ *
+ * Gateway code imports the stable tool schema and result types from this
+ * module, while the compatibility implementation itself is isolated in
+ * legacy-tool-service.ts and is invoked for long work only by Worker
+ * processes through the durable ExecutionJob pipeline.
+ */
+export * from './legacy-tool-service';

package/adapters/mcp/tool-mapping/umbrella-tools.ts

@@ -0,0 +1,117 @@
+import { createUmbrellaIssue, getUmbrellaIssue, listUmbrellaIssues, updateUmbrellaTask } from '../../../src/cli/repositories/umbrella';
+import type { McpToolDefinition } from './tools';
+import type { RepositoryToolResult } from './repository-tools';
+
+export const umbrellaToolDefinitions: McpToolDefinition[] = [
+  {
+    name: 'umbrella_list',
+    description: 'List cross-repository umbrella work items.',
+    inputSchema: { type: 'object', additionalProperties: false },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+  {
+    name: 'umbrella_get',
+    description: 'Inspect one cross-repository umbrella work item.',
+    inputSchema: {
+      type: 'object',
+      properties: { umbrella_id: { type: 'string' } },
+      required: ['umbrella_id'],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+  {
+    name: 'umbrella_create',
+    description: 'Create an umbrella work item whose executable tasks each belong to exactly one repository.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        umbrella_id: { type: 'string' },
+        title: { type: 'string' },
+        summary: { type: 'string' },
+        tasks: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              repo_id: { type: 'string' },
+              task_id: { type: 'string' },
+              issue_id: { type: 'string' },
+              title: { type: 'string' },
+            },
+            required: ['repo_id', 'task_id', 'title'],
+            additionalProperties: false,
+          },
+        },
+      },
+      required: ['umbrella_id', 'title', 'tasks'],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+  },
+  {
+    name: 'umbrella_update_task',
+    description: 'Record a repository-local task outcome without claiming cross-repository atomic success.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        umbrella_id: { type: 'string' },
+        repo_id: { type: 'string' },
+        task_id: { type: 'string' },
+        status: { type: 'string', enum: ['planned', 'running', 'succeeded', 'failed', 'blocked', 'cancelled'] },
+        run_id: { type: 'string' },
+        commit_sha: { type: 'string' },
+        rollback_ref: { type: 'string' },
+        error: { type: 'string' },
+      },
+      required: ['umbrella_id', 'repo_id', 'task_id', 'status'],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+  },
+];
+
+function result(value: Record<string, unknown>): RepositoryToolResult {
+  return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }], structuredContent: value };
+}
+
+export function callUmbrellaTool(controllerHome: string, name: string, args: Record<string, unknown>): RepositoryToolResult | undefined {
+  if (!name.startsWith('umbrella_')) return undefined;
+  try {
+    if (name === 'umbrella_list') return result({ umbrellaIssues: listUmbrellaIssues(controllerHome) });
+    if (name === 'umbrella_get') return result({ umbrellaIssue: getUmbrellaIssue(String(args.umbrella_id ?? ''), controllerHome) });
+    if (name === 'umbrella_create') {
+      const tasks = Array.isArray(args.tasks) ? args.tasks.map((value) => {
+        const task = value as Record<string, unknown>;
+        return {
+          repoId: String(task.repo_id ?? ''),
+          taskId: String(task.task_id ?? ''),
+          issueId: typeof task.issue_id === 'string' ? task.issue_id : undefined,
+          title: String(task.title ?? ''),
+        };
+      }) : [];
+      return result({ umbrellaIssue: createUmbrellaIssue({
+        controllerHome,
+        umbrellaId: String(args.umbrella_id ?? ''),
+        title: String(args.title ?? ''),
+        summary: typeof args.summary === 'string' ? args.summary : undefined,
+        tasks,
+      }) });
+    }
+    if (name === 'umbrella_update_task') return result({ umbrellaIssue: updateUmbrellaTask({
+      controllerHome,
+      umbrellaId: String(args.umbrella_id ?? ''),
+      repoId: String(args.repo_id ?? ''),
+      taskId: String(args.task_id ?? ''),
+      status: String(args.status ?? '') as 'planned' | 'running' | 'succeeded' | 'failed' | 'blocked' | 'cancelled',
+      runId: typeof args.run_id === 'string' ? args.run_id : undefined,
+      commitSha: typeof args.commit_sha === 'string' ? args.commit_sha : undefined,
+      rollbackRef: typeof args.rollback_ref === 'string' ? args.rollback_ref : undefined,
+      error: typeof args.error === 'string' ? args.error : undefined,
+    }) });
+    return undefined;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { ...result({ error: { code: 'UMBRELLA_TOOL_FAILED', message } }), isError: true };
+  }
+}

package/adapters/mcp/toolset-names.ts

@@ -0,0 +1,79 @@
+import { FACADE_TOOLS } from '../../src/runtime/control-plane/facade/types';
+
+/** Preferred ChatGPT-facing facade tools. Must stay small and stable. */
+export const PREFERRED_FACADE_TOOL_NAMES = [...FACADE_TOOLS] as const;
+
+/**
+ * Default ChatGPT-facing MCP surface. The Runtime keeps every internal atomic
+ * handler and the full compatibility profile; ChatGPT only needs this bounded
+ * execution surface. Atomic Git / issue-task / edit-session / plugin
+ * tools remain registered and reachable through `toolset=full`.
+ */
+export const DEFAULT_CONTROLLER_TOOL_NAMES = [
+  ...PREFERRED_FACADE_TOOL_NAMES,
+
+  // Repository selection / bootstrap.
+  'repository_list',
+  'repository_get',
+  'repository_register',
+
+  // Generic repository-scoped command (readonly fast path, mutation, destructive gate).
+  'repository_command_execute',
+
+  // Source inspection and bounded Direct Edit. Code location is routed through
+  // rh_context.search; the low-level search_repository handler remains in full.
+  'read_repository_file',
+  'repository_safe_patch_apply',
+
+  // Focused checks through Process Runtime.
+  'run_check',
+
+  // Protected Computer preparation/input use typed direct-non-persistent actions
+  // behind the stable plugin dispatcher. Their full-profile atomic tools remain
+  // registered only for compatibility clients and are not part of this frozen ABI.
+
+  // One typed plugin dispatcher. Plugin discovery/action schemas stay routed
+  // through rh_context(capability_id=plugin.<plugin>.<action>) to avoid widening
+  // the default surface with list/get plugin atomics.
+  'plugin_action_execute',
+
+  // Managed Process Runtime lifecycle (attach / poll / cancel — never re-exec).
+  // process_exec is the canonical host-local command lane: the Forge instance is
+  // the target, cwd is an execution argument, and it is authorized by one
+  // explicit `process:exec` canonical Grant. repository_command_execute stays as
+  // translation-only compatibility over the repository target.
+  'process_exec',
+  'process_get',
+  'process_wait',
+  'process_logs',
+  'process_cancel',
+
+  // Evidence. Approval resolution is available through rh_access/rh_work and
+  // the explicit full compatibility profile; it does not need a top-level
+  // default tool.
+  'result_read',
+  'result_search',
+] as const;
+
+/** Minimal bootstrap subset retained for diagnostics and constrained clients. */
+export const BOOTSTRAP_CONTROLLER_TOOL_NAMES = [
+  ...PREFERRED_FACADE_TOOL_NAMES,
+  'repository_access_get',
+  'repository_list',
+  'repository_get',
+  'repository_register',
+  'repository_latest_source_diagnose',
+  'repository_bootstrap_local_project',
+] as const;
+
+/**
+ * Stable ChatGPT connector schema. Keep this identical to the bounded default
+ * Runtime surface so discovery never advertises atomic tools that the default
+ * Forge build will reject. The exhaustive `full` profile is assembled directly
+ * from registered definitions and remains available for explicit compatibility
+ * clients without widening the normal connector schema.
+ */
+export const STABLE_CONTROLLER_TOOL_NAMES = DEFAULT_CONTROLLER_TOOL_NAMES;
+
+/** Core is a compatibility label for the bounded default Controller surface. */
+export const CORE_CONTROLLER_TOOL_NAMES = DEFAULT_CONTROLLER_TOOL_NAMES;

package/adapters/mcp/toolset-selection.ts

@@ -0,0 +1,41 @@
+import type { McpLocalConfig } from './auth';
+import type { McpToolset } from './types';
+
+export interface ControllerToolsetSelection {
+  toolset: McpToolset;
+  locked: boolean;
+  migratedLegacyAdvanced: boolean;
+}
+
+export function normalizeConfiguredMcpToolset(value: unknown): McpToolset | undefined {
+  return value === 'facade' || value === 'core' || value === 'advanced' || value === 'full' ? value : undefined;
+}
+
+/** Persisted Core and Advanced are compatibility-equivalent stable profiles. */
+export function configuredControllerToolset(config: McpLocalConfig | null | undefined): McpToolset | undefined {
+  return normalizeConfiguredMcpToolset(config?.toolset);
+}
+
+export function resolveControllerToolsetSelection(
+  config: McpLocalConfig | null | undefined,
+  override?: unknown,
+): ControllerToolsetSelection {
+  const explicitOverride = normalizeConfiguredMcpToolset(override);
+  const configured = configuredControllerToolset(config);
+  return {
+    toolset: explicitOverride ?? configured ?? 'advanced',
+    locked: explicitOverride !== undefined || configured !== undefined,
+    migratedLegacyAdvanced: false,
+  };
+}
+
+export function migrateControllerToolsetConfig(config: McpLocalConfig | null | undefined): {
+  toolset: McpToolset;
+  toolsetExplicit: boolean;
+} {
+  const configured = configuredControllerToolset(config);
+  return {
+    toolset: configured ?? 'advanced',
+    toolsetExplicit: configured !== undefined,
+  };
+}

package/adapters/mcp/toolset.ts

@@ -0,0 +1,337 @@
+import type { McpToolDefinition } from '../../packages/protocols/mcp/tool-contract';
+import type { MultiRepositoryMcpToolContext } from './multi-repository';
+import { buildMultiRepositoryToolDefinitions } from './multi-repository';
+import { accessToolDefinitions } from './tool-mapping/access-tools';
+import {
+  resolveControllerAccessState,
+  type ControllerAccessState,
+} from './access-mode';
+import { repositoryToolDefinitions } from './tool-mapping/repository-tools';
+import { runtimeToolDefinitions } from './runtime-gateway/runtime-tool-definitions';
+import { executionToolDefinitions } from './runtime-gateway/execution-tools';
+import { processToolDefinitions } from './runtime-gateway/process-tools';
+import { injectDurableCommandFields } from './runtime-gateway/router';
+import { injectAutomationEnvelopeFields } from './runtime-gateway/automation-receipt-adapter';
+import { injectCognitionSettlementFields } from './runtime-gateway/cognition-settlement';
+import { DEFAULT_CONTROLLER_TOOL_NAMES, PREFERRED_FACADE_TOOL_NAMES, STABLE_CONTROLLER_TOOL_NAMES } from './toolset-names';
+export { BOOTSTRAP_CONTROLLER_TOOL_NAMES, CORE_CONTROLLER_TOOL_NAMES, DEFAULT_CONTROLLER_TOOL_NAMES, PREFERRED_FACADE_TOOL_NAMES, STABLE_CONTROLLER_TOOL_NAMES } from './toolset-names';
+import type { McpToolset } from './types';
+import { forgeToolSurfaceFingerprint } from '../../src/cli/controller/runtime-config';
+
+export type ToolExposureClass = 'facade' | 'advanced' | 'internal' | 'compatibility';
+export type ControllerToolProfile = 'facade' | 'core' | 'advanced' | 'full';
+
+export interface ControllerToolInventoryEntry {
+  name: string;
+  profile: ControllerToolProfile;
+  capability: string;
+  exposedVia: 'facade' | 'core' | 'advanced' | 'full';
+}
+
+/**
+ * One authoritative snapshot of the MCP schema actually served to a client.
+ * Access mode intentionally does not alter this schema: Request vs Full Access
+ * is an execution-policy decision, not a tool-discovery decision.
+ */
+export interface ControllerExposureSnapshot {
+  access: ControllerAccessState;
+  toolset: McpToolset;
+  profile: ControllerToolProfile;
+  definitions: McpToolDefinition[];
+  toolNames: string[];
+  expectedToolNames: string[];
+  actualToolNames: string[];
+  missingToolNames: string[];
+  unexpectedToolNames: string[];
+  duplicateToolNames: string[];
+  fingerprint: string;
+  inventory: ControllerToolInventoryEntry[];
+  schemaStableAcrossAccessModes: true;
+  ready: boolean;
+}
+
+/**
+ * Cached schema/readiness projection for hot paths that do not need access
+ * policy or a per-tool inventory. Status uses this rather than rebuilding a
+ * complete controller exposure response on every read.
+ */
+export interface ControllerToolSurfaceStatus {
+  expectedToolNames: string[];
+  actualToolNames: string[];
+  missingToolNames: string[];
+  unexpectedToolNames: string[];
+  duplicateToolNames: string[];
+  fingerprint: string;
+  schemaStableAcrossAccessModes: true;
+  ready: boolean;
+}
+
+/**
+ * Core and Advanced expose the same bounded default ChatGPT surface
+ * (DEFAULT_CONTROLLER_TOOL_NAMES). Full remains the exhaustive compatibility
+ * surface for legacy integrations; internal atomic handlers are never deleted.
+ */
+
+/** Historical Advanced name retained for compatibility. */
+export const ADVANCED_CONTROLLER_TOOL_NAMES = DEFAULT_CONTROLLER_TOOL_NAMES;
+
+const DEFAULT_CONTROLLER_TOOL_SET = new Set<string>(DEFAULT_CONTROLLER_TOOL_NAMES);
+
+interface StaticControllerExposureSnapshot {
+  definitions: McpToolDefinition[];
+  toolNames: string[];
+  expectedToolNames: string[];
+  actualToolNames: string[];
+  missingToolNames: string[];
+  unexpectedToolNames: string[];
+  duplicateToolNames: string[];
+  fingerprint: string;
+  schemaStableAcrossAccessModes: true;
+  ready: boolean;
+}
+
+const STATIC_EXPOSURE_CACHE_MAX_ENTRIES = 64;
+const staticControllerExposureCache = new Map<string, StaticControllerExposureSnapshot>();
+
+function pruneStaticExposureCache(): void {
+  while (staticControllerExposureCache.size > STATIC_EXPOSURE_CACHE_MAX_ENTRIES) {
+    const oldest = staticControllerExposureCache.keys().next().value as string | undefined;
+    if (!oldest) break;
+    staticControllerExposureCache.delete(oldest);
+  }
+}
+
+export function normalizeMcpToolset(value: unknown): McpToolset {
+  if (value === 'full' || value === 'advanced' || value === 'core' || value === 'facade') return value;
+  return 'advanced';
+}
+
+/**
+ * null means expose every registered definition. Profile membership only
+ * changes schema discovery; authorization remains an independent policy.
+ */
+export function controllerToolNamesForToolset(
+  toolset: McpToolset,
+  _ctx?: MultiRepositoryMcpToolContext,
+): readonly string[] | null {
+  if (toolset === 'full') return null;
+  if (toolset === 'facade') return PREFERRED_FACADE_TOOL_NAMES;
+  return DEFAULT_CONTROLLER_TOOL_NAMES;
+}
+
+export function resolveControllerAccessStateForContext(
+  ctx: MultiRepositoryMcpToolContext,
+): ControllerAccessState {
+  return resolveControllerAccessState({
+    controllerHome: ctx.controllerHome,
+    repoRoot: ctx.explicitRepository?.canonicalRoot,
+    toolsetOverride: ctx.toolset,
+    toolsetLocked: ctx.toolsetLocked ?? false,
+  });
+}
+
+function uniqueDefinitions(definitions: McpToolDefinition[]): {
+  definitions: McpToolDefinition[];
+  duplicates: string[];
+} {
+  const byName = new Map<string, McpToolDefinition>();
+  const duplicates = new Set<string>();
+  for (const definition of definitions) {
+    if (byName.has(definition.name)) {
+      duplicates.add(definition.name);
+      continue;
+    }
+    byName.set(definition.name, definition);
+  }
+  const preferredOrder = new Map<string, number>(
+    (PREFERRED_FACADE_TOOL_NAMES as readonly string[]).map((name, index) => [name, index]),
+  );
+  const orderedDefinitions = [...byName.values()].sort((left, right) => {
+    const leftOrder = preferredOrder.get(left.name);
+    const rightOrder = preferredOrder.get(right.name);
+    if (leftOrder !== undefined || rightOrder !== undefined) {
+      if (leftOrder === undefined) return 1;
+      if (rightOrder === undefined) return -1;
+      return leftOrder - rightOrder;
+    }
+    return 0;
+  });
+  return { definitions: orderedDefinitions, duplicates: [...duplicates].sort() };
+}
+
+function staticExposureCacheKey(ctx: MultiRepositoryMcpToolContext): string {
+  return JSON.stringify({
+    controllerHome: ctx.controllerHome,
+    repoRoot: ctx.repoRoot,
+    explicitRepositoryId: ctx.explicitRepository?.repoId,
+    toolset: ctx.toolset,
+    profile: ctx.policy.profile,
+    enableChatgptBrowser: ctx.enableChatgptBrowser === true,
+    devAgentRunner: ctx.policy.execution.agentRunner,
+    allowedAgents: [...ctx.policy.execution.allowedAgents].sort(),
+    runnerTimeoutMs: ctx.policy.execution.runnerTimeoutMs,
+    runnerMaxTimeoutMs: ctx.policy.execution.runnerMaxTimeoutMs,
+  });
+}
+
+function buildStaticControllerExposureSnapshot(
+  ctx: MultiRepositoryMcpToolContext,
+): StaticControllerExposureSnapshot {
+  const currentDefinitions = runtimeToolDefinitions.concat(
+    executionToolDefinitions,
+    processToolDefinitions,
+    accessToolDefinitions,
+    repositoryToolDefinitions,
+  );
+  const rawDefinitions = ctx.toolset === 'full'
+    ? currentDefinitions.concat(
+      buildMultiRepositoryToolDefinitions(ctx).filter(
+        (legacy) => !currentDefinitions.some((current) => current.name === legacy.name),
+      ),
+    )
+    : currentDefinitions;
+  const unique = uniqueDefinitions(rawDefinitions);
+  const allowed = controllerToolNamesForToolset(ctx.toolset, ctx);
+  const expectedToolNames = allowed === null
+    ? unique.definitions.map((tool) => tool.name)
+    : [...new Set(allowed)];
+  const definitionByName = new Map(unique.definitions.map((definition) => [definition.name, definition]));
+  const definitions = expectedToolNames
+    .map((name) => definitionByName.get(name))
+    .filter((definition): definition is McpToolDefinition => Boolean(definition))
+    // Fingerprint the exact definitions that ListTools returns. Shared transport
+    // contracts are injected here once rather than re-declared by domain registries.
+    .map((definition) => injectCognitionSettlementFields(injectAutomationEnvelopeFields(injectDurableCommandFields(definition))));
+  const actualToolNames = definitions.map((tool) => tool.name);
+  const actualSet = new Set(actualToolNames);
+  const expectedSet = new Set(expectedToolNames);
+  const missingToolNames = expectedToolNames.filter((name) => !actualSet.has(name));
+  const unexpectedToolNames = actualToolNames.filter((name) => !expectedSet.has(name));
+  const fingerprint = forgeToolSurfaceFingerprint(definitions);
+  return {
+    definitions,
+    toolNames: actualToolNames,
+    expectedToolNames,
+    actualToolNames,
+    missingToolNames,
+    unexpectedToolNames,
+    duplicateToolNames: unique.duplicates,
+    fingerprint,
+    schemaStableAcrossAccessModes: true,
+    ready: missingToolNames.length === 0 && unexpectedToolNames.length === 0 && unique.duplicates.length === 0,
+  };
+}
+
+function staticControllerExposureSnapshot(
+  ctx: MultiRepositoryMcpToolContext,
+): StaticControllerExposureSnapshot {
+  const key = staticExposureCacheKey(ctx);
+  const cached = staticControllerExposureCache.get(key);
+  if (cached) return cached;
+  const built = buildStaticControllerExposureSnapshot(ctx);
+  staticControllerExposureCache.set(key, built);
+  pruneStaticExposureCache();
+  return built;
+}
+
+function capabilityForToolName(name: string): string {
+  if (name.startsWith('rh_')) return 'facade';
+  if (name.startsWith('git_') || name.startsWith('repository_git_')) return 'git';
+  if (/(^|_)(issue|task|project|worklog)(_|$)/.test(name)) return 'issue-task';
+  if (name.startsWith('repository_') || name.startsWith('search_') || name.startsWith('read_')) return 'repository';
+  if (name.startsWith('ios_')) return 'ios';
+  if (name.startsWith('web_')) return 'browser';
+  if (name.includes('plugin')) return 'plugin';
+  if (name.startsWith('result_') || name.includes('artifact') || name.includes('evidence')) return 'evidence';
+  if (name.includes('controller_')) return 'controller';
+  if (name.startsWith('process_') || name.startsWith('schedule_') || name.startsWith('runtime_') || name.startsWith('maintenance_')) return 'runtime-maintenance';
+  if (name.startsWith('work_') || name.startsWith('session_')) return 'workflow';
+  return 'compatibility';
+}
+
+function profileForToolset(toolset: McpToolset): ControllerToolProfile {
+  return toolset === 'full' ? 'full' : toolset === 'facade' ? 'facade' : toolset === 'core' ? 'core' : 'advanced';
+}
+
+export function controllerToolInventory(
+  toolNames: readonly string[],
+  toolset: McpToolset,
+): ControllerToolInventoryEntry[] {
+  const profile = profileForToolset(toolset);
+  return toolNames.map((name) => ({
+    name,
+    profile,
+    capability: capabilityForToolName(name),
+    exposedVia: name.startsWith('rh_') ? 'facade' : profile,
+  }));
+}
+
+export function clearControllerExposureCacheForTest(): void {
+  staticControllerExposureCache.clear();
+}
+
+export function allControllerToolDefinitions(ctx: MultiRepositoryMcpToolContext): McpToolDefinition[] {
+  return uniqueDefinitions(
+    runtimeToolDefinitions.concat(executionToolDefinitions, processToolDefinitions, accessToolDefinitions, repositoryToolDefinitions, buildMultiRepositoryToolDefinitions(ctx)),
+  ).definitions.map((definition) => injectCognitionSettlementFields(injectAutomationEnvelopeFields(injectDurableCommandFields(definition))));
+}
+
+export function controllerExposureSnapshot(ctx: MultiRepositoryMcpToolContext): ControllerExposureSnapshot {
+  const staticSnapshot = staticControllerExposureSnapshot(ctx);
+  return {
+    access: resolveControllerAccessStateForContext(ctx),
+    toolset: ctx.toolset,
+    profile: profileForToolset(ctx.toolset),
+    inventory: controllerToolInventory(staticSnapshot.actualToolNames, ctx.toolset),
+    ...staticSnapshot,
+  };
+}
+
+export function controllerToolSurfaceStatus(ctx: MultiRepositoryMcpToolContext): ControllerToolSurfaceStatus {
+  const snapshot = staticControllerExposureSnapshot(ctx);
+  return {
+    expectedToolNames: snapshot.expectedToolNames,
+    actualToolNames: snapshot.actualToolNames,
+    missingToolNames: snapshot.missingToolNames,
+    unexpectedToolNames: snapshot.unexpectedToolNames,
+    duplicateToolNames: snapshot.duplicateToolNames,
+    fingerprint: snapshot.fingerprint,
+    schemaStableAcrossAccessModes: snapshot.schemaStableAcrossAccessModes,
+    ready: snapshot.ready,
+  };
+}
+
+export function controllerExposedToolNames(ctx: MultiRepositoryMcpToolContext): string[] {
+  return controllerExposureSnapshot(ctx).actualToolNames;
+}
+
+export function classifyControllerToolExposure(toolName: string): ToolExposureClass {
+  if ((PREFERRED_FACADE_TOOL_NAMES as readonly string[]).includes(toolName)) return 'facade';
+  if (toolName.startsWith('rh_')) return 'facade';
+  if (DEFAULT_CONTROLLER_TOOL_SET.has(toolName)) return 'advanced';
+  return 'compatibility';
+}
+
+export function controllerToolExposureMetadata(toolNames: readonly string[]): {
+  preferredTools: string[];
+  advancedTools: string[];
+  compatibilityTools: string[];
+  classification: Record<string, ToolExposureClass>;
+} {
+  const classification: Record<string, ToolExposureClass> = {};
+  for (const name of toolNames) classification[name] = classifyControllerToolExposure(name);
+  return {
+    preferredTools: toolNames.filter((name) => classification[name] === 'facade'),
+    advancedTools: toolNames.filter((name) => classification[name] === 'advanced'),
+    compatibilityTools: toolNames.filter((name) => classification[name] === 'compatibility'),
+    classification,
+  };
+}
+
+export function exposedControllerToolDefinitions(ctx: MultiRepositoryMcpToolContext): McpToolDefinition[] {
+  return controllerExposureSnapshot(ctx).definitions;
+}
+
+export function isControllerToolExposed(ctx: MultiRepositoryMcpToolContext, name: string): boolean {
+  return controllerExposureSnapshot(ctx).actualToolNames.includes(name);
+}