@link-assistant/hive-mind 2.9.1 → 2.10.0

package/src/codex-health.lib.mjs

@@ -11,6 +11,7 @@
 // Both are re-exported from codex.lib.mjs for backward compatibility, so existing
 // importers (and tests) can keep importing them from either module.
 
+import { normalizePluginSelector } from './codex-capability-preflight.lib.mjs';
 import { isENOSPC } from './lib.mjs';
 
 const unwrapCodexErrorMessage = value => {
@@ -115,6 +116,84 @@ export const getCodexErrorEventSummary = codexJsonState => {
   };
 };
 
+// Issue #2102: `request_plugin_install` can never succeed under `codex exec`.
+// The tool validates its `plugin_id` against the server-driven
+// `<recommended_plugins>` list with an exact string comparison, and `codex exec`
+// auto-cancels the elicitation it would raise, so a model that reaches for it is
+// stuck in a loop it cannot exit. In the captured GCS-TS#5 runs that produced no
+// work at all, the only trace was in codex's OTEL text stream (the tool is a
+// builtin, so there is no NDJSON `mcp_tool_call` item to inspect):
+//
+//   INFO codex_otel.log_only: event.name="codex.tool_result"
+//     tool_name=request_plugin_install call_id=… arguments={"plugin_id":"…"}
+//     … success=false output=plugin_id must match one of the entries in the
+//     <recommended_plugins> list
+//   ERROR codex_core::tools::router: error=plugin_id must match one of the
+//     entries in the <recommended_plugins> list
+//
+// Both patterns are anchored at the beginning of the line rather than matched
+// anywhere in it: codex echoes the stdout of every command it runs back into its
+// own stream (issue #1955), and this repository's own case-study logs contain
+// these very lines. An echoed copy is always preceded by the emitting tool's own
+// prefix (`tool_name=shell … output=…`), so requiring `request_plugin_install` to
+// be the tool of the line's *own* event, and the router error to open the line,
+// keeps replayed text from being read as a live rejection.
+const PLUGIN_INSTALL_MESSAGE_TEXT = 'plugin_id must match one of the entries in the <recommended_plugins> list';
+const PLUGIN_INSTALL_MESSAGE_PATTERN = /plugin_id must match one of the entries in the <recommended_plugins> list/;
+const PLUGIN_INSTALL_TOOL_RESULT = /^(?:\S+\s+)?(?:TRACE|DEBUG|INFO|WARN|ERROR)\s+codex_otel\.log_only:\s+event\.name="codex\.tool_result"\s+tool_name=request_plugin_install\b/;
+const PLUGIN_INSTALL_ROUTER_ERROR = /^(?:\S+\s+)?ERROR\s+codex_core::tools::router:\s+error=plugin_id must match one of the entries in the <recommended_plugins> list/;
+const PLUGIN_INSTALL_CALL_ID = /\bcall_id=(\S+)/;
+const PLUGIN_INSTALL_PLUGIN_ID = /"plugin_id"\s*:\s*"([^"]+)"/;
+const PLUGIN_INSTALL_SUCCESS = /\bsuccess=(true|false)\b/;
+
+export const matchCodexPluginInstallRejection = line => {
+  const text = String(line || '');
+  if (PLUGIN_INSTALL_ROUTER_ERROR.test(text)) return { source: 'router', callId: null, pluginId: null, message: PLUGIN_INSTALL_MESSAGE_TEXT };
+  if (!PLUGIN_INSTALL_TOOL_RESULT.test(text)) return null;
+  if (!PLUGIN_INSTALL_MESSAGE_PATTERN.test(text)) return null;
+  if (PLUGIN_INSTALL_SUCCESS.exec(text)?.[1] === 'true') return null;
+  return { source: 'tool_result', callId: PLUGIN_INSTALL_CALL_ID.exec(text)?.[1] || null, pluginId: PLUGIN_INSTALL_PLUGIN_ID.exec(text)?.[1] || null, message: PLUGIN_INSTALL_MESSAGE_TEXT };
+};
+
+// Issue #2102: a rejected runtime install means the capability preflight did not
+// provision what the task needs, so the run cannot do the work it was asked to
+// do. It is reported as a failure only when nothing was produced: a model may
+// probe `request_plugin_install` and then complete the task without the plugin,
+// and failing that run retroactively would discard real output.
+export const getCodexPluginProvisioningHealth = (codexJsonState, { capabilityPreflight = null } = {}) => {
+  const rejections = codexJsonState?.pluginInstallRejections || [];
+  const requestedPlugins = [...new Set(rejections.map(entry => entry.pluginId).filter(Boolean))].sort();
+  const fileChanges = codexJsonState?.fileChanges || [];
+  const producedWork = fileChanges.length > 0;
+  const detected = rejections.length > 0;
+
+  const reasons = [];
+  const guidance = [];
+  if (detected) {
+    reasons.push(`Codex called request_plugin_install${requestedPlugins.length > 0 ? ` for ${requestedPlugins.join(', ')}` : ''} and codex rejected it: ${PLUGIN_INSTALL_MESSAGE_TEXT}. Under codex exec this tool can never install a plugin, so the model cannot recover on its own.`);
+    reasons.push(capabilityPreflight?.required ? `The Hive Mind Codex capability preflight ran for ${(capabilityPreflight.plugins || []).join(', ') || 'no plugins'}, so the plugin the model asked for was not among the requirements it discovered.` : 'The Hive Mind Codex capability preflight detected no requirements for this task, so nothing was provisioned before codex exec.');
+    for (const plugin of requestedPlugins.length > 0 ? requestedPlugins : ['<plugin>@<marketplace>']) {
+      // Issue #2102: the model asks for `@openai-curated-remote`, which is a
+      // synthesized namespace that `codex plugin add` cannot install; the
+      // preflight's normalization maps it onto the installable `@openai-curated`
+      // marketplace, so the guidance must quote the selector that actually works.
+      guidance.push(`Declare the requirement so the preflight provisions it: --require-codex-plugin ${normalizePluginSelector(plugin)} (or HIVE_MIND_CODEX_REQUIRED_PLUGINS).`);
+    }
+    guidance.push('Requirements declared in the target repository AGENTS.md / CLAUDE.md are discovered automatically; run with --verbose to see the sources the preflight scanned.');
+  }
+
+  return {
+    healthy: !detected || producedWork,
+    detected,
+    producedWork,
+    requestedPlugins,
+    rejections,
+    message: detected ? reasons[0] : null,
+    reasons,
+    guidance,
+  };
+};
+
 // Issue #1990: A Codex run can exit 0 with no fatal `turn.failed`/error event yet
 // still be fundamentally broken. Under docker isolation two long-running
 // `solve --tool codex` tasks reported SUCCESS (Exit Code: 0) while their
