@link-assistant/hive-mind 2.9.2 → 2.10.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @link-assistant/hive-mind
 
+## 2.10.0
+
+### Minor Changes
+
+- a1a1f63: Allow `--model formal-ai` with every supported agentic CLI, route execution through `formal-ai with`, and provide a persistent Formal AI Docker service.
+
 ## 2.9.2
 
 ### Patch Changes

package/README.hi.md

@@ -502,6 +502,11 @@ Free Models via Kilo Gateway (with --tool agent):
 /solve https://github.com/owner/repo/issues/123 --tool agent --model kilo/glm-5-free
 /solve https://github.com/owner/repo/issues/123 --tool agent --model kilo/glm-4.5-air-free
 /solve https://github.com/owner/repo/issues/123 --tool agent --model kilo/deepseek-r1-free
+
+# किसी भी समर्थित agentic CLI को Formal AI के माध्यम से route करें
+/solve https://github.com/owner/repo/issues/123 --tool agent --model formal-ai
+/solve https://github.com/owner/repo/issues/123 --tool codex --model formal-ai
+/solve https://github.com/owner/repo/issues/123 --tool claude --model formal-ai
 ```
 
 > **📖 मुफ्त मॉडल गाइड**: OpenCode Zen और Kilo Gateway प्रदाताओं सहित सभी मुफ्त मॉडलों के बारे में व्यापक जानकारी के लिए [docs/FREE_MODELS.hi.md](./docs/FREE_MODELS.hi.md) देखें।

package/README.md

@@ -506,6 +506,11 @@ Free Models via Kilo Gateway (with --tool agent):
 /solve https://github.com/owner/repo/issues/123 --tool agent --model kilo/glm-5-free
 /solve https://github.com/owner/repo/issues/123 --tool agent --model kilo/glm-4.5-air-free
 /solve https://github.com/owner/repo/issues/123 --tool agent --model kilo/deepseek-r1-free
+
+# Route any supported agentic CLI through Formal AI
+/solve https://github.com/owner/repo/issues/123 --tool agent --model formal-ai
+/solve https://github.com/owner/repo/issues/123 --tool codex --model formal-ai
+/solve https://github.com/owner/repo/issues/123 --tool claude --model formal-ai
 ```
 
 Current tool defaults in Hive Mind:

package/README.ru.md

@@ -503,6 +503,11 @@ Free Models via Kilo Gateway (with --tool agent):
 /solve https://github.com/owner/repo/issues/123 --tool agent --model kilo/glm-5-free
 /solve https://github.com/owner/repo/issues/123 --tool agent --model kilo/glm-4.5-air-free
 /solve https://github.com/owner/repo/issues/123 --tool agent --model kilo/deepseek-r1-free
+
+# Маршрутизация любого поддерживаемого агентного CLI через Formal AI
+/solve https://github.com/owner/repo/issues/123 --tool agent --model formal-ai
+/solve https://github.com/owner/repo/issues/123 --tool codex --model formal-ai
+/solve https://github.com/owner/repo/issues/123 --tool claude --model formal-ai
 ```
 
 > **📖 Руководство по бесплатным моделям**: см. [docs/FREE_MODELS.ru.md](./docs/FREE_MODELS.ru.md) для получения полной информации обо всех бесплатных моделях, включая провайдеры OpenCode Zen и Kilo Gateway.

package/README.zh.md

@@ -499,6 +499,11 @@ Free Models via Kilo Gateway (with --tool agent):
 /solve https://github.com/owner/repo/issues/123 --tool agent --model kilo/glm-5-free
 /solve https://github.com/owner/repo/issues/123 --tool agent --model kilo/glm-4.5-air-free
 /solve https://github.com/owner/repo/issues/123 --tool agent --model kilo/deepseek-r1-free
+
+# 通过 Formal AI 路由任意受支持的 Agent CLI
+/solve https://github.com/owner/repo/issues/123 --tool agent --model formal-ai
+/solve https://github.com/owner/repo/issues/123 --tool codex --model formal-ai
+/solve https://github.com/owner/repo/issues/123 --tool claude --model formal-ai
 ```
 
 > **📖 免费模型指南**：有关所有免费模型（包括 OpenCode Zen 和 Kilo Gateway 提供商）的全面信息，请参见 [docs/FREE_MODELS.zh.md](./docs/FREE_MODELS.zh.md)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "2.9.2",
