@nathapp/nax 0.34.0 → 0.36.0

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/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/cli/plan.ts

@@ -91,6 +91,7 @@ export async function planCommand(
     inputFile: options.from,
     modelTier,
     modelDef,
+    config,
   };
 
   // Run agent in plan mode

package/src/config/types.ts

@@ -7,7 +7,7 @@
 
 export type Complexity = "simple" | "medium" | "complex" | "expert";
 export type TestStrategy = "test-after" | "tdd-simple" | "three-session-tdd" | "three-session-tdd-lite";
-export type TddStrategy = "auto" | "strict" | "lite" | "off";
+export type TddStrategy = "auto" | "strict" | "lite" | "simple" | "off";
 
 export interface EscalationEntry {
   from: string;
@@ -125,6 +125,8 @@ export interface ExecutionConfig {
   /** Enable smart test runner to scope test runs to changed files (default: true).
    * Accepts boolean for backward compat or a SmartTestRunnerConfig object. */
   smartTestRunner?: boolean | SmartTestRunnerConfig;
+  /** Configured agent binary: claude, codex, opencode, gemini, aider (default: claude) */
+  agent?: string;
 }
 
 /** Quality gate config */

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/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/init.ts

@@ -41,18 +41,20 @@ function createInteractionPlugin(pluginName: string): InteractionPlugin {
 export async function initInteractionChain(config: NaxConfig, headless: boolean): Promise<InteractionChain | null> {
   const logger = getSafeLogger();
 
-  // If headless mode, skip interaction system
-  if (headless) {
-    logger?.debug("interaction", "Headless mode - skipping interaction system");
-    return null;
-  }
-
   // If no interaction config, skip
   if (!config.interaction) {
     logger?.debug("interaction", "No interaction config - skipping interaction system");
     return null;
   }
 
+  // In headless mode, skip CLI plugin only — it requires stdin (TTY).
+  // Telegram and Webhook plugins work via HTTP and don't need a TTY.
+  const pluginName = config.interaction.plugin;
+  if (headless && pluginName === "cli") {
+    logger?.debug("interaction", "Headless mode with CLI plugin - skipping interaction system (stdin unavailable)");
+    return null;
+  }
+
   // Create chain
   const chain = new InteractionChain({
     defaultTimeout: config.interaction.defaults.timeout,
@@ -60,7 +62,6 @@ export async function initInteractionChain(config: NaxConfig, headless: boolean)
   });
 
   // Create and register plugin
-  const pluginName = config.interaction.plugin;
   try {
     const plugin = createInteractionPlugin(pluginName);
     chain.register(plugin, 100);

package/src/interaction/plugins/auto.ts

@@ -6,6 +6,7 @@
  */
 
 import { z } from "zod";
+import type { AgentAdapter } from "../../agents/types";
 import type { NaxConfig } from "../../config";
 import { resolveModel } from "../../config";
 import type { InteractionPlugin, InteractionRequest, InteractionResponse } from "../types";
@@ -40,9 +41,12 @@ interface DecisionResponse {
 
 /**
  * Module-level deps for testability (_deps pattern).
- * Override callLlm in tests to avoid spawning the claude CLI.
+ * Override adapter in tests to mock adapter.complete() without spawning the claude CLI.
+ *
+ * For backward compatibility, also supports _deps.callLlm (deprecated).
  */
 export const _deps = {
+  adapter: null as AgentAdapter | null,
   callLlm: null as ((request: InteractionRequest) => Promise<DecisionResponse>) | null,
 };
 
@@ -71,7 +75,7 @@ export class AutoInteractionPlugin implements InteractionPlugin {
     // No-op — in-process plugin
   }
 
-  async receive(requestId: string, timeout = 60000): Promise<InteractionResponse> {
+  async receive(_requestId: string, _timeout = 60000): Promise<InteractionResponse> {
     // For auto plugin, we need to fetch the request from somewhere
     // In practice, the chain should pass the request to us
     // For now, throw an error since we need the full request
@@ -88,8 +92,23 @@ export class AutoInteractionPlugin implements InteractionPlugin {
     }
 
     try {
-      const callFn = _deps.callLlm ?? this.callLlm.bind(this);
-      const decision = await callFn(request);
+      // Use deprecated callLlm if provided (backward compatibility)
+      if (_deps.callLlm) {
+        const decision = await _deps.callLlm(request);
+        if (decision.confidence < (this.config.confidenceThreshold ?? 0.7)) {
+          return undefined;
+        }
+        return {
+          requestId: request.id,
+          action: decision.action,
+          value: decision.value,
+          respondedBy: "auto-ai",
+          respondedAt: Date.now(),
+        };
+      }
+
+      // Use new adapter-based path
+      const decision = await this.callLlm(request);
 
       // Check confidence threshold
       if (decision.confidence < (this.config.confidenceThreshold ?? 0.7)) {
@@ -114,34 +133,31 @@ export class AutoInteractionPlugin implements InteractionPlugin {
    */
   private async callLlm(request: InteractionRequest): Promise<DecisionResponse> {
     const prompt = this.buildPrompt(request);
-    const modelTier = this.config.model ?? "fast";
 
-    if (!this.config.naxConfig) {
-      throw new Error("Auto plugin requires naxConfig in init()");
+    // Get adapter from dependency injection or throw
+    const adapter = _deps.adapter;
+    if (!adapter) {
+      throw new Error("Auto plugin requires adapter to be injected via _deps.adapter");
     }
 
-    const modelEntry = this.config.naxConfig.models[modelTier];
-    if (!modelEntry) {
-      throw new Error(`Model tier "${modelTier}" not found in config.models`);
+    // Resolve model option if naxConfig is available
+    let modelArg: string | undefined;
+    if (this.config.naxConfig) {
+      const modelTier = this.config.model ?? "fast";
+      const modelEntry = this.config.naxConfig.models[modelTier];
+      if (!modelEntry) {
+        throw new Error(`Model tier "${modelTier}" not found in config.models`);
+      }
+      const modelDef = resolveModel(modelEntry);
+      modelArg = modelDef.model;
     }
 
-    const modelDef = resolveModel(modelEntry);
-    const modelArg = modelDef.model;
-
-    // Spawn claude CLI
-    const proc = Bun.spawn(["claude", "-p", prompt, "--model", modelArg], {
-      stdout: "pipe",
-      stderr: "pipe",
+    // Use adapter.complete() for one-shot LLM call
+    const output = await adapter.complete(prompt, {
+      ...(modelArg && { model: modelArg }),
+      jsonMode: true,
     });
 
-    const [stdout, stderr] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()]);
-
-    const exitCode = await proc.exited;
-    if (exitCode !== 0) {
-      throw new Error(`claude CLI failed with exit code ${exitCode}: ${stderr}`);
-    }
-
-    const output = stdout.trim();
     return this.parseResponse(output);
   }
 

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";
 
 /**
@@ -200,7 +200,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 +270,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,10 +92,13 @@ 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;
-      if (ctx.story.routing?.testStrategy) routing.testStrategy = ctx.story.routing.testStrategy;
+      // BUG-062: Only honor stored testStrategy for legacy/manual routing (no contentHash).
+      // When contentHash exists, the LLM strategy layer already recomputes testStrategy
+      // fresh via determineTestStrategy() — don't clobber it with the stale PRD value.
+      if (!hasContentHash && ctx.story.routing?.testStrategy) routing.testStrategy = ctx.story.routing.testStrategy;
       // BUG-032: Use escalated modelTier if explicitly set (by handleTierEscalation),
       // otherwise derive from complexity + current config
       if (ctx.story.routing?.modelTier) {
@@ -103,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 = {
@@ -220,4 +228,5 @@ export const _routingDeps = {
   applyDecomposition,
   runDecompose,
   checkStoryOversized,
+  getAgent,
 };

package/src/plugins/index.ts

@@ -9,6 +9,7 @@ export type {
   PluginType,
   PluginExtensions,
   PluginConfigEntry,
+  PluginLogger,
   IReviewPlugin,
   ReviewCheckResult,
   IContextProvider,
@@ -29,3 +30,4 @@ export type {
 export { validatePlugin } from "./validator";
 export { loadPlugins } from "./loader";
 export { PluginRegistry } from "./registry";
+export { createPluginLogger } from "./plugin-logger";

package/src/plugins/loader.ts

@@ -11,6 +11,7 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { getSafeLogger as _getSafeLoggerFromModule } from "../logger";
 import { validateModulePath } from "../utils/path-security";
+import { createPluginLogger } from "./plugin-logger";
 import { PluginRegistry } from "./registry";
 import type { NaxPlugin, PluginConfigEntry } from "./types";
 import { validatePlugin } from "./validator";
@@ -272,10 +273,11 @@ async function loadAndValidatePlugin(
       return null;
     }
 
-    // Call setup() if defined
+    // Call setup() if defined — pass plugin-scoped logger
     if (validated.setup) {
       try {
-        await validated.setup(config);
+        const pluginLogger = createPluginLogger(validated.name);
+        await validated.setup(config, pluginLogger);
       } catch (error) {
         const logger = getSafeLogger();
         logger?.error("plugins", `Plugin '${validated.name}' setup failed`, { error });

package/src/plugins/plugin-logger.ts

@@ -0,0 +1,41 @@
+/**
+ * Plugin Logger Factory
+ *
+ * Creates write-only, stage-prefixed loggers for plugins.
+ * Each logger auto-tags entries with `plugin:<name>` so plugin
+ * output is filterable and cannot impersonate core stages.
+ *
+ * @module plugins/plugin-logger
+ */
+
+import { getSafeLogger } from "../logger";
+import type { PluginLogger } from "./types";
+
+/**
+ * Create a PluginLogger scoped to a plugin name.
+ *
+ * The returned logger delegates to the global nax Logger with
+ * `plugin:<pluginName>` as the stage. If the global logger is
+ * not initialized (e.g., during tests), calls are silently dropped.
+ *
+ * @param pluginName - Plugin name used as stage prefix
+ * @returns PluginLogger instance
+ */
+export function createPluginLogger(pluginName: string): PluginLogger {
+  const stage = `plugin:${pluginName}`;
+
+  return {
+    error(message: string, data?: Record<string, unknown>): void {
+      getSafeLogger()?.error(stage, message, data);
+    },
+    warn(message: string, data?: Record<string, unknown>): void {
+      getSafeLogger()?.warn(stage, message, data);
+    },
+    info(message: string, data?: Record<string, unknown>): void {
+      getSafeLogger()?.info(stage, message, data);
+    },
+    debug(message: string, data?: Record<string, unknown>): void {
+      getSafeLogger()?.debug(stage, message, data);
+    },
+  };
+}

package/src/plugins/types.ts

@@ -61,8 +61,9 @@ export interface NaxPlugin {
    * validating config, establishing connections, etc.
    *
    * @param config - Plugin-specific config from nax config.json
+   * @param logger - Write-only logger scoped to this plugin (stage auto-prefixed as `plugin:<name>`)
    */
-  setup?(config: Record<string, unknown>): Promise<void>;
+  setup?(config: Record<string, unknown>, logger: PluginLogger): Promise<void>;
 
   /**
    * Called when the nax run ends (success or failure).
@@ -333,6 +334,54 @@ export interface IReporter {
   onRunEnd?(event: RunEndEvent): Promise<void>;
 }
 
+// ============================================================================
+// Plugin Logger
+// ============================================================================
+
+/**
+ * Write-only, level-gated logger provided to plugins via setup().
+ *
+ * All log entries are auto-prefixed with `plugin:<name>` as the stage,
+ * so plugins cannot impersonate core nax stages. The interface is
+ * intentionally minimal — plugins only need to emit messages, not
+ * configure log levels or access log files.
+ *
+ * @example
+ * ```ts
+ * let log: PluginLogger;
+ *
+ * const myPlugin: NaxPlugin = {
+ *   name: "my-plugin",
+ *   version: "1.0.0",
+ *   provides: ["reviewer"],
+ *   async setup(config, logger) {
+ *     log = logger;
+ *     log.info("Initialized with config", { keys: Object.keys(config) });
+ *   },
+ *   extensions: {
+ *     reviewer: {
+ *       name: "my-check",
+ *       description: "Custom check",
+ *       async check(workdir, changedFiles) {
+ *         log.debug("Scanning files", { count: changedFiles.length });
+ *         // ...
+ *       }
+ *     }
+ *   }
+ * };
+ * ```
+ */
+export interface PluginLogger {
+  /** Log an error message */
+  error(message: string, data?: Record<string, unknown>): void;
+  /** Log a warning message */
+  warn(message: string, data?: Record<string, unknown>): void;
+  /** Log an informational message */
+  info(message: string, data?: Record<string, unknown>): void;
+  /** Log a debug message */
+  debug(message: string, data?: Record<string, unknown>): void;
+}
+
 // ============================================================================
 // Plugin Config
 // ============================================================================

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"}`,
+    };
+  }
+}