@@ -189,3 +268,47 @@ export const getCodexCompletionHealth = (codexJsonState, { lastMessage = '' } =
     reasons,
   };
 };
+
+// Reporting helpers for the run gates in codex.lib.mjs. They live here with the
+// analysis they narrate so codex.lib.mjs stays inside the 1500-line budget
+// (issues #1730 / #1990).
+export const logCodexResourceSnapshot = async ({ getResourceSnapshot, log }) => {
+  const resourcesAfter = await getResourceSnapshot();
+  await log('\n📈 System resources after execution:', { verbose: true });
+  await log(`   Memory: ${resourcesAfter.memory.split('\n')[1]}`, { verbose: true });
+  await log(`   Load: ${resourcesAfter.load}`, { verbose: true });
+};
+
+export const reportCodexCompletionFailure = async ({ completionHealth, log, getResourceSnapshot }) => {
+  await log('\n\n❌ Codex exited 0 but the run did not complete — treating as failure', { level: 'error' });
+  for (const reason of completionHealth.reasons) {
+    await log(`   • ${reason}`, { level: 'error' });
+  }
+  await log(`   📊 turn.started=${completionHealth.turnStarted}, turn.completed=${completionHealth.turnCompleted}, turn.failed=${completionHealth.turnFailed}`, { verbose: true });
+  if (completionHealth.diskPressureDetected) {
+    await log('   💽 Disk-exhaustion evidence (diagnostic):', { level: 'error' });
+    for (const evidence of completionHealth.diskEvidence.slice(0, 5)) {
+      await log(`      ↳ [${evidence.source}] ${evidence.text}`, { level: 'error' });
+    }
+    await log('   💡 Free disk space before retrying. Under docker isolation the container is preserved on failure for inspection.', { level: 'error' });
+  }
+  await logCodexResourceSnapshot({ getResourceSnapshot, log });
+};
+
+export const reportCodexPluginProvisioning = async ({ pluginProvisioning, log }) => {
+  if (!pluginProvisioning.detected) return;
+  if (!pluginProvisioning.healthy) {
+    await log('\n\n❌ Codex could not obtain a required plugin at runtime — treating as failure', { level: 'error' });
+    for (const reason of pluginProvisioning.reasons) {
+      await log(`   • ${reason}`, { level: 'error' });
+    }
+    for (const hint of pluginProvisioning.guidance) {
+      await log(`   💡 ${hint}`, { level: 'error' });
+    }
+    return;
+  }
+  await log(`\n⚠️ Codex asked to install ${pluginProvisioning.requestedPlugins.join(', ') || 'a plugin'} at runtime and was rejected, but the run still produced changes`, { level: 'warning' });
+  for (const hint of pluginProvisioning.guidance) {
+    await log(`   💡 ${hint}`, { level: 'warning', verbose: true });
+  }
+};

