@link-assistant/hive-mind 2.9.1 → 2.10.0

package/src/isolation-runner.lib.mjs

@@ -15,6 +15,7 @@ import { ensureUseM } from './use-m-bootstrap.lib.mjs';
 
 import crypto from 'crypto';
 import { spawn } from 'node:child_process';
+import { lookup as lookupHost } from 'node:dns/promises';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -53,6 +54,7 @@ const HIVE_MIND_IMAGE_REPO = 'konard/hive-mind';
 const HIVE_MIND_DIND_IMAGE_REPO = 'konard/hive-mind-dind';
 const DEFAULT_HIVE_MIND_IMAGE_TAG = 'latest';
 const DOCKER_CONTAINER_HOME = '/home/box';
+const FORMAL_AI_COMPOSE_HOSTNAME = 'link-assistant-formal-ai';
 // Default path where the host Docker socket is bind-mounted inside a DinD
 // container so box's host-image passthrough can copy host images into the
 // nested daemon. Matches box's own DIND_HOST_DOCKER_SOCK default. The deploy
@@ -227,6 +229,44 @@ function resolveImageVariant(image, env = process.env) {
   return image.includes('hive-mind-dind') ? 'dind' : env.HIVE_MIND_IMAGE_VARIANT || 'regular';
 }
 