+  "version": "2.10.0",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/agent.lib.mjs

@@ -22,6 +22,7 @@ import { sanitizeObjectStrings } from './unicode-sanitization.lib.mjs';
 import Decimal from 'decimal.js-light';
 import semver from 'semver';
 import { agentModels, defaultModels, freeToBaseModelMap } from './models/index.mjs';
+import { logPreparedToolCommand, resolveFormalAiToolInvocation } from './formal-ai.lib.mjs';
 import { checkPlaywrightMcpPackageAvailability, getAgentPlaywrightMcpDisableEnv } from './playwright-mcp.lib.mjs';
 import { createAgentTokenUsage, accumulateAgentStepFinishUsage, parseAgentTokenUsage } from './agent-token-usage.lib.mjs';
 import { classifyRetryableError, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
@@ -502,6 +503,11 @@ export const executeAgentCommand = async params => {
 
     // Map model alias to full ID
     const mappedModel = mapModelToId(argv.model);
+    const toolInvocation = resolveFormalAiToolInvocation({
+      tool: 'agent',
+      model: argv.model,
+      toolPath: agentPath,
+    });
 
     // Build agent command arguments
     let agentArgs = `--model ${mappedModel}`;
@@ -546,30 +552,31 @@ export const executeAgentCommand = async params => {
         await fs.writeFile(promptFile, combinedPrompt);
       }
 
-      const fullCommand = streamingInput ? `(cd "${tempDir}" && ${agentPath} ${agentArgs})` : `(cd "${tempDir}" && cat "${promptFile}" | ${agentPath} ${agentArgs})`;
+      const fullCommand = streamingInput ? `(cd "${tempDir}" && ${toolInvocation.displayCommand} ${agentArgs})` : `(cd "${tempDir}" && cat "${promptFile}" | ${toolInvocation.displayCommand} ${agentArgs})`;
 
-      await log(`\n${formatAligned('📝', 'Raw command:', '')}`);
-      await log(`${fullCommand}`);
-      await log('');
+      const preparedResult = await logPreparedToolCommand({ argv, fullCommand, log, formatAligned });
+      if (preparedResult) return preparedResult;
 
       if (streamingInput) {
-        execCommand = $({
+        const commandRunner = $({
           cwd: tempDir,
           stdin: 'pipe',
           mirror: false,
           env: agentEnv,
-        })`${agentPath} ${agentArgs}`;
+        });
+        execCommand = toolInvocation.formalAi ? commandRunner`${toolInvocation.command} ${toolInvocation.args} ${agentArgs}` : commandRunner`${toolInvocation.command} ${agentArgs}`;
         const attached = await attachStreamingInput(bidirectionalHandler, execCommand, combinedPrompt, log, !!argv.verbose, { toolLabel: 'Agent' });
         if (!attached) {
           throw new Error('Agent live stream-json input requested, but stdin attachment failed');
         }
       } else {
         // Pipe the prompt file to agent via stdin for the legacy one-shot path.
-        execCommand = $({
+        const commandRunner = $({
           cwd: tempDir,
           mirror: false,
           env: agentEnv,
-        })`cat ${promptFile} | ${agentPath} ${agentArgs}`;
+        });
+        execCommand = toolInvocation.formalAi ? commandRunner`cat ${promptFile} | ${toolInvocation.command} ${toolInvocation.args} ${agentArgs}` : commandRunner`cat ${promptFile} | ${toolInvocation.command} ${agentArgs}`;
       }
 
       await log(`${formatAligned('📋', 'Command details:', '')}`);

package/src/claude.lib.mjs

@@ -22,6 +22,7 @@ import { buildSolveResumeCommand } from './solve.resume-command.lib.mjs'; // Iss
 import { SESSION_FORCE_KILLED_MARKER, postTrackedComment } from './tool-comments.lib.mjs'; // Issue #1625
 import { handleClaudeRuntimeSwitch } from './claude.runtime-switch.lib.mjs'; // see issue #1141
 import { CLAUDE_MODELS as availableModels, mapClaudeSubAgentModelToEnvValue } from './models/index.mjs'; // Issue #1221, #1978
+import { logPreparedToolCommand, resolveFormalAiToolInvocation } from './formal-ai.lib.mjs';
 import { buildMcpConfigWithoutPlaywright, ensureClaudePlaywrightMcpServer } from './playwright-mcp.lib.mjs';
 import { resolveClaudeSessionToolFlags } from './useless-tools.lib.mjs';
 import { ensureClaudeQuietConfig } from './claude-quiet-config.lib.mjs';
@@ -614,13 +615,13 @@ export const executeClaudeCommand = async params => {
     const progressMonitor = await initProgressMonitoring(argv, { owner, repo, prNumber, $, log }); // works with or without --interactive-mode
     let execCommand;
     const mappedModel = mapModelToId(argv.model);
+    const toolInvocation = resolveFormalAiToolInvocation({ tool: 'claude', model: argv.model, toolPath: claudePath });
     const resolvedPlanModel = argv.planModel ? mapModelToId(argv.planModel) : undefined; // Issue #1223
     const resolvedSubAgentModel = argv.subAgentModel ? mapClaudeSubAgentModelToEnvValue(argv.subAgentModel) : undefined; // Issue #1978
     const effectiveModel = resolvedPlanModel ? 'opusplan' : mappedModel;
     const resolvedExecutionModel = resolvedPlanModel ? mappedModel : undefined;
-    // Issue #1949: Let Claude Code handle transient overload (529) fallback via its own
-    // `--fallback-model` flag (it re-tries the primary each turn) instead of us swapping
-    // `--model`. Only for plain `--model` runs (not opusplan) with a distinct fallback.
+    // Issue #1949: Let Claude Code's `--fallback-model` handle transient overloads and retry
+    // the primary each turn. Only for plain `--model` runs with a distinct fallback.
     const mappedFallbackModel = argv.fallbackModel ? mapModelToId(argv.fallbackModel) : undefined;
     const useClaudeFallbackModel = !resolvedPlanModel && mappedFallbackModel && mappedFallbackModel !== effectiveModel;
     let claudeArgs = `--output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel}`;
@@ -650,10 +651,9 @@ export const executeClaudeCommand = async params => {
     } else {
       claudeArgs += ` -p "${escapedPromptForAttempt}" --append-system-prompt "${escapedSystemPrompt}"`;
     }
-    const fullCommand = `(cd "${tempDir}" && ${claudePath} ${claudeArgs} | jq -c .)`;
-    await log(`\n${formatAligned('📝', 'Raw command:', '')}`);
-    await log(`${fullCommand}`);
-    await log('');
+    const fullCommand = `(cd "${tempDir}" && ${toolInvocation.displayCommand} ${claudeArgs} | jq -c .)`;
+    const preparedResult = await logPreparedToolCommand({ argv, fullCommand, log, formatAligned });
+    if (preparedResult) return preparedResult;
     if (argv.verbose) {
       await log(`📋 User prompt:\n---BEGIN USER PROMPT---\n${promptForAttempt}\n---END USER PROMPT---`, { verbose: true });
       await log(`📋 System prompt:\n---BEGIN SYSTEM PROMPT---\n${systemPrompt}\n---END SYSTEM PROMPT---`, { verbose: true });
@@ -684,15 +684,15 @@ export const executeClaudeCommand = async params => {
       if (useClaudeFallbackModel && argv.verbose) await log(`📊 Claude --fallback-model: ${mappedFallbackModel} (Issue #1949 — primary --model ${effectiveModel} stays stable across overload retries)`, { verbose: true });
       if (argv.resume) {
         const simpleEscapedPrompt = promptForAttempt.replace(/"/g, '\\"');
-        execCommand = $({ cwd: tempDir, mirror: false, env: claudeEnv })`${claudePath} --resume ${argv.resume} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${fallbackModelArgs} ${mcpDisableArgs} ${disallowedToolsArgs} -p "${simpleEscapedPrompt}" --append-system-prompt "${simpleEscapedSystem}"`;
+        execCommand = toolInvocation.formalAi ? $({ cwd: tempDir, mirror: false, env: claudeEnv })`${toolInvocation.command} ${toolInvocation.args} --resume ${argv.resume} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${fallbackModelArgs} ${mcpDisableArgs} ${disallowedToolsArgs} -p "${simpleEscapedPrompt}" --append-system-prompt "${simpleEscapedSystem}"` : $({ cwd: tempDir, mirror: false, env: claudeEnv })`${toolInvocation.command} --resume ${argv.resume} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${fallbackModelArgs} ${mcpDisableArgs} ${disallowedToolsArgs} -p "${simpleEscapedPrompt}" --append-system-prompt "${simpleEscapedSystem}"`;
       } else if (streamingInput) {
         // Issue #817: Drive Claude via --input-format stream-json on a pipe
         // stdin. Initial prompt + later PR comments are written as NDJSON
         // frames by attachStreamingInput (see bidirectional-interactive.lib.mjs).
         const streamingInputArgs = ['-p', '--input-format', 'stream-json'];
-        execCommand = $({ cwd: tempDir, stdin: 'pipe', mirror: false, env: claudeEnv })`${claudePath} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${fallbackModelArgs} ${mcpDisableArgs} ${disallowedToolsArgs} ${streamingInputArgs} --append-system-prompt "${simpleEscapedSystem}"`;
+        execCommand = toolInvocation.formalAi ? $({ cwd: tempDir, stdin: 'pipe', mirror: false, env: claudeEnv })`${toolInvocation.command} ${toolInvocation.args} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${fallbackModelArgs} ${mcpDisableArgs} ${disallowedToolsArgs} ${streamingInputArgs} --append-system-prompt "${simpleEscapedSystem}"` : $({ cwd: tempDir, stdin: 'pipe', mirror: false, env: claudeEnv })`${toolInvocation.command} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${fallbackModelArgs} ${mcpDisableArgs} ${disallowedToolsArgs} ${streamingInputArgs} --append-system-prompt "${simpleEscapedSystem}"`;
       } else {
-        execCommand = $({ cwd: tempDir, stdin: promptForAttempt, mirror: false, env: claudeEnv })`${claudePath} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${fallbackModelArgs} ${mcpDisableArgs} ${disallowedToolsArgs} --append-system-prompt "${simpleEscapedSystem}"`;
+        execCommand = toolInvocation.formalAi ? $({ cwd: tempDir, stdin: promptForAttempt, mirror: false, env: claudeEnv })`${toolInvocation.command} ${toolInvocation.args} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${fallbackModelArgs} ${mcpDisableArgs} ${disallowedToolsArgs} --append-system-prompt "${simpleEscapedSystem}"` : $({ cwd: tempDir, stdin: promptForAttempt, mirror: false, env: claudeEnv })`${toolInvocation.command} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${fallbackModelArgs} ${mcpDisableArgs} ${disallowedToolsArgs} --append-system-prompt "${simpleEscapedSystem}"`;
       }
       if (streamingInput) {
         await attachStreamingInput(bidirectionalHandler, execCommand, promptForAttempt, log, !!argv.verbose);

package/src/codex.lib.mjs

@@ -31,6 +31,7 @@ import { initProgressMonitoring } from './solve.progress-monitoring.lib.mjs';
 import { ensureCodexPlaywrightMcpServer, getCodexPlaywrightMcpDisableConfigArgs } from './playwright-mcp.lib.mjs';
 import { fetchModelInfo } from './model-info.lib.mjs';
 import { defaultModels } from './models/index.mjs';
+import { logPreparedToolCommand, resolveFormalAiToolInvocation } from './formal-ai.lib.mjs';
 import { classifyRetryableError, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
 import { parseSubSessionSize, buildCodexSubSessionSizeConfigArgs, buildCodexDisable1mContextConfigArgs } from './sub-session-size.lib.mjs'; // Issue #1706
 import { getCumulativeContextInputTokens } from './context-fill.lib.mjs';
@@ -816,6 +817,11 @@ export const executeCodexCommand = async params => {
 
     let execCommand;
     const mappedModel = mapModelToId(argv.model);
+    const toolInvocation = resolveFormalAiToolInvocation({
+      tool: 'codex',
+      model: argv.model,
+      toolPath: codexPath,
+    });
     const { reasoningEffort, source: reasoningEffortSource, rolloutTokenBudget } = resolveCodexReasoningEffort(argv);
     const isResumeMode = !!argv.resume;
     const codexEnv = applyCodexCapabilityEnv(capabilityPreflight?.codexBaseEnv || getCodexExecEnv(argv.verbose), {
@@ -889,11 +895,10 @@ export const executeCodexCommand = async params => {
       if (subSessionSizeArgs.length) await log(`📊 Codex --sub-session-size: ${subSessionSizeArgs.join(' ')}`, { verbose: true });
     }
 
-    const fullCommand = `(cd ${shellQuote(tempDir)} && cat ${shellQuote(promptFile)} | ${codexPath} ${codexArgs})`;
+    const fullCommand = `(cd ${shellQuote(tempDir)} && cat ${shellQuote(promptFile)} | ${toolInvocation.displayCommand} ${codexArgs})`;
 
-    await log(`\n${formatAligned('📝', 'Raw command:', '')}`);
-    await log(`${fullCommand}`);
-    await log('');
+    const preparedResult = await logPreparedToolCommand({ argv, fullCommand, log, formatAligned });
+    if (preparedResult) return preparedResult;
 
     try {
       let interactiveHandler = null;

package/src/formal-ai.lib.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+import { FORMAL_AI_MODEL_ALIAS, isFormalAiModel } from './models/index.mjs';
+
+const execFileAsync = promisify(execFile);
+
+export const FORMAL_AI_SUPPORTED_TOOLS = Object.freeze(['claude', 'agent', 'opencode', 'codex', 'qwen', 'gemini']);
+export const DEFAULT_FORMAL_AI_PATH = 'formal-ai';
+
+const SAFE_SHELL_WORD = /^[a-zA-Z0-9_\-./=,+@:]+$/;
+
+const shellQuote = value => {
+  const stringValue = String(value);
+  if (SAFE_SHELL_WORD.test(stringValue)) return stringValue;
+  return `'${stringValue.replaceAll("'", "'\\''")}'`;
+};
+
+const normalizeExternalBaseUrl = value => {
+  if (!value) return null;
+
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error(`HIVE_MIND_FORMAL_AI_BASE_URL must be a valid HTTP(S) URL, received "${value}"`);
+  }
+
+  if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password || parsed.pathname !== '/' || parsed.search || parsed.hash) {
+    throw new Error('HIVE_MIND_FORMAL_AI_BASE_URL must be an HTTP(S) origin without credentials, a path, a query, or a fragment');
+  }
+
+  return parsed.origin;
+};
+
+/**
+ * Resolve the executable and leading arguments for one Hive tool invocation.
+ * Formal AI owns the temporary client configuration and forwards all remaining
+ * arguments to the selected agentic CLI unchanged.
+ */
+export const resolveFormalAiToolInvocation = ({ tool, model, toolPath, env = process.env }) => {
+  if (!isFormalAiModel(model)) {
+    return {
+      command: toolPath,
+      args: [],
+      displayCommand: shellQuote(toolPath),
+      formalAi: false,
+      baseUrl: null,
+    };
+  }
+
+  if (!FORMAL_AI_SUPPORTED_TOOLS.includes(tool)) {
+    throw new Error(`Formal AI dispatch does not support Hive tool "${tool}"`);
+  }
+
+  const command = env.HIVE_MIND_FORMAL_AI_PATH?.trim() || DEFAULT_FORMAL_AI_PATH;
+  const baseUrl = normalizeExternalBaseUrl(env.HIVE_MIND_FORMAL_AI_BASE_URL);
+  const args = ['with'];
+
+  if (baseUrl) {
+    args.push('--no-start-server', '--base-url', baseUrl);
+  }
+  args.push(tool);
+
+  return {
+    command,
+    args,
+    displayCommand: [command, ...args].map(shellQuote).join(' '),
+    formalAi: true,
+    baseUrl,
+  };
+};
+
+/**
+ * Check both the wrapper and the selected native CLI without starting a model
+ * server or spending a model request.
+ */
+export const validateFormalAiToolConnection = async (tool, { env = process.env, run = execFileAsync, timeoutMs = 30_000 } = {}) => {
+  const invocation = resolveFormalAiToolInvocation({
+    tool,
+    model: FORMAL_AI_MODEL_ALIAS,
+    toolPath: tool,
+    env,
+  });
+  const args = ['with', '--no-start-server', tool, '--version'];
+
+  try {
+    const result = await run(invocation.command, args, {
+      encoding: 'utf8',
+      env: { ...process.env, ...env },
+      timeout: timeoutMs,
+    });
+    return {
+      valid: true,
+      command: invocation.command,
+      args,
+      version: result?.stdout?.trim() || null,
+    };
+  } catch (error) {
+    return {
+      valid: false,
+      command: invocation.command,
+      args,
+      error: error?.stderr?.trim() || error?.message || String(error),
+      code: error?.code,
+    };
+  }
+};
+
+export const isPrepareOnly = argv => !!(argv?.dryRun || argv?.onlyPrepareCommand);
+
+export const createPreparedToolResult = preparedCommand => ({
+  success: true,
+  preparedOnly: true,
+  preparedCommand,
+  sessionId: null,
+  limitReached: false,
+  errorDuringExecution: false,
+});
+
+export const logPreparedToolCommand = async ({ argv, fullCommand, log, formatAligned }) => {
+  await log(`\n${formatAligned('📝', 'Raw command:', '')}`);
+  await log(fullCommand);
+  await log('');
+
+  if (!isPrepareOnly(argv)) return null;
+
+  await log('🧪 Command prepared; AI execution skipped.');
+  return createPreparedToolResult(fullCommand);
+};

package/src/gemini.lib.mjs

@@ -18,6 +18,7 @@ import { buildSolveResumeCommand } from './solve.resume-command.lib.mjs'; // Iss
 const __geminiBuildSolveResumeCmd = (argv, sessionId, tempDir) => (sessionId && argv?.url ? buildSolveResumeCommand({ issueUrl: argv.url, sessionId, tool: 'gemini', model: argv.model, fallbackModel: argv.fallbackModel, tempDir }) : null);
 import { sanitizeObjectStrings } from './unicode-sanitization.lib.mjs';
 import { defaultModels, geminiModels } 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, toTokenCount } from './context-fill.lib.mjs';
@@ -423,6 +424,11 @@ export const executeGeminiCommand = async params => {
     await log(`   Load: ${resourcesBefore.load}`, { verbose: true });
 
     const mappedModel = mapModelToId(argv.model || defaultModels.gemini);
+    const toolInvocation = resolveFormalAiToolInvocation({
+      tool: 'gemini',
+      model: argv.model || defaultModels.gemini,
+      toolPath: geminiPath,
+    });
     const combinedPrompt = systemPrompt ? `${systemPrompt}\n\n${prompt}` : prompt;
 
     if (argv.resume) {
@@ -432,11 +438,11 @@ export const executeGeminiCommand = async params => {
     // Issue #1809: build args via shared helper so verbose/sandbox/include-dirs
     // toggles stay consistent between the logged command and the real invocation.
     const geminiArgList = buildGeminiArgs(argv, mappedModel, { tempDir, workspaceTmpDir });
-    const fullCommand = `(cd ${shellQuote(tempDir)} && ${geminiPath} ${geminiArgList.map(shellQuote).join(' ')} <<< <prompt>)`;
+    const fullGeminiArgList = [...toolInvocation.args, ...geminiArgList];
+    const fullCommand = `(cd ${shellQuote(tempDir)} && ${toolInvocation.displayCommand} ${geminiArgList.map(shellQuote).join(' ')} <<< <prompt>)`;
 
-    await log(`\n${formatAligned('📝', 'Raw command:', '')}`);
-    await log(fullCommand);
-    await log('');
+    const preparedResult = await logPreparedToolCommand({ argv, fullCommand, log, formatAligned });
+    if (preparedResult) return preparedResult;
 
     let geminiJsonState = {};
     let allOutput = '';
@@ -455,7 +461,7 @@ export const executeGeminiCommand = async params => {
         cwd: tempDir,
         stdin: combinedPrompt,
         mirror: false,
-      })`${geminiPath} ${geminiArgList}`;
+      })`${toolInvocation.command} ${fullGeminiArgList}`;
 
       await log(`${formatAligned('📋', 'Command details:', '')}`);
       await log(formatAligned('📂', 'Working directory:', tempDir, 2));

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/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.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',