package/src/codex.lib.mjs

@@ -17,8 +17,8 @@ const os = (await use('os')).default;
 import { log } from './lib.mjs';
 // Issues #1955 / #1990: run-health analysis lives in its own module to keep this
 // file under the max-lines budget. Re-exported below for backward compatibility.
-import { getCodexErrorEventSummary, getCodexCompletionHealth } from './codex-health.lib.mjs';
-export { getCodexErrorEventSummary, getCodexCompletionHealth };
+import { getCodexErrorEventSummary, getCodexCompletionHealth, getCodexPluginProvisioningHealth, logCodexResourceSnapshot, matchCodexPluginInstallRejection, reportCodexCompletionFailure, reportCodexPluginProvisioning } from './codex-health.lib.mjs';
+export { getCodexErrorEventSummary, getCodexCompletionHealth, getCodexPluginProvisioningHealth, matchCodexPluginInstallRejection };
 import { reportError } from './sentry.lib.mjs';
 import { timeouts, retryLimits } from './config.lib.mjs';
 import { detectUsageLimit, formatUsageLimitMessage } from './usage-limit.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';
@@ -351,6 +352,7 @@ export const parseCodexExecJsonOutput = (output, state = {}, requestedModelId =
     itemErrors: state.itemErrors || [],
     turnFailures: state.turnFailures || [],
     streamErrors: state.streamErrors || [],
+    pluginInstallRejections: state.pluginInstallRejections || [],
     observedUsageFieldSets: state.observedUsageFieldSets || [],
     observedModelDiagnosticPaths: state.observedModelDiagnosticPaths || [],
   };