+/**
+ * Resolve an outer Compose HTTP service before handing its origin to a nested
+ * Docker daemon. The nested daemon has its own DNS namespace, but it can route
+ * to the outer service's address through the parent container.
+ *
+ * HTTPS names are deliberately preserved for certificate verification.
+ */
+export async function resolveFormalAiIsolationEnv(env = process.env, { lookup = lookupHost } = {}) {
+  const baseUrl = env.HIVE_MIND_FORMAL_AI_BASE_URL;
+  if (!baseUrl) return env;
+
+  let parsed;
+  try {
+    parsed = new URL(baseUrl);
+  } catch {
+    return env;
+  }
+
+  if (parsed.protocol !== 'http:' || parsed.hostname !== FORMAL_AI_COMPOSE_HOSTNAME) {
+    return env;
+  }
+
+  try {
+    const addresses = await lookup(parsed.hostname, { all: true, verbatim: true });
+    const selected = addresses.find(candidate => candidate.family === 4) || addresses[0];
+    if (!selected?.address) return env;
+
+    const host = selected.family === 6 ? `[${selected.address}]` : selected.address;
+    return {
+      ...env,
+      HIVE_MIND_FORMAL_AI_BASE_URL: `${parsed.protocol}//${host}${parsed.port ? `:${parsed.port}` : ''}`,
+    };
+  } catch {
+    // Keep the hostname for deployments whose nested DNS can resolve it.
+    return env;
+  }
+}
+
 /**
  * Build the `$` (start-command) arguments that launch a Docker-isolated task
  * using start-command's NATIVE Docker backend (`$ --isolated docker`).
@@ -264,6 +304,13 @@ export function buildDockerIsolationStartArgs(command, args = [], options = {})
   // working directory comes from the image's WORKDIR.
   startArgs.push('-e', `HOME=${DOCKER_CONTAINER_HOME}`, '-e', `HIVE_MIND_PARENT_SESSION_ID=${sessionId || ''}`, '-e', `HIVE_MIND_IMAGE_VARIANT=${resolveImageVariant(image, env)}`);
 
+  // A persistent Formal AI server normally runs beside the Telegram/root
+  // container. Docker-isolated `/solve` jobs must receive the same endpoint;
+  // otherwise the wrapper starts a per-job server and loses shared memory.
+  if (env.HIVE_MIND_FORMAL_AI_BASE_URL) {
+    startArgs.push('-e', `HIVE_MIND_FORMAL_AI_BASE_URL=${env.HIVE_MIND_FORMAL_AI_BASE_URL}`);
+  }
+
   for (const mount of getDockerIsolationAuthMounts({ tool, env, homeDir, existsSync })) {
     startArgs.push('--volume', `${mount.source}:${mount.target}`);
   }
@@ -620,14 +667,21 @@ export async function executeWithIsolation(command, args, options = {}) {
     console.log(`[VERBOSE] isolation-runner: Backend: ${backend}, Session ID: ${sessionId}`);
   }
 
-  const startCommandArgs = buildStartCommandArgs(command, args, { ...options, sessionId });
+  const effectiveOptions =
+    backend === 'docker'
+      ? {
+          ...options,
+          env: await resolveFormalAiIsolationEnv(options.env || process.env),
+        }
+      : options;
+  const startCommandArgs = buildStartCommandArgs(command, args, { ...effectiveOptions, sessionId });
 
   if (verbose) {
     console.log(`[VERBOSE] isolation-runner: ${[binPath, ...startCommandArgs].map(shellQuote).join(' ')}`);
     if (backend === 'docker') {
-      const env = options.env || process.env;
+      const env = effectiveOptions.env || process.env;
       const image = getDockerIsolationImage({ env });
-      const mounts = getDockerIsolationAuthMounts({ tool: options.tool, env, homeDir: options.homeDir || os.homedir(), existsSync: options.existsSync || fs.existsSync });
+      const mounts = getDockerIsolationAuthMounts({ tool: effectiveOptions.tool, env, homeDir: effectiveOptions.homeDir || os.homedir(), existsSync: effectiveOptions.existsSync || fs.existsSync });
       console.log('[VERBOSE] isolation-runner: Docker isolation backend: native ($ --isolated docker)');
       console.log(`[VERBOSE] isolation-runner: Docker isolation image: ${image}`);
       console.log(`[VERBOSE] isolation-runner: Docker isolation privileged: ${shouldRunPrivilegedDockerIsolation(image, env)}`);

package/src/models/index.mjs

@@ -28,10 +28,26 @@ const execFileAsync = promisify(execFile);
 
 // ─── MODEL DATA ──────────────────────────────────────────────────────────────
 
+export const FORMAL_AI_MODEL_ALIAS = 'formal-ai';
+export const FORMAL_AI_PROVIDER_MODEL_ID = 'formalai/formal-ai';
+
+const formalAiNativeModelAliases = {
+  [FORMAL_AI_MODEL_ALIAS]: FORMAL_AI_MODEL_ALIAS,
+  [FORMAL_AI_PROVIDER_MODEL_ID]: FORMAL_AI_MODEL_ALIAS,
+};
+
+const formalAiProviderModelAliases = {
+  [FORMAL_AI_MODEL_ALIAS]: FORMAL_AI_PROVIDER_MODEL_ID,
+  [FORMAL_AI_PROVIDER_MODEL_ID]: FORMAL_AI_PROVIDER_MODEL_ID,
+};
+
+export const isFormalAiModel = model => model === FORMAL_AI_MODEL_ALIAS || model === FORMAL_AI_PROVIDER_MODEL_ID;
+
 // Claude models (Anthropic API)
 // Updated for Opus 4.5/4.6/4.7/4.8/5, Sonnet 4.6/5, and Fable 5 / Mythos 5 support
 // (Issue #1221, Issue #1238, Issue #1329, Issue #1433, Issue #1620, Issue #1832, Issue #1875, Issue #2003, Issue #2096)
 export const claudeModels = {
+  ...formalAiNativeModelAliases,
   sonnet: 'claude-sonnet-5', // Sonnet 5 (Issue #2003)
   opus: 'claude-opus-5', // Opus 5 (default, Issue #2096)
   haiku: 'claude-haiku-4-5-20251001', // Haiku 4.5
@@ -72,6 +88,7 @@ export const claudeModels = {
 // Issue #1543: Added qwen3.6-plus-free (former default) and nemotron-3-super-free per agent PR #234
 // Issue #1563: qwen3.6-plus-free free promotion ended (April 2026), nemotron-3-super-free is now default per agent PR #243
 export const agentModels = {
+  ...formalAiProviderModelAliases,
   // OpenCode Zen free models (current)
   grok: 'opencode/grok-code',
   'grok-code': 'opencode/grok-code',
@@ -111,6 +128,7 @@ export const agentModels = {
 
 // OpenCode models (OpenCode API)
 export const opencodeModels = {
+  ...formalAiProviderModelAliases,
   gpt4: 'openai/gpt-4',
   gpt4o: 'openai/gpt-4o',
   claude: 'anthropic/claude-3-5-sonnet',
@@ -124,6 +142,7 @@ export const opencodeModels = {
 
 // Codex models (OpenAI API)
 export const codexModels = {
+  ...formalAiNativeModelAliases,
   gpt5: 'gpt-5',
   'gpt-5': 'gpt-5',
   'gpt-5.5': 'gpt-5.5',
@@ -196,6 +215,7 @@ export const CODEX_MODEL_VARIANTS = getCodexModelVariants();
 
 // Qwen Code models
 export const qwenModels = {
+  ...formalAiNativeModelAliases,
   qwen: 'qwen3-coder-plus',
   'qwen-coder': 'qwen3-coder-plus',
   qwen3: 'qwen3-coder-plus',
@@ -210,6 +230,7 @@ export const qwenModels = {
 // Keep aliases aligned with the Gemini CLI model aliases documented in
 // docs/cli/cli-reference.md: auto, pro, flash, and flash-lite.
 export const geminiModels = {
+  ...formalAiNativeModelAliases,
   auto: 'auto',
   gemini: 'gemini-2.5-flash',
   flash: 'gemini-2.5-flash',
@@ -492,6 +513,10 @@ export const mapModelForTool = (tool, model) => {
  * @returns {boolean} True if the model is compatible with the tool
  */
 export const isModelCompatibleWithTool = (tool, model) => {
+  if (isFormalAiModel(model)) {
+    return ['claude', 'agent', 'opencode', 'codex', 'qwen', 'gemini'].includes(tool);
+  }
+
   const mappedModel = mapModelForTool(tool, model);
 
   switch (tool) {
@@ -539,12 +564,12 @@ export const getValidModelsForTool = tool => {
 // Primary (non-alias, non-deprecated) short names shown in CLI help descriptions
 // These are the recommended model names users should see in --model help text
 export const primaryModelNames = {
-  claude: ['opus', 'sonnet', 'haiku', 'opusplan', 'fable'],
-  opencode: ['grok', 'gpt4o'],
-  codex: ['gpt-5.6-sol', 'gpt-5.5', 'gpt-5.6-terra', 'gpt-5.6-luna', 'gpt-5.4', 'gpt-5.4-mini', 'gpt-5.3-codex-spark'],
-  agent: ['nemotron-3-super-free', 'minimax-m2.5-free', 'big-pickle', 'gpt-5-nano', 'glm-5-free', 'deepseek-r1-free'],
-  qwen: ['qwen3-coder-plus', 'qwen3-coder', 'qwen3-coder-flash'],
-  gemini: ['flash', 'pro', 'flash-lite', 'auto'],
+  claude: ['opus', 'sonnet', 'haiku', 'opusplan', 'fable', FORMAL_AI_MODEL_ALIAS],
+  opencode: ['grok', 'gpt4o', FORMAL_AI_MODEL_ALIAS],
+  codex: ['gpt-5.6-sol', 'gpt-5.5', 'gpt-5.6-terra', 'gpt-5.6-luna', 'gpt-5.4', 'gpt-5.4-mini', 'gpt-5.3-codex-spark', FORMAL_AI_MODEL_ALIAS],
+  agent: ['nemotron-3-super-free', 'minimax-m2.5-free', 'big-pickle', 'gpt-5-nano', 'glm-5-free', 'deepseek-r1-free', FORMAL_AI_MODEL_ALIAS],
+  qwen: ['qwen3-coder-plus', 'qwen3-coder', 'qwen3-coder-flash', FORMAL_AI_MODEL_ALIAS],
+  gemini: ['flash', 'pro', 'flash-lite', 'auto', FORMAL_AI_MODEL_ALIAS],
 };
 
 /**

package/src/opencode.lib.mjs

@@ -20,6 +20,7 @@ import { timeouts, retryLimits } from './config.lib.mjs';
 import { detectUsageLimit, formatUsageLimitMessage } from './usage-limit.lib.mjs';
 import { sanitizeObjectStrings } from './unicode-sanitization.lib.mjs';
 import { opencodeModels, defaultModels } from './models/index.mjs';
+import { logPreparedToolCommand, resolveFormalAiToolInvocation } from './formal-ai.lib.mjs';
 import { checkPlaywrightMcpPackageAvailability, getOpenCodePlaywrightMcpDisableEnv } from './playwright-mcp.lib.mjs';
 import { createAgentTokenUsage, accumulateAgentStepFinishUsage, parseAgentTokenUsage as parseOpenCodeTokenUsage } from './agent-token-usage.lib.mjs';
 import { calculateAgentPricing } from './agent.lib.mjs';
@@ -212,34 +213,6 @@ export const executeOpenCodeCommand = async params => {
       }
     }
 
-    // Create OpenCode configuration file with unrestricted permissions
-    // This allows OpenCode to access files outside the working directory without prompting
-    // Fixes issue #755: "Permission required to run: Access file outside working directory"
-    // Reference: https://opencode.ai/docs/config - see permissions documentation
-    const opencodeConfigPath = path.join(tempDir, 'opencode.json');
-    const opencodeConfig = {
-      $schema: 'https://opencode.ai/config.json',
-      permission: {
-        // All tool permissions set to 'allow' for unrestricted autonomous execution
-        // See: https://github.com/sst/opencode - permission options: "allow", "ask", "deny"
-        edit: 'allow', // File modification operations
-        bash: 'allow', // Command execution
-        webfetch: 'allow', // Web page retrieval
-        skill: 'allow', // Custom skills execution
-        doom_loop: 'allow', // Allow repeated identical tool calls (default: ask)
-        external_directory: 'allow', // File operations outside working directory (default: ask)
-      },
-    };
-    try {
-      await fs.writeFile(opencodeConfigPath, JSON.stringify(opencodeConfig, null, 2));
-      if (argv.verbose) {
-        await log(`   Created OpenCode config: ${opencodeConfigPath}`, { verbose: true });
-        await log('   Permissions set: edit=allow, bash=allow, webfetch=allow, skill=allow, doom_loop=allow, external_directory=allow', { verbose: true });
-      }
-    } catch (configError) {
-      await log(`⚠️  Warning: Could not create OpenCode config file: ${configError.message}`, { level: 'warning' });
-    }
-
     // Take resource snapshot before execution
     const resourcesBefore = await getResourceSnapshot();
     await log('📈 System resources before execution:', { verbose: true });
@@ -259,6 +232,11 @@ export const executeOpenCodeCommand = async params => {
 
     // Map model alias to full ID
     const mappedModel = mapModelToId(argv.model);
+    const toolInvocation = resolveFormalAiToolInvocation({
+      tool: 'opencode',
+      model: argv.model,
+      toolPath: opencodePath,
+    });
     const streamingTokenUsage = createAgentTokenUsage();
 
     // Build opencode command arguments
@@ -280,11 +258,38 @@ export const executeOpenCodeCommand = async params => {
     await fs.writeFile(promptFile, combinedPrompt);
 
     // Build the full command - pipe the prompt file to opencode
-    const fullCommand = `(cd "${tempDir}" && cat "${promptFile}" | ${opencodePath} ${opencodeArgs})`;
+    const fullCommand = `(cd "${tempDir}" && cat "${promptFile}" | ${toolInvocation.displayCommand} ${opencodeArgs})`;
 
-    await log(`\n${formatAligned('📝', 'Raw command:', '')}`);
-    await log(`${fullCommand}`);
-    await log('');
+    const preparedResult = await logPreparedToolCommand({ argv, fullCommand, log, formatAligned });
+    if (preparedResult) return preparedResult;
+
+    // Create OpenCode configuration file with unrestricted permissions
+    // This allows OpenCode to access files outside the working directory without prompting
+    // Fixes issue #755: "Permission required to run: Access file outside working directory"
+    // Reference: https://opencode.ai/docs/config - see permissions documentation
+    const opencodeConfigPath = path.join(tempDir, 'opencode.json');
+    const opencodeConfig = {
+      $schema: 'https://opencode.ai/config.json',
+      permission: {
+        // All tool permissions set to 'allow' for unrestricted autonomous execution
+        // See: https://github.com/sst/opencode - permission options: "allow", "ask", "deny"
+        edit: 'allow', // File modification operations
+        bash: 'allow', // Command execution
+        webfetch: 'allow', // Web page retrieval
+        skill: 'allow', // Custom skills execution
+        doom_loop: 'allow', // Allow repeated identical tool calls (default: ask)
+        external_directory: 'allow', // File operations outside working directory (default: ask)
+      },
+    };
+    try {
+      await fs.writeFile(opencodeConfigPath, JSON.stringify(opencodeConfig, null, 2));
+      if (argv.verbose) {
+        await log(`   Created OpenCode config: ${opencodeConfigPath}`, { verbose: true });
+        await log('   Permissions set: edit=allow, bash=allow, webfetch=allow, skill=allow, doom_loop=allow, external_directory=allow', { verbose: true });
+      }
+    } catch (configError) {
+      await log(`⚠️  Warning: Could not create OpenCode config file: ${configError.message}`, { level: 'warning' });
+    }
 
     const buildPricingInfo = async () => {
       const tokenUsage = streamingTokenUsage;
@@ -298,17 +303,19 @@ export const executeOpenCodeCommand = async params => {
     try {
       // Pipe the prompt file to opencode via stdin
       if (argv.resume) {
-        execCommand = $({
+        const commandRunner = $({
           cwd: tempDir,
           mirror: false,
           env: opencodeEnv,
-        })`cat ${promptFile} | ${opencodePath} run --format json --session ${argv.resume} --model ${mappedModel}`;
+        });
+        execCommand = toolInvocation.formalAi ? commandRunner`cat ${promptFile} | ${toolInvocation.command} ${toolInvocation.args} run --format json --session ${argv.resume} --model ${mappedModel}` : commandRunner`cat ${promptFile} | ${toolInvocation.command} run --format json --session ${argv.resume} --model ${mappedModel}`;
       } else {
-        execCommand = $({
+        const commandRunner = $({
           cwd: tempDir,
           mirror: false,
           env: opencodeEnv,
-        })`cat ${promptFile} | ${opencodePath} run --format json --model ${mappedModel}`;
+        });
+        execCommand = toolInvocation.formalAi ? commandRunner`cat ${promptFile} | ${toolInvocation.command} ${toolInvocation.args} run --format json --model ${mappedModel}` : commandRunner`cat ${promptFile} | ${toolInvocation.command} run --format json --model ${mappedModel}`;
       }
 
       await log(`${formatAligned('📋', 'Command details:', '')}`);

package/src/option-suggestions.lib.mjs

@@ -247,6 +247,7 @@ const KNOWN_OPTION_NAMES = [
   'keep-going-until-all-requirements-are-fully-done',
   'keep-working',
   'keep-going',
+  'require-codex-plugin',
 ];
 
 /**

package/src/qwen.lib.mjs

@@ -19,6 +19,7 @@ import { timeouts, retryLimits } from './config.lib.mjs';
 import { detectUsageLimit, formatUsageLimitMessage } from './usage-limit.lib.mjs';
 import { sanitizeObjectStrings } from './unicode-sanitization.lib.mjs';
 import { qwenModels, defaultModels } from './models/index.mjs';
+import { logPreparedToolCommand, resolveFormalAiToolInvocation } from './formal-ai.lib.mjs';
 import { checkPlaywrightMcpPackageAvailability } from './playwright-mcp.lib.mjs';
 import { classifyRetryableError, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
 import { getCumulativeContextInputTokens, getRestoredContextInputTokens, toTokenCount } from './context-fill.lib.mjs';
@@ -504,15 +505,19 @@ export const executeQwenCommand = async params => {
     await log(`   Load: ${resourcesBefore.load}`, { verbose: true });
 
     const mappedModel = mapModelToId(argv.model || defaultModels.qwen);
+    const toolInvocation = resolveFormalAiToolInvocation({
+      tool: 'qwen',
+      model: argv.model || defaultModels.qwen,
+      toolPath: qwenPath,
+    });
     const resumeSession = argv.resume || null;
     const resumeArgs = resumeSession ? ` --resume ${shellQuote(resumeSession)}` : '';
     const appendSystemPromptArg = systemPrompt ? ` --append-system-prompt "$(cat ${shellQuote(systemPromptFile)})"` : '';
-    const commandScript = `cd ${shellQuote(tempDir)} && ${shellQuote(qwenPath)} --model ${shellQuote(mappedModel)} --output-format stream-json --yolo${resumeArgs}${appendSystemPromptArg} --prompt "$(cat ${shellQuote(promptFile)})"`;
-    const fullCommand = `(cd "${tempDir}" && ${qwenPath} --model "${mappedModel}" --output-format stream-json --yolo${resumeSession ? ` --resume "${resumeSession}"` : ''}${systemPrompt ? ` --append-system-prompt "$(cat "${systemPromptFile}")"` : ''} --prompt "$(cat "${promptFile}")")`;
+    const commandScript = `cd ${shellQuote(tempDir)} && ${toolInvocation.displayCommand} --model ${shellQuote(mappedModel)} --output-format stream-json --yolo${resumeArgs}${appendSystemPromptArg} --prompt "$(cat ${shellQuote(promptFile)})"`;
+    const fullCommand = `(cd "${tempDir}" && ${toolInvocation.displayCommand} --model "${mappedModel}" --output-format stream-json --yolo${resumeSession ? ` --resume "${resumeSession}"` : ''}${systemPrompt ? ` --append-system-prompt "$(cat "${systemPromptFile}")"` : ''} --prompt "$(cat "${promptFile}")")`;
 
-    await log(`\n${formatAligned('📝', 'Raw command:', '')}`);
-    await log(fullCommand);
-    await log('');
+    const preparedResult = await logPreparedToolCommand({ argv, fullCommand, log, formatAligned });
+    if (preparedResult) return preparedResult;
 
     try {
       const execCommand = dollar({

package/src/solve.config.lib.mjs

@@ -715,6 +715,15 @@ export const SOLVE_OPTION_DEFINITIONS = {
     type: 'string',
     description: 'Comma-separated list of MCP server names that gemini-cli is allowed to call (passes --allowed-mcp-server-names to gemini-cli). Only used when --tool gemini.',
   },
+  // Issue #2102: the Codex capability preflight discovers requirements from the
+  // issue text and the target repository's agent instruction files (AGENTS.md,
+  // CLAUDE.md, .codex/). This is the escape hatch for a requirement no document
+  // states — codex's own `request_plugin_install` can never install anything
+  // under `codex exec`, so declaring it here is the only way in.
+  'require-codex-plugin': {
+    type: 'string',
+    description: 'Comma-separated list of Codex plugins (plugin@marketplace) that must be installed into the scoped CODEX_HOME before codex exec starts, in addition to the ones discovered from the issue text and the repository AGENTS.md/CLAUDE.md files. Fails the run when a listed plugin is unavailable. Equivalent to HIVE_MIND_CODEX_REQUIRED_PLUGINS. Only used when --tool codex.',
+  },
 };
 
 function hasRawOption(rawArgs, optionName) {

package/src/solve.mjs

@@ -253,7 +253,8 @@ if (argv.planModel) {
 if (argv.subAgentModel) await validateAndExitOnInvalidClaudeSubAgentModel(argv.subAgentModel, tool, safeExit);
 
 // Perform all system checks (skip tool connection check in dry-run or when --skip-tool-connection-check; model validation always runs)
-const skipToolConnectionCheck = argv.dryRun || argv.skipToolConnectionCheck || argv.toolConnectionCheck === false;
+const prepareOnly = argv.dryRun || argv.onlyPrepareCommand;
+const skipToolConnectionCheck = prepareOnly || argv.skipToolConnectionCheck || argv.toolConnectionCheck === false;
 const { cascadePlaywrightMcpDisable, ensureSolvePlaywrightMcpReady } = await import('./playwright-mcp.lib.mjs');
 await cascadePlaywrightMcpDisable(argv, log);
 if (!(await performSystemChecks(argv.minDiskSpace || 10240, skipToolConnectionCheck, argv.model, argv))) {
@@ -864,6 +865,7 @@ try {
     await safeExit(shutdownExitCode, 'Graceful shutdown after AI working session', { skipPreExit: true });
   }
 
+  if (toolResult.preparedOnly) await safeExit(0, 'Command prepared', { skipPreExit: true });
   const { success } = toolResult;
   sessionId = toolResult.sessionId;
   let anthropicTotalCostUSD = toolResult.anthropicTotalCostUSD;

package/src/solve.validation.lib.mjs

@@ -303,7 +303,22 @@ export const performSystemChecks = async (minDiskSpace = 10240, skipToolConnecti
   // Skip tool connection validation if in dry-run mode or explicitly requested
   if (!skipToolConnection) {
     let isToolConnected;
-    if (argv.useAgentCommander) {
+    const { isFormalAiModel } = await import('./models/index.mjs');
+    if (isFormalAiModel(model)) {
+      const { validateFormalAiToolConnection } = await import('./formal-ai.lib.mjs');
+      const formalAiValidation = await validateFormalAiToolConnection(argv.tool || 'claude');
+      isToolConnected = formalAiValidation.valid;
+      if (isToolConnected) {
+        await log(`✅ Formal AI wrapper and ${argv.tool || 'claude'} CLI are available`);
+        if (formalAiValidation.version) {
+          await log(`📦 ${argv.tool || 'claude'} CLI version: ${formalAiValidation.version}`);
+        }
+      } else {
+        await log(`❌ Formal AI dispatch validation failed: ${formalAiValidation.error}`, { level: 'error' });
+        await log('   Install or update the wrapper with: cargo install formal-ai', { level: 'error' });
+        return false;
+      }
+    } else if (argv.useAgentCommander) {
       const agentCommanderLib = await import('./agent-commander.lib.mjs');
       isToolConnected = await agentCommanderLib.validateAgentCommanderConnection({
         tool: argv.tool || 'claude',