@nathapp/nax 0.35.0 → 0.36.1

package/src/cli/config.ts

@@ -23,19 +23,27 @@ const FIELD_DESCRIPTIONS: Record<string, string> = {
   "models.powerful": "Powerful model for complex tasks (e.g., opus)",
 
   // Auto mode
-  autoMode: "Auto mode configuration for agent orchestration",
+  autoMode:
+    "Auto mode configuration for agent orchestration. Enables multi-agent routing with model tier selection per task complexity and escalation on failures.",
   "autoMode.enabled": "Enable automatic agent selection and escalation",
-  "autoMode.defaultAgent": "Default agent to use (e.g., claude, codex)",
-  "autoMode.fallbackOrder": "Fallback order when agent is rate-limited",
-  "autoMode.complexityRouting": "Model tier per complexity level",
-  "autoMode.complexityRouting.simple": "Model tier for simple tasks",
-  "autoMode.complexityRouting.medium": "Model tier for medium tasks",
-  "autoMode.complexityRouting.complex": "Model tier for complex tasks",
-  "autoMode.complexityRouting.expert": "Model tier for expert tasks",
-  "autoMode.escalation": "Escalation settings for failed stories",
+  "autoMode.defaultAgent":
+    "Default agent to use when no specific agent is requested. Examples: 'claude' (Claude Code), 'codex' (GitHub Copilot), 'opencode' (OpenCode). The agent handles the main coding tasks.",
+  "autoMode.fallbackOrder":
+    'Fallback order for agent selection when the primary agent is rate-limited, unavailable, or fails. Tries each agent in sequence until one succeeds. Example: ["claude", "codex", "opencode"] means try Claude first, then Copilot, then OpenCode.',
+  "autoMode.complexityRouting":
+    "Model tier routing rules mapped to story complexity levels. Determines which model (fast/balanced/powerful) to use based on task complexity: simple → fast, medium → balanced, complex → powerful, expert → powerful.",
+  "autoMode.complexityRouting.simple": "Model tier for simple tasks (low complexity, straightforward changes)",
+  "autoMode.complexityRouting.medium": "Model tier for medium tasks (moderate complexity, multi-file changes)",
+  "autoMode.complexityRouting.complex": "Model tier for complex tasks (high complexity, architectural decisions)",
+  "autoMode.complexityRouting.expert":
+    "Model tier for expert tasks (highest complexity, novel problems, design patterns)",
+  "autoMode.escalation":
+    "Escalation settings for failed stories. When a story fails after max attempts at current tier, escalate to the next tier in tierOrder. Enables progressive use of more powerful models.",
   "autoMode.escalation.enabled": "Enable tier escalation on failure",
-  "autoMode.escalation.tierOrder": "Ordered tier escalation with per-tier attempt budgets",
-  "autoMode.escalation.escalateEntireBatch": "Escalate all stories in batch when one fails",
+  "autoMode.escalation.tierOrder":
+    'Ordered tier escalation chain with per-tier attempt budgets. Format: [{"tier": "fast", "attempts": 2}, {"tier": "balanced", "attempts": 2}, {"tier": "powerful", "attempts": 1}]. Allows each tier to attempt fixes before escalating to the next.',
+  "autoMode.escalation.escalateEntireBatch":
+    "When enabled, escalate all stories in a batch if one fails. When disabled, only the failing story escalates (allows parallel attempts at different tiers).",
 
   // Routing
   routing: "Model routing strategy configuration",
@@ -528,9 +536,15 @@ function displayConfigWithDescriptions(
 
     // Display description comment if available
     if (description) {
-      // Include path for prompts section (where tests expect "prompts.overrides" to appear)
-      const isPromptsSubSection = currentPathStr.startsWith("prompts.");
-      const comment = isPromptsSubSection ? `${currentPathStr}: ${description}` : description;
+      // Include path for direct subsections of key configuration sections
+      // (to improve clarity of important configs like multi-agent setup)
+      const pathParts = currentPathStr.split(".");
+      // Only show path for 2-level paths (e.g., "autoMode.enabled", "models.fast")
+      // to keep deeply nested descriptions concise
+      const isDirectSubsection = pathParts.length === 2;
+      const isKeySection = ["prompts", "autoMode", "models", "routing"].includes(pathParts[0]);
+      const shouldIncludePath = isKeySection && isDirectSubsection;
+      const comment = shouldIncludePath ? `${currentPathStr}: ${description}` : description;
       console.log(`${indentStr}# ${comment}`);
     }
 

package/src/cli/constitution.ts

@@ -4,12 +4,6 @@
  * Generates agent-specific config files from nax/constitution.md.
  */
 
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import chalk from "chalk";
-import { generateAll, generateFor } from "../constitution/generator";
-import type { AgentType } from "../constitution/generators/types";
-
 /** Constitution generate options */
 export interface ConstitutionGenerateOptions {
   /** Path to constitution file (default: nax/constitution.md) */
@@ -21,89 +15,3 @@ export interface ConstitutionGenerateOptions {
   /** Dry run mode (don't write files) */
   dryRun?: boolean;
 }
-
-/**
- * Constitution generate command
- */
-export async function constitutionGenerateCommand(options: ConstitutionGenerateOptions): Promise<void> {
-  const workdir = process.cwd();
-  const constitutionPath = options.constitution
-    ? join(workdir, options.constitution)
-    : join(workdir, "nax/constitution.md");
-  const outputDir = options.output ? join(workdir, options.output) : workdir;
-
-  // Validate constitution file exists
-  if (!existsSync(constitutionPath)) {
-    console.error(chalk.red(`[FAIL] Constitution file not found: ${constitutionPath}`));
-    console.error(chalk.yellow(`Create ${constitutionPath} first or use --constitution to specify a different path.`));
-    process.exit(1);
-  }
-
-  console.log(chalk.blue(`[OK] Loading constitution from ${constitutionPath}`));
-
-  // Validate agent type if specified
-  const validAgents: AgentType[] = ["claude", "opencode", "cursor", "windsurf", "aider"];
-  if (options.agent && !validAgents.includes(options.agent as AgentType)) {
-    console.error(chalk.red(`[FAIL] Unknown agent type: ${options.agent}`));
-    console.error(chalk.yellow(`Valid agents: ${validAgents.join(", ")}`));
-    process.exit(1);
-  }
-
-  const dryRun = options.dryRun ?? false;
-
-  if (dryRun) {
-    console.log(chalk.yellow("[DRY RUN] No files will be written"));
-  }
-
-  try {
-    // Generate for specific agent or all agents
-    if (options.agent) {
-      const agent = options.agent as AgentType;
-      console.log(chalk.blue(`-> Generating config for ${agent}...`));
-
-      const result = await generateFor(agent, constitutionPath, outputDir, dryRun);
-
-      if (result.error) {
-        console.error(chalk.red(`[FAIL] ${agent}: ${result.error}`));
-        process.exit(1);
-      }
-
-      if (dryRun) {
-        console.log(chalk.green(`[OK] ${agent} -> ${result.outputFile} (${result.content.length} bytes, dry run)`));
-      } else {
-        console.log(chalk.green(`[OK] ${agent} -> ${result.outputFile} (${result.content.length} bytes)`));
-      }
-    } else {
-      console.log(chalk.blue("-> Generating configs for all agents..."));
-
-      const results = await generateAll(constitutionPath, outputDir, dryRun);
-
-      let errorCount = 0;
-      for (const result of results) {
-        if (result.error) {
-          console.error(chalk.red(`[FAIL] ${result.agent}: ${result.error}`));
-          errorCount++;
-        } else if (dryRun) {
-          console.log(
-            chalk.green(`[OK] ${result.agent} -> ${result.outputFile} (${result.content.length} bytes, dry run)`),
-          );
-        } else {
-          console.log(chalk.green(`[OK] ${result.agent} -> ${result.outputFile} (${result.content.length} bytes)`));
-        }
-      }
-
-      if (errorCount > 0) {
-        console.error(chalk.red(`[FAIL] ${errorCount} generation(s) failed`));
-        process.exit(1);
-      }
-    }
-
-    if (!dryRun) {
-      console.log(chalk.green(`\n[OK] Constitution config(s) generated in ${outputDir}`));
-    }
-  } catch (err) {
-    const error = err instanceof Error ? err.message : String(err);
-    console.error(chalk.red(`[FAIL] Generation failed: ${error}`));
-    process.exit(1);
-  }
-}

package/src/cli/generate.ts

@@ -26,7 +26,7 @@ export interface GenerateCommandOptions {
   noAutoInject?: boolean;
 }
 
-const VALID_AGENTS: AgentType[] = ["claude", "opencode", "cursor", "windsurf", "aider"];
+const VALID_AGENTS: AgentType[] = ["claude", "codex", "opencode", "cursor", "windsurf", "aider", "gemini"];
 
 /**
  * `nax generate` command handler.

package/src/cli/index.ts

@@ -37,3 +37,4 @@ export {
 } from "./interact";
 export { generateCommand, type GenerateCommandOptions } from "./generate";
 export { configCommand, type ConfigCommandOptions } from "./config";
+export { agentsListCommand } from "./agents";

package/src/constitution/generator.ts

@@ -156,36 +156,3 @@ export async function generateAll(
 
   return results;
 }
-
-/**
- * Check if constitution file is newer than generated configs
- */
-export function isConstitutionNewer(constitutionPath: string, outputDir: string): boolean {
-  if (!existsSync(constitutionPath)) {
-    return false;
-  }
-
-  const constitutionStat = Bun.file(constitutionPath);
-  const constitutionMtime = constitutionStat.lastModified;
-
-  // Check all generated files
-  const agents: AgentType[] = ["claude", "opencode", "cursor", "windsurf", "aider"];
-  for (const agent of agents) {
-    const outputFile = GENERATORS[agent].outputFile;
-    const outputPath = join(outputDir, outputFile);
-
-    if (!existsSync(outputPath)) {
-      // If any config file is missing, consider constitution newer
-      return true;
-    }
-
-    const outputStat = Bun.file(outputPath);
-    const outputMtime = outputStat.lastModified;
-
-    if (constitutionMtime > outputMtime) {
-      return true;
-    }
-  }
-
-  return false;
-}

package/src/constitution/index.ts

@@ -7,4 +7,5 @@
  */
 
 export type { ConstitutionConfig, ConstitutionResult } from "./types";
-export { loadConstitution, estimateTokens, truncateToTokens } from "./loader";
+export { loadConstitution, truncateToTokens } from "./loader";
+export { estimateTokens } from "../optimizer/types";

package/src/constitution/loader.ts

@@ -8,21 +8,9 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { validateFilePath } from "../config/path-security";
 import { globalConfigDir } from "../config/paths";
+import { estimateTokens } from "../optimizer/types";
 import type { ConstitutionConfig, ConstitutionResult } from "./types";
 
-/**
- * Estimate token count for text
- *
- * Uses simple heuristic: 1 token ≈ 3 characters (conservative estimate)
- * This is a rough approximation sufficient for quota management.
- *
- * @param text - Text to estimate tokens for
- * @returns Estimated token count
- */
-export function estimateTokens(text: string): number {
-  return Math.ceil(text.length / 3);
-}
-
 /**
  * Truncate text to fit within token limit
  *

package/src/context/builder.ts

@@ -7,6 +7,7 @@
 import path from "node:path";
 import type { NaxConfig } from "../config";
 import { getLogger } from "../logger";
+import { estimateTokens } from "../optimizer/types";
 import type { UserStory } from "../prd";
 import { countStories, getContextFiles } from "../prd";
 import { autoDetectContextFiles } from "./auto-detect";
@@ -18,7 +19,6 @@ import {
   createProgressContext,
   createStoryContext,
   createTestCoverageContext,
-  estimateTokens,
 } from "./elements";
 import { generateTestCoverageSummary } from "./test-scanner";
 import type { BuiltContext, ContextBudget, ContextElement, StoryContext } from "./types";
@@ -30,7 +30,6 @@ export const _deps = {
 
 // Re-export for backward compatibility
 export {
-  estimateTokens,
   createStoryContext,
   createDependencyContext,
   createErrorContext,

package/src/context/elements.ts

@@ -5,21 +5,10 @@
  */
 
 import { getLogger } from "../logger";
+import { estimateTokens } from "../optimizer/types";
 import type { StructuredFailure, UserStory } from "../prd";
 import type { ContextElement } from "./types";
 
-/**
- * Approximate character-to-token ratio for token estimation.
- * Value of 3 is a middle ground optimized for mixed content (prose + code + markdown).
- * Slightly overestimates tokens, preventing budget overflow.
- */
-const CHARS_PER_TOKEN = 3;
-
-/** Estimate token count for text using character-to-token ratio. */
-export function estimateTokens(text: string): number {
-  return Math.ceil(text.length / CHARS_PER_TOKEN);
-}
-
 /** Create context element from current story */
 export function createStoryContext(story: UserStory, priority: number): ContextElement {
   const content = formatStoryAsText(story);

package/src/context/generator.ts

@@ -11,7 +11,9 @@ import type { NaxConfig } from "../config";
 import { validateFilePath } from "../config/path-security";
 import { aiderGenerator } from "./generators/aider";
 import { claudeGenerator } from "./generators/claude";
+import { codexGenerator } from "./generators/codex";
 import { cursorGenerator } from "./generators/cursor";
+import { geminiGenerator } from "./generators/gemini";
 import { opencodeGenerator } from "./generators/opencode";
 import { windsurfGenerator } from "./generators/windsurf";
 import { buildProjectMetadata } from "./injector";
@@ -20,10 +22,12 @@ import type { AgentContextGenerator, AgentType, ContextContent, GeneratorMap } f
 /** Generator registry */
 const GENERATORS: GeneratorMap = {
   claude: claudeGenerator,
+  codex: codexGenerator,
   opencode: opencodeGenerator,
   cursor: cursorGenerator,
   windsurf: windsurfGenerator,
   aider: aiderGenerator,
+  gemini: geminiGenerator,
 };
 
 /** Generation result for a single agent */

package/src/context/generators/codex.ts

@@ -0,0 +1,28 @@
+/**
+ * Codex Config Generator (v0.16.1)
+ *
+ * Generates codex.md from nax/context.md + auto-injected metadata.
+ */
+
+import { formatMetadataSection } from "../injector";
+import type { AgentContextGenerator, ContextContent } from "../types";
+
+function generateCodexConfig(context: ContextContent): string {
+  const header = `# Codex Instructions
+
+This file is auto-generated from \`nax/context.md\`.
+DO NOT EDIT MANUALLY — run \`nax generate\` to regenerate.
+
+---
+
+`;
+
+  const metaSection = context.metadata ? formatMetadataSection(context.metadata) : "";
+  return header + metaSection + context.markdown;
+}
+
+export const codexGenerator: AgentContextGenerator = {
+  name: "codex",
+  outputFile: "codex.md",
+  generate: generateCodexConfig,
+};

package/src/context/generators/gemini.ts

@@ -0,0 +1,28 @@
+/**
+ * Gemini CLI Config Generator (v0.16.1)
+ *
+ * Generates GEMINI.md from nax/context.md + auto-injected metadata.
+ */
+
+import { formatMetadataSection } from "../injector";
+import type { AgentContextGenerator, ContextContent } from "../types";
+
+function generateGeminiConfig(context: ContextContent): string {
+  const header = `# Gemini CLI Context
+
+This file is auto-generated from \`nax/context.md\`.
+DO NOT EDIT MANUALLY — run \`nax generate\` to regenerate.
+
+---
+
+`;
+
+  const metaSection = context.metadata ? formatMetadataSection(context.metadata) : "";
+  return header + metaSection + context.markdown;
+}
+
+export const geminiGenerator: AgentContextGenerator = {
+  name: "gemini",
+  outputFile: "GEMINI.md",
+  generate: generateGeminiConfig,
+};

package/src/context/index.ts

@@ -5,7 +5,6 @@
 export type { ContextElement, ContextBudget, StoryContext, BuiltContext } from "./types";
 
 export {
-  estimateTokens,
   createStoryContext,
   createDependencyContext,
   createErrorContext,
@@ -17,6 +16,8 @@ export {
   formatContextAsMarkdown,
 } from "./builder";
 
+export { estimateTokens } from "../optimizer/types";
+
 export {
   generateTestCoverageSummary,
   scanTestFiles,

package/src/context/test-scanner.ts

@@ -9,7 +9,7 @@
 import path from "node:path";
 import { Glob } from "bun";
 import { getLogger } from "../logger";
-import { estimateTokens } from "./builder";
+import { estimateTokens } from "../optimizer/types";
 
 // ============================================================================
 // Types

package/src/context/types.ts

@@ -40,7 +40,7 @@ export interface AgentContextGenerator {
 }
 
 /** All available generator types */
-export type AgentType = "claude" | "opencode" | "cursor" | "windsurf" | "aider";
+export type AgentType = "claude" | "codex" | "opencode" | "cursor" | "windsurf" | "aider" | "gemini";
 
 /** Generator registry map */
 export type GeneratorMap = Record<AgentType, AgentContextGenerator>;

package/src/interaction/chain.ts

@@ -86,11 +86,27 @@ export class InteractionChain {
   }
 
   /**
-   * Send and receive in one call (convenience method)
+   * Send and receive in one call (convenience method).
+   *
+   * Normalizes "choose" type responses: when the plugin returns
+   * `action: "choose"` + `value: "<key>"`, remaps action to the selected
+   * option key so all consumers can switch on action directly without
+   * needing to inspect value themselves.
    */
   async prompt(request: InteractionRequest): Promise<InteractionResponse> {
     await this.send(request);
     const response = await this.receive(request.id, request.timeout);
+
+    // Normalize choose responses: action="choose" means the user picked an option;
+    // the actual selection is in value. Remap to the selected key if it matches
+    // one of the declared options.
+    if (response.action === "choose" && response.value && request.options) {
+      const matched = request.options.find((o) => o.key === response.value);
+      if (matched) {
+        return { ...response, action: matched.key as InteractionResponse["action"] };
+      }
+    }
+
     return response;
   }
 

package/src/pipeline/stages/execution.ts

@@ -36,7 +36,7 @@ import { checkMergeConflict, checkStoryAmbiguity, isTriggerEnabled } from "../..
 import { getLogger } from "../../logger";
 import type { FailureCategory } from "../../tdd";
 import { runThreeSessionTdd } from "../../tdd";
-import { detectMergeConflict } from "../../utils/git";
+import { autoCommitIfDirty, detectMergeConflict } from "../../utils/git";
 import type { PipelineContext, PipelineStage, StageResult } from "../types";
 
 /**
@@ -134,6 +134,7 @@ export const executionStage: PipelineStage = {
         workdir: ctx.workdir,
         modelTier: ctx.routing.modelTier,
         contextMarkdown: ctx.contextMarkdown,
+        constitution: ctx.constitution?.content,
         dryRun: false,
         lite: isLiteMode,
       });
@@ -156,7 +157,7 @@ export const executionStage: PipelineStage = {
         // Store failure category in context for runner to use at max-attempts decision
         ctx.tddFailureCategory = tddResult.failureCategory;
 
-        // Log needsHumanReview context when present
+        // Log and notify when human review is needed
         if (tddResult.needsHumanReview) {
           logger.warn("execution", "Human review needed", {
             storyId: ctx.story.id,
@@ -164,6 +165,27 @@ export const executionStage: PipelineStage = {
             lite: tddResult.lite,
             failureCategory: tddResult.failureCategory,
           });
+          // Send notification via interaction chain (Telegram in headless mode)
+          if (ctx.interaction) {
+            try {
+              await ctx.interaction.send({
+                id: `human-review-${ctx.story.id}-${Date.now()}`,
+                type: "notify",
+                featureName: ctx.featureDir ? (ctx.featureDir.split("/").pop() ?? "unknown") : "unknown",
+                storyId: ctx.story.id,
+                stage: "execution",
+                summary: `⚠️ Human review needed: ${ctx.story.id}`,
+                detail: `Story: ${ctx.story.title}\nReason: ${tddResult.reviewReason ?? "No reason provided"}\nCategory: ${tddResult.failureCategory ?? "unknown"}`,
+                fallback: "continue",
+                createdAt: Date.now(),
+              });
+            } catch (notifyErr) {
+              logger.warn("execution", "Failed to send human review notification", {
+                storyId: ctx.story.id,
+                error: String(notifyErr),
+              });
+            }
+          }
         }
 
         return routeTddFailure(tddResult.failureCategory, isLiteMode, ctx, tddResult.reviewReason);
@@ -200,7 +222,7 @@ export const executionStage: PipelineStage = {
     ctx.agentResult = result;
 
     // BUG-058: Auto-commit if agent left uncommitted changes (single-session/test-after)
-    await autoCommitIfDirty(ctx.workdir, "single-session", ctx.story.id);
+    await autoCommitIfDirty(ctx.workdir, "execution", "single-session", ctx.story.id);
 
     // merge-conflict trigger: detect CONFLICT markers in agent output
     const combinedOutput = (result.output ?? "") + (result.stderr ?? "");
@@ -270,40 +292,3 @@ export const _executionDeps = {
   isAmbiguousOutput,
   checkStoryAmbiguity,
 };
-
-/**
- * BUG-058: Auto-commit safety net for single-session/test-after.
- * Mirrors the same function in tdd/session-runner.ts for three-session TDD.
- */
-async function autoCommitIfDirty(workdir: string, role: string, storyId: string): Promise<void> {
-  try {
-    const statusProc = Bun.spawn(["git", "status", "--porcelain"], {
-      cwd: workdir,
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    const statusOutput = await new Response(statusProc.stdout).text();
-    await statusProc.exited;
-
-    if (!statusOutput.trim()) return;
-
-    const logger = getLogger();
-    logger.warn("execution", `Agent did not commit after ${role} session — auto-committing`, {
-      role,
-      storyId,
-      dirtyFiles: statusOutput.trim().split("\n").length,
-    });
-
-    const addProc = Bun.spawn(["git", "add", "-A"], { cwd: workdir, stdout: "pipe", stderr: "pipe" });
-    await addProc.exited;
-
-    const commitProc = Bun.spawn(["git", "commit", "-m", `chore(${storyId}): auto-commit after ${role} session`], {
-      cwd: workdir,
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    await commitProc.exited;
-  } catch {
-    // Silently ignore — auto-commit is best-effort
-  }
-}

package/src/pipeline/stages/routing.ts

@@ -25,6 +25,7 @@
  * ```
  */
 
+import { getAgent } from "../../agents/registry";
 import type { NaxConfig } from "../../config";
 import { isGreenfieldStory } from "../../context/greenfield";
 import { applyDecomposition } from "../../decompose/apply";
@@ -68,6 +69,10 @@ export const routingStage: PipelineStage = {
   async execute(ctx: PipelineContext): Promise<StageResult> {
     const logger = getLogger();
 
+    // Resolve agent adapter for LLM routing (shared with execution)
+    const agentName = ctx.config.execution?.agent ?? "claude";
+    const adapter = _routingDeps.getAgent(agentName);
+
     // Staleness detection (RRP-003):
     // - story.routing absent                   → cache miss (no prior routing)
     // - story.routing + no contentHash         → legacy cache hit (manual / pre-RRP-003 routing, honor as-is)
@@ -87,7 +92,7 @@ export const routingStage: PipelineStage = {
 
     if (isCacheHit) {
       // Cache hit: legacy routing (no contentHash) or matching contentHash — use cached values
-      routing = await _routingDeps.routeStory(ctx.story, { config: ctx.config }, ctx.workdir, ctx.plugins);
+      routing = await _routingDeps.routeStory(ctx.story, { config: ctx.config, adapter }, ctx.workdir, ctx.plugins);
       // Override with cached values only when they are actually set
       if (ctx.story.routing?.complexity) routing.complexity = ctx.story.routing.complexity;
       // BUG-062: Only honor stored testStrategy for legacy/manual routing (no contentHash).
@@ -106,7 +111,7 @@ export const routingStage: PipelineStage = {
       }
     } else {
       // Cache miss: no routing, or contentHash present but mismatched — fresh classification
-      routing = await _routingDeps.routeStory(ctx.story, { config: ctx.config }, ctx.workdir, ctx.plugins);
+      routing = await _routingDeps.routeStory(ctx.story, { config: ctx.config, adapter }, ctx.workdir, ctx.plugins);
       // currentHash already computed if a mismatch was detected; compute now if starting fresh
       currentHash = currentHash ?? _routingDeps.computeStoryContentHash(ctx.story);
       ctx.story.routing = {
@@ -223,4 +228,5 @@ export const _routingDeps = {
   applyDecomposition,
   runDecompose,
   checkStoryOversized,
+  getAgent,
 };

package/src/precheck/checks-agents.ts

@@ -0,0 +1,63 @@
+/**
+ * Precheck for multi-agent health
+ *
+ * Detects installed agents, reports version information,
+ * and checks health status for each configured agent.
+ */
+
+import { getAgentVersions } from "../agents/version-detection";
+import type { Check } from "./types";
+
+/**
+ * Check multi-agent health: installed agents and their versions
+ *
+ * This is a Tier 2 warning check. Reports which agents are available
+ * and their versions, but doesn't fail if no agents are installed
+ * (since the main configured agent is checked in Tier 1).
+ */
+export async function checkMultiAgentHealth(): Promise<Check> {
+  try {
+    const versions = await getAgentVersions();
+
+    // Separate installed from not installed
+    const installed = versions.filter((v) => v.installed);
+    const notInstalled = versions.filter((v) => !v.installed);
+
+    // Build message with agent status
+    const lines: string[] = [];
+
+    if (installed.length > 0) {
+      lines.push(`Installed agents (${installed.length}):`);
+      for (const agent of installed) {
+        const versionStr = agent.version ? ` v${agent.version}` : " (version unknown)";
+        lines.push(`  • ${agent.displayName}${versionStr}`);
+      }
+    } else {
+      lines.push("No additional agents detected (using default configured agent)");
+    }
+
+    if (notInstalled.length > 0) {
+      lines.push(`\nAvailable but not installed (${notInstalled.length}):`);
+      for (const agent of notInstalled) {
+        lines.push(`  • ${agent.displayName}`);
+      }
+    }
+
+    const message = lines.join("\n");
+
+    return {
+      name: "multi-agent-health",
+      tier: "warning",
+      passed: true, // Always pass - this is informational
+      message,
+    };
+  } catch (error) {
+    // If version detection fails, still pass but report error
+    return {
+      name: "multi-agent-health",
+      tier: "warning",
+      passed: true,
+      message: `Agent detection: ${error instanceof Error ? error.message : "Unknown error"}`,
+    };
+  }
+}

package/src/precheck/checks.ts

@@ -30,3 +30,6 @@ export {
   checkGitignoreCoversNax,
   checkPromptOverrideFiles,
 } from "./checks-warnings";
+
+// Agent checks
+export { checkMultiAgentHealth } from "./checks-agents";