@@ -371,6 +373,11 @@ export const parseCodexExecJsonOutput = (output, state = {}, requestedModelId =
     try {
       data = sanitizeObjectStrings(JSON.parse(line));
     } catch {
+      // Issue #2102: `request_plugin_install` is a codex builtin, so its rejection
+      // never arrives as an NDJSON item — it only exists in the interleaved OTEL
+      // text stream, which is exactly the set of lines that fail to parse here.
+      const rejection = matchCodexPluginInstallRejection(line);
+      if (rejection) nextState.pluginInstallRejections.push(rejection);
       continue;
     }
 
@@ -745,7 +752,10 @@ export const executeCodex = async params => {
   // it natively from .agents/skills/handoff/SKILL.md (no-op unless --use-handoff).
   await deployHandoffSkill({ tempDir, argv, log, $ });
   const codexBaseEnv = getCodexExecEnv(argv.verbose);
-  const capabilityPreflight = await runCodexCapabilityPreflight({ owner, repo, issueNumber, projectDir: tempDir, codexPath, log, env: codexBaseEnv });
+  // Issue #2102: the target repository's own agent instruction files are part of
+  // the requirement corpus, so the preflight needs the checkout; `--require-codex-plugin`
+  // is the explicit escape hatch for requirements no document states.
+  const capabilityPreflight = await runCodexCapabilityPreflight({ owner, repo, issueNumber, projectDir: tempDir, codexPath, log, env: codexBaseEnv, requiredPlugins: argv.requireCodexPlugin });
   // Execute the Codex command
   return await executeCodexCommand({
     tempDir,
@@ -807,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), {
@@ -880,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;
@@ -961,6 +975,7 @@ export const executeCodexCommand = async params => {
         itemErrors: [],
         turnFailures: [],
         streamErrors: [],
+        pluginInstallRejections: [],
         observedUsageFieldSets: [],
         observedModelDiagnosticPaths: [],
       };
@@ -1127,13 +1142,25 @@ export const executeCodexCommand = async params => {
         await log(`⚠️ Codex public pricing estimate unavailable: ${pricingInfo.error}`, { level: 'warning', verbose: true });
       }
       const resultModelUsage = pricingInfo?.tokenUsage ? buildCodexResultModelUsage(firstActualModelId, pricingInfo.tokenUsage, pricingInfo) : null;
+      // Every exit from this run reports the same accounting fields; only the
+      // outcome-specific ones differ. `lastTextContent` is the result summary
+      // captured from the JSON output stream (issue #1263).
+      const buildRunResult = outcome => ({
+        sessionId,
+        limitReached,
+        limitResetTime,
+        pricingInfo,
+        publicPricingEstimate: pricingInfo?.totalCostUSD ?? null,
+        resultModelUsage,
+        subAgentCalls: codexJsonState.subAgentCalls.length > 0 ? codexJsonState.subAgentCalls : null,
+        codexJsonDetails: codexJsonState,
+        resultSummary: lastTextContent || null,
+        ...outcome,
+      });
 
       // Check for authentication errors first - these should never be retried
       if (authError) {
-        const resourcesAfter = await getResourceSnapshot();
-        await log('\n📈 System resources after execution:', { verbose: true });
-        await log(`   Memory: ${resourcesAfter.memory.split('\n')[1]}`, { verbose: true });
-        await log(`   Load: ${resourcesAfter.load}`, { verbose: true });
+        await logCodexResourceSnapshot({ getResourceSnapshot, log });
 
         // Throw an error to stop retries and propagate the auth failure
         const error = new Error('Codex authentication failed - 401 Unauthorized. Please run: codex login');
@@ -1199,25 +1226,9 @@ export const executeCodexCommand = async params => {
           await log(`   Error events: item=${codexErrorSummary.counts.item}, turn=${codexErrorSummary.counts.turn}, stream=${codexErrorSummary.counts.stream}`, { level: 'error' });
         }
 
-        const resourcesAfter = await getResourceSnapshot();
-        await log('\n📈 System resources after execution:', { verbose: true });
-        await log(`   Memory: ${resourcesAfter.memory.split('\n')[1]}`, { verbose: true });
-        await log(`   Load: ${resourcesAfter.load}`, { verbose: true });
+        await logCodexResourceSnapshot({ getResourceSnapshot, log });
 
-        return {
-          success: false,
-          sessionId,
-          limitReached,
-          limitResetTime,
-          pricingInfo,
-          publicPricingEstimate: pricingInfo?.totalCostUSD ?? null,
-          resultModelUsage,
-          subAgentCalls: codexJsonState.subAgentCalls.length > 0 ? codexJsonState.subAgentCalls : null,
-          codexJsonDetails: codexJsonState,
-          errorInfo: codexErrorSummary,
-          result: codexErrorSummary.message,
-          resultSummary: lastTextContent || null, // Issue #1263: Use last text content from JSON output stream
-        };
+        return buildRunResult({ success: false, errorInfo: codexErrorSummary, result: codexErrorSummary.message });
       }
 
       if (exitCode !== 0) {
@@ -1269,24 +1280,22 @@ export const executeCodexCommand = async params => {
           await log(`\n\n❌ Codex command failed with exit code ${exitCode}`, { level: 'error' });
         }
 
-        const resourcesAfter = await getResourceSnapshot();
-        await log('\n📈 System resources after execution:', { verbose: true });
-        await log(`   Memory: ${resourcesAfter.memory.split('\n')[1]}`, { verbose: true });
-        await log(`   Load: ${resourcesAfter.load}`, { verbose: true });
+        await logCodexResourceSnapshot({ getResourceSnapshot, log });
 
-        return {
-          success: false,
-          sessionId,
-          limitReached,
-          limitResetTime,
-          pricingInfo,
-          publicPricingEstimate: pricingInfo?.totalCostUSD ?? null,
-          resultModelUsage,
-          subAgentCalls: codexJsonState.subAgentCalls.length > 0 ? codexJsonState.subAgentCalls : null,
-          codexJsonDetails: codexJsonState,
-          errorInfo: getCodexErrorEventSummary(codexJsonState),
-          resultSummary: lastTextContent || null, // Issue #1263: Use last text content from JSON output stream
-        };
+        return buildRunResult({ success: false, errorInfo: getCodexErrorEventSummary(codexJsonState) });
+      }
+
+      // Issue #2102: a rejected `request_plugin_install` means codex asked for a
+      // capability the preflight did not provision, and under `codex exec` that
+      // request can never succeed — so a run that produced nothing is blocked,
+      // not finished. Reporting it as a named failure (instead of an empty
+      // success) is what makes the missing requirement visible.
+      const pluginProvisioning = getCodexPluginProvisioningHealth(codexJsonState, { capabilityPreflight });
+      await reportCodexPluginProvisioning({ pluginProvisioning, log });
+      if (!pluginProvisioning.healthy) {
+        if (sessionId && !argv.resume) argv.resume = sessionId;
+
+        return buildRunResult({ success: false, errorInfo: getCodexErrorEventSummary(codexJsonState), pluginProvisioning, result: [pluginProvisioning.message, ...pluginProvisioning.guidance].join(' ') });
       }
 
       // Issue #1990: exit code 0 and the absence of a fatal codex error event are
@@ -1297,23 +1306,7 @@ export const executeCodexCommand = async params => {
       // container filesystem needed to inspect and retry the failure (#1990).
       const completionHealth = getCodexCompletionHealth(codexJsonState, { lastMessage });
       if (!completionHealth.healthy) {
-        await log('\n\n❌ Codex exited 0 but the run did not complete — treating as failure', { level: 'error' });
-        for (const reason of completionHealth.reasons) {
-          await log(`   • ${reason}`, { level: 'error' });
-        }
-        await log(`   📊 turn.started=${completionHealth.turnStarted}, turn.completed=${completionHealth.turnCompleted}, turn.failed=${completionHealth.turnFailed}`, { verbose: true });
-        if (completionHealth.diskPressureDetected) {
-          await log('   💽 Disk-exhaustion evidence (diagnostic):', { level: 'error' });
-          for (const evidence of completionHealth.diskEvidence.slice(0, 5)) {
-            await log(`      ↳ [${evidence.source}] ${evidence.text}`, { level: 'error' });
-          }
-          await log('   💡 Free disk space before retrying. Under docker isolation the container is preserved on failure for inspection.', { level: 'error' });
-        }
-
-        const resourcesAfter = await getResourceSnapshot();
-        await log('\n📈 System resources after execution:', { verbose: true });
-        await log(`   Memory: ${resourcesAfter.memory.split('\n')[1]}`, { verbose: true });
-        await log(`   Load: ${resourcesAfter.load}`, { verbose: true });
+        await reportCodexCompletionFailure({ completionHealth, log, getResourceSnapshot });
 
         // Issue #1990: preserve the codex session so an outer full restart can
         // resume with context (mirrors the transient-error retry above and the
@@ -1323,23 +1316,7 @@ export const executeCodexCommand = async params => {
         // restart at the orchestration level.
         if (sessionId && !argv.resume) argv.resume = sessionId;
 
-        return {
-          success: false,
-          sessionId,
-          limitReached,
-          limitResetTime,
-          pricingInfo,
-          publicPricingEstimate: pricingInfo?.totalCostUSD ?? null,
-          resultModelUsage,
-          subAgentCalls: codexJsonState.subAgentCalls.length > 0 ? codexJsonState.subAgentCalls : null,
-          codexJsonDetails: codexJsonState,
-          errorInfo: getCodexErrorEventSummary(codexJsonState),
-          completionHealth,
-          incompleteSession: completionHealth.incompleteSession,
-          diskPressureDetected: completionHealth.diskPressureDetected,
-          result: completionHealth.reasons.join(' '),
-          resultSummary: lastTextContent || null,
-        };
+        return buildRunResult({ success: false, errorInfo: getCodexErrorEventSummary(codexJsonState), completionHealth, pluginProvisioning, incompleteSession: completionHealth.incompleteSession, diskPressureDetected: completionHealth.diskPressureDetected, result: completionHealth.reasons.join(' ') });
       }
 
       await log('\n\n✅ Codex command completed');
@@ -1351,18 +1328,7 @@ export const executeCodexCommand = async params => {
         await log('⚠️ No result summary captured from Codex output or last-message file', { level: 'warning', verbose: true });
       }
 
-      return {
-        success: true,
-        sessionId,
-        limitReached,
-        limitResetTime,
-        pricingInfo,
-        publicPricingEstimate: pricingInfo?.totalCostUSD ?? null,
-        resultModelUsage,
-        subAgentCalls: codexJsonState.subAgentCalls.length > 0 ? codexJsonState.subAgentCalls : null,
-        codexJsonDetails: codexJsonState,
-        resultSummary: lastTextContent || null, // Issue #1263: Use last text content from JSON output stream
-      };
+      return buildRunResult({ success: true, pluginProvisioning });
     } catch (error) {
       // Don't report auth errors to Sentry as they are user configuration issues
       if (!error.isAuthError) {

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));