@nathapp/nax 0.40.0 → 0.41.0

package/src/agents/acp/types.ts

@@ -0,0 +1,22 @@
+/**
+ * ACP Adapter Types
+ *
+ * Type definitions for the ACP (Agent Communication Protocol) adapter.
+ * The adapter shells out to `acpx` CLI — no in-process ACP client needed.
+ */
+
+import type { ModelTier } from "../../config/schema";
+
+/**
+ * Maps agent names to their acpx registry entries and capabilities.
+ */
+export interface AgentRegistryEntry {
+  /** Agent name in acpx's built-in registry (e.g., 'claude', 'codex', 'gemini') */
+  binary: string;
+  /** Human-readable display name */
+  displayName: string;
+  /** Model tiers this agent supports */
+  supportedTiers: readonly ModelTier[];
+  /** Max context window in tokens */
+  maxContextTokens: number;
+}

package/src/agents/claude-complete.ts

@@ -43,9 +43,9 @@ export async function executeComplete(binary: string, prompt: string, options?:
     cmd.push("--model", options.model);
   }
 
-  if (options?.maxTokens !== undefined) {
-    cmd.push("--max-tokens", String(options.maxTokens));
-  }
+  // Note: Claude Code CLI does not support --max-tokens; the option is accepted in
+  // CompleteOptions for future use or non-Claude adapters, but is intentionally not
+  // forwarded to the claude binary here.
 
   if (options?.jsonMode) {
     cmd.push("--output-format", "json");

package/src/agents/registry.ts

@@ -4,6 +4,9 @@
  * Discovers and manages available coding agents.
  */
 
+import type { NaxConfig } from "../config/schema";
+import { getLogger } from "../logger";
+import { AcpAgentAdapter } from "./acp/adapter";
 import { AiderAdapter } from "./adapters/aider";
 import { CodexAdapter } from "./adapters/codex";
 import { GeminiAdapter } from "./adapters/gemini";
@@ -51,3 +54,83 @@ export async function checkAgentHealth(): Promise<Array<{ name: string; displayN
     })),
   );
 }
+
+/** Protocol-aware agent registry returned by createAgentRegistry() */
+export interface AgentRegistry {
+  /** Get a specific agent, respecting the configured protocol */
+  getAgent(name: string): AgentAdapter | undefined;
+  /** Get all installed agents */
+  getInstalledAgents(): Promise<AgentAdapter[]>;
+  /** Check health of all agents */
+  checkAgentHealth(): Promise<Array<{ name: string; displayName: string; installed: boolean }>>;
+  /** Active protocol ('acp' | 'cli') */
+  protocol: "acp" | "cli";
+}
+
+/**
+ * Create a protocol-aware agent registry.
+ *
+ * When config.agent.protocol is 'acp', returns AcpAgentAdapter instances.
+ * When 'cli' (or unset), returns legacy CLI adapters.
+ * AcpAgentAdapter instances are cached per agent name for the lifetime of the registry.
+ */
+export function createAgentRegistry(config: NaxConfig): AgentRegistry {
+  const protocol: "acp" | "cli" = config.agent?.protocol ?? "cli";
+  const logger = getLogger();
+  const acpCache = new Map<string, AcpAgentAdapter>();
+
+  // Log which protocol is being used at startup
+  logger?.info("agents", `Agent protocol: ${protocol}`, { protocol, hasConfig: !!config.agent });
+
+  function getAgent(name: string): AgentAdapter | undefined {
+    if (protocol === "acp") {
+      const known = ALL_AGENTS.find((a) => a.name === name);
+      if (!known) return undefined;
+      if (!acpCache.has(name)) {
+        acpCache.set(name, new AcpAgentAdapter(name));
+        logger?.debug("agents", `Created AcpAgentAdapter for ${name}`, { name, protocol });
+      }
+      return acpCache.get(name);
+    }
+    const adapter = ALL_AGENTS.find((a) => a.name === name);
+    if (adapter) {
+      logger?.debug("agents", `Using CLI adapter for ${name}: ${adapter.constructor.name}`, { name });
+    }
+    return adapter;
+  }
+
+  async function getInstalledAgents(): Promise<AgentAdapter[]> {
+    const agents =
+      protocol === "acp"
+        ? ALL_AGENTS.map((a) => {
+            if (!acpCache.has(a.name)) {
+              acpCache.set(a.name, new AcpAgentAdapter(a.name));
+            }
+            return acpCache.get(a.name) as AcpAgentAdapter;
+          })
+        : ALL_AGENTS;
+    const results = await Promise.all(agents.map(async (agent) => ({ agent, installed: await agent.isInstalled() })));
+    return results.filter((r) => r.installed).map((r) => r.agent);
+  }
+
+  async function checkAgentHealth(): Promise<Array<{ name: string; displayName: string; installed: boolean }>> {
+    const agents =
+      protocol === "acp"
+        ? ALL_AGENTS.map((a) => {
+            if (!acpCache.has(a.name)) {
+              acpCache.set(a.name, new AcpAgentAdapter(a.name));
+            }
+            return acpCache.get(a.name) as AcpAgentAdapter;
+          })
+        : ALL_AGENTS;
+    return Promise.all(
+      agents.map(async (agent) => ({
+        name: agent.name,
+        displayName: agent.displayName,
+        installed: await agent.isInstalled(),
+      })),
+    );
+  }
+
+  return { getAgent, getInstalledAgents, checkAgentHealth, protocol };
+}

package/src/agents/types-extended.ts

@@ -30,6 +30,29 @@ export interface PlanOptions {
   modelDef?: ModelDef;
   /** Global config — used to resolve models.balanced when modelDef is absent */
   config?: Partial<NaxConfig>;
+  /**
+   * Interaction bridge for mid-session human Q&A (ACP only).
+   * If provided, the agent can pause and ask clarifying questions during planning.
+   */
+  interactionBridge?: {
+    detectQuestion: (text: string) => Promise<boolean>;
+    onQuestionDetected: (text: string) => Promise<string>;
+  };
+  /** Feature name for ACP session naming (plan→run continuity) */
+  featureName?: string;
+  /** Story ID for ACP session naming (plan→run continuity) */
+  storyId?: string;
+  /** Session role for TDD isolation (e.g. "test-writer" | "implementer" | "verifier") */
+  sessionRole?: string;
+  /** Timeout in seconds — inherited from config.execution.sessionTimeoutSeconds */
+  timeoutSeconds?: number;
+  /** Whether to skip permission prompts (maps to permissionMode in ACP) */
+  dangerouslySkipPermissions?: boolean;
+  /**
+   * Callback invoked with the ACP session name after the session is created.
+   * Used to persist the name to status.json for plan→run session continuity.
+   */
+  onAcpSessionCreated?: (sessionName: string) => Promise<void> | void;
 }
 
 /**

package/src/agents/types.ts

@@ -59,6 +59,21 @@ export interface AgentRunOptions {
   env?: Record<string, string>;
   /** Use --dangerously-skip-permissions flag (default: true) */
   dangerouslySkipPermissions?: boolean;
+  /** Interaction bridge for mid-session human interaction (ACP) */
+  interactionBridge?: {
+    detectQuestion: (text: string) => Promise<boolean>;
+    onQuestionDetected: (text: string) => Promise<string>;
+  };
+  /** PID registry for cleanup on crash/SIGTERM */
+  pidRegistry?: import("../execution/pid-registry").PidRegistry;
+  /** ACP session name to resume for plan→run session continuity */
+  acpSessionName?: string;
+  /** Feature name for ACP session naming and logging */
+  featureName?: string;
+  /** Story ID for ACP session naming and logging */
+  storyId?: string;
+  /** Session role for TDD isolation (e.g. "test-writer" | "implementer" | "verifier") */
+  sessionRole?: string;
 }
 
 /**
@@ -83,6 +98,8 @@ export interface CompleteOptions {
   jsonMode?: boolean;
   /** Override the model (adds --model flag) */
   model?: string;
+  /** Whether to skip permission prompts (maps to permissionMode in ACP) */
+  dangerouslySkipPermissions?: boolean;
 }
 
 /**

package/src/cli/analyze.ts

@@ -223,9 +223,13 @@ async function runDecomposeDefault(
     maxComplexity: naxDecompose?.maxSubstoryComplexity ?? "medium",
     maxRetries: naxDecompose?.maxRetries ?? 2,
   };
+  const agent = getAgent(config.autoMode.defaultAgent);
+  if (!agent) {
+    throw new Error(`[decompose] Agent "${config.autoMode.defaultAgent}" not found — cannot decompose`);
+  }
   const adapter = {
-    async decompose(_prompt: string): Promise<string> {
-      throw new Error("[decompose] No LLM adapter configured for story decomposition");
+    async decompose(prompt: string): Promise<string> {
+      return agent.complete(prompt, { jsonMode: true });
     },
   };
   return DecomposeBuilder.for(story).prd(prd).config(builderConfig).decompose(adapter);

package/src/cli/init-detect.ts

@@ -5,12 +5,74 @@
  * for nax/config.json.
  */
 
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 /** Detected project runtime */
 export type Runtime = "bun" | "node" | "unknown";
 
+/** Detected UI framework */
+export type UIFramework = "ink" | "react" | "vue" | "svelte";
+
+/** Full stack info including UI framework and bin detection */
+export interface StackInfo extends ProjectStack {
+  uiFramework?: UIFramework;
+  hasBin?: boolean;
+}
+
+/** Shape of a parsed package.json for detection purposes */
+interface PackageJson {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  bin?: Record<string, string> | string;
+}
+
+function readPackageJson(projectRoot: string): PackageJson | undefined {
+  const pkgPath = join(projectRoot, "package.json");
+  if (!existsSync(pkgPath)) return undefined;
+  try {
+    return JSON.parse(readFileSync(pkgPath, "utf-8")) as PackageJson;
+  } catch {
+    return undefined;
+  }
+}
+
+function allDeps(pkg: PackageJson): Record<string, string> {
+  return {
+    ...pkg.dependencies,
+    ...pkg.devDependencies,
+    ...pkg.peerDependencies,
+  };
+}
+
+function detectUIFramework(pkg: PackageJson): UIFramework | undefined {
+  const deps = allDeps(pkg);
+  if ("ink" in deps) return "ink";
+  if ("react" in deps || "next" in deps) return "react";
+  if ("vue" in deps || "nuxt" in deps) return "vue";
+  if ("svelte" in deps || "@sveltejs/kit" in deps) return "svelte";
+  return undefined;
+}
+
+function detectHasBin(pkg: PackageJson): boolean {
+  return pkg.bin !== undefined;
+}
+
+/**
+ * Detect the project stack including UI framework from package.json.
+ */
+export function detectStack(projectRoot: string): StackInfo {
+  const base = detectProjectStack(projectRoot);
+  const pkg = readPackageJson(projectRoot);
+  if (!pkg) return base;
+  return {
+    ...base,
+    uiFramework: detectUIFramework(pkg),
+    hasBin: detectHasBin(pkg) || undefined,
+  };
+}
+
 /** Detected project language */
 export type Language = "typescript" | "python" | "rust" | "go" | "unknown";
 
@@ -146,24 +208,48 @@ function isStackDetected(stack: ProjectStack): boolean {
   return stack.runtime !== "unknown" || stack.language !== "unknown";
 }
 
+/** Build the acceptance config section from StackInfo, or undefined if not applicable. */
+function buildAcceptanceConfig(stack: StackInfo): { testStrategy: string; testFramework?: string } | undefined {
+  if (stack.uiFramework === "ink") {
+    return { testStrategy: "component", testFramework: "ink-testing-library" };
+  }
+  if (stack.uiFramework === "react") {
+    return { testStrategy: "component", testFramework: "@testing-library/react" };
+  }
+  if (stack.uiFramework === "vue") {
+    return { testStrategy: "component", testFramework: "@testing-library/vue" };
+  }
+  if (stack.uiFramework === "svelte") {
+    return { testStrategy: "component", testFramework: "@testing-library/svelte" };
+  }
+  if (stack.hasBin) {
+    const testFramework = stack.runtime === "bun" ? "bun:test" : "jest";
+    return { testStrategy: "cli", testFramework };
+  }
+  return undefined;
+}
+
 /**
  * Build the full init config object from a detected project stack.
  * Falls back to minimal config when stack is undetected.
  */
-export function buildInitConfig(stack: ProjectStack): object {
+export function buildInitConfig(stack: ProjectStack | StackInfo): object {
+  const stackInfo = stack as StackInfo;
+  const acceptance = buildAcceptanceConfig(stackInfo);
+
   if (!isStackDetected(stack)) {
-    return { version: 1 };
+    return acceptance ? { version: 1, acceptance } : { version: 1 };
   }
 
   const commands = buildQualityCommands(stack);
   const hasCommands = Object.keys(commands).length > 0;
 
-  if (!hasCommands) {
+  if (!hasCommands && !acceptance) {
     return { version: 1 };
   }
 
-  return {
-    version: 1,
-    quality: { commands },
-  };
+  const config: Record<string, unknown> = { version: 1 };
+  if (hasCommands) config.quality = { commands };
+  if (acceptance) config.acceptance = acceptance;
+  return config;
 }

package/src/cli/init.ts

@@ -10,7 +10,7 @@ import { join } from "node:path";
 import { globalConfigDir, projectConfigDir } from "../config/paths";
 import { getLogger } from "../logger";
 import { initContext } from "./init-context";
-import { buildInitConfig, detectProjectStack } from "./init-detect";
+import { buildInitConfig, detectStack } from "./init-detect";
 import type { ProjectStack } from "./init-detect";
 import { promptsInitCommand } from "./prompts";
 
@@ -183,7 +183,7 @@ export async function initProject(projectRoot: string, options?: InitProjectOpti
   }
 
   // Detect project stack and build config
-  const stack = detectProjectStack(projectRoot);
+  const stack = detectStack(projectRoot);
   const projectConfig = buildInitConfig(stack);
   logger.info("init", "Detected project stack", {
     runtime: stack.runtime,

package/src/cli/plan.ts

@@ -7,6 +7,7 @@
 
 import { existsSync } from "node:fs";
 import { join } from "node:path";
+import { createInterface } from "node:readline";
 import { ClaudeCodeAdapter } from "../agents/claude";
 import type { PlanOptions } from "../agents/types";
 import { scanCodebase } from "../analyze/scanner";
@@ -14,6 +15,26 @@ import type { NaxConfig } from "../config";
 import { resolveModel } from "../config/schema";
 import { getLogger } from "../logger";
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Question detection helpers for ACP interaction bridge
+// ─────────────────────────────────────────────────────────────────────────────
+
+const QUESTION_PATTERNS = [/\?[\s]*$/, /\bwhich\b/i, /\bshould i\b/i, /\bdo you want\b/i, /\bwould you like\b/i];
+
+async function detectQuestion(text: string): Promise<boolean> {
+  return QUESTION_PATTERNS.some((p) => p.test(text.trim()));
+}
+
+async function askHuman(question: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(`\n[Agent asks]: ${question}\nYour answer: `, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
 /**
  * Template for structured specification output.
  *
@@ -92,6 +113,8 @@ export async function planCommand(
     modelTier,
     modelDef,
     config,
+    // Wire ACP interaction bridge for mid-session Q&A (only in interactive mode)
+    interactionBridge: interactive ? { detectQuestion, onQuestionDetected: askHuman } : undefined,
   };
 
   // Run agent in plan mode

package/src/config/defaults.ts

@@ -203,6 +203,7 @@ export const DEFAULT_CONFIG: NaxConfig = {
     },
   },
   prompts: {},
+  // agent: intentionally omitted — cli is the default when no agent config is set
   decompose: {
     trigger: "auto",
     maxAcceptanceCriteria: 6,

package/src/config/index.ts

@@ -14,7 +14,7 @@ export type {
   TierConfig,
   RectificationConfig,
 } from "./schema";
-export { DEFAULT_CONFIG, resolveModel, NaxConfigSchema } from "./schema";
+export { DEFAULT_CONFIG, resolveModel, NaxConfigSchema, AcceptanceConfigSchema } from "./schema";
 export { loadConfig, findProjectDir, globalConfigPath } from "./loader";
 export { validateConfig, type ValidationResult } from "./validate"; // @deprecated: Use NaxConfigSchema.safeParse() instead
 export { validateDirectory, validateFilePath, isWithinDirectory, MAX_DIRECTORY_DEPTH } from "./path-security";

package/src/config/runtime-types.ts

@@ -228,6 +228,9 @@ export interface PlanConfig {
   outputPath: string;
 }
 
+/** Valid test strategy values for acceptance testing */
+export type AcceptanceTestStrategy = "unit" | "component" | "cli" | "e2e" | "snapshot";
+
 /** Acceptance validation config */
 export interface AcceptanceConfig {
   /** Enable acceptance test generation and validation */
@@ -244,6 +247,10 @@ export interface AcceptanceConfig {
   refinement: boolean;
   /** Whether to run RED gate check after generating acceptance tests (default: true) */
   redGate: boolean;
+  /** Test strategy for acceptance tests (default: auto-detect) */
+  testStrategy?: AcceptanceTestStrategy;
+  /** Test framework for acceptance tests (default: auto-detect) */
+  testFramework?: string;
 }
 
 /** Optimizer config (v0.10) */
@@ -458,4 +465,14 @@ export interface NaxConfig {
   prompts?: PromptsConfig;
   /** Decompose settings (SD-003) */
   decompose?: DecomposeConfig;
+  /** Agent protocol settings (ACP-003) */
+  agent?: AgentConfig;
+}
+
+/** Agent protocol configuration (ACP-003) */
+export interface AgentConfig {
+  /** Protocol to use for agent communication (default: 'acp') */
+  protocol?: "acp" | "cli";
+  /** ACP permission mode (default: 'approve-all') */
+  acpPermissionMode?: string;
 }

package/src/config/schema.ts

@@ -30,6 +30,7 @@ export type {
   ReviewConfig,
   PlanConfig,
   AcceptanceConfig,
+  AcceptanceTestStrategy,
   OptimizerConfig,
   PluginConfigEntry,
   HooksConfig,
@@ -47,12 +48,13 @@ export type {
   SmartTestRunnerConfig,
   DecomposeConfig,
   NaxConfig,
+  AgentConfig,
 } from "./types";
 
 export { resolveModel } from "./types";
 
 // Zod schemas
-export { NaxConfigSchema } from "./schemas";
+export { NaxConfigSchema, AcceptanceConfigSchema } from "./schemas";
 
 // Default config
 export { DEFAULT_CONFIG } from "./defaults";

package/src/config/schemas.ts

@@ -210,7 +210,7 @@ const PlanConfigSchema = z.object({
   outputPath: z.string().min(1, "plan.outputPath must be non-empty"),
 });
 
-const AcceptanceConfigSchema = z.object({
+export const AcceptanceConfigSchema = z.object({
   enabled: z.boolean(),
   maxRetries: z.number().int().nonnegative(),
   generateTests: z.boolean(),
@@ -218,6 +218,8 @@ const AcceptanceConfigSchema = z.object({
   model: z.enum(["fast", "balanced", "powerful"]).default("fast"),
   refinement: z.boolean().default(true),
   redGate: z.boolean().default(true),
+  testStrategy: z.enum(["unit", "component", "cli", "e2e", "snapshot"]).optional(),
+  testFramework: z.string().min(1, "acceptance.testFramework must be non-empty").optional(),
 });
 
 const TestCoverageConfigSchema = z.object({
@@ -324,6 +326,11 @@ const StorySizeGateConfigSchema = z.object({
   maxBulletPoints: z.number().int().min(1).max(100).default(8),
 });
 
+const AgentConfigSchema = z.object({
+  protocol: z.enum(["acp", "cli"]).default("acp"),
+  acpPermissionMode: z.string().optional(),
+});
+
 const PrecheckConfigSchema = z.object({
   storySizeGate: StorySizeGateConfigSchema,
 });
@@ -370,6 +377,7 @@ export const NaxConfigSchema = z
     disabledPlugins: z.array(z.string()).optional(),
     hooks: HooksConfigSchema.optional(),
     interaction: InteractionConfigSchema.optional(),
+    agent: AgentConfigSchema.optional(),
     precheck: PrecheckConfigSchema.optional(),
     prompts: PromptsConfigSchema.optional(),
     decompose: DecomposeConfigSchema.optional(),

package/src/config/types.ts

@@ -24,6 +24,7 @@ export { resolveModel } from "./schema-types";
 // Runtime types
 export type {
   AcceptanceConfig,
+  AcceptanceTestStrategy,
   AnalyzeConfig,
   AutoModeConfig,
   ConstitutionConfig,
@@ -51,4 +52,5 @@ export type {
   TddConfig,
   TestCoverageConfig,
   AdaptiveRoutingConfig,
+  AgentConfig,
 } from "./runtime-types";

package/src/execution/executor-types.ts

@@ -10,10 +10,12 @@ import type { InteractionChain } from "../interaction/chain";
 import type { StoryMetrics } from "../metrics";
 import type { PipelineEventEmitter } from "../pipeline/events";
 import type { RoutingResult } from "../pipeline/types";
+import type { AgentGetFn } from "../pipeline/types";
 import type { PluginRegistry } from "../plugins";
 import type { PRD, UserStory } from "../prd/types";
 import type { StoryBatch } from "./batching";
 import type { DeferredReviewResult } from "./deferred-review";
+import type { PidRegistry } from "./pid-registry";
 import type { StatusWriter } from "./status-writer";
 
 export interface SequentialExecutionContext {
@@ -33,6 +35,10 @@ export interface SequentialExecutionContext {
   startTime: number;
   batchPlan: StoryBatch[];
   interactionChain?: InteractionChain | null;
+  /** Protocol-aware agent resolver (ACP wiring). Falls back to standalone getAgent when absent. */
+  agentGetFn?: AgentGetFn;
+  /** PID registry for crash recovery — register child PIDs so they can be killed on SIGTERM. */
+  pidRegistry?: PidRegistry;
 }
 
 export interface SequentialExecutionResult {

package/src/execution/iteration-runner.ts

@@ -78,6 +78,8 @@ export async function runIteration(
     storyStartTime: new Date().toISOString(),
     storyGitRef: storyGitRef ?? undefined,
     interaction: ctx.interactionChain ?? undefined,
+    agentGetFn: ctx.agentGetFn,
+    pidRegistry: ctx.pidRegistry,
     accumulatedAttemptCost: accumulatedAttemptCost > 0 ? accumulatedAttemptCost : undefined,
   };
 

package/src/execution/lifecycle/acceptance-loop.ts

@@ -10,7 +10,6 @@
 
 import path from "node:path";
 import { type FixStory, convertFixStoryToUserStory, generateFixStories } from "../../acceptance";
-import { getAgent } from "../../agents";
 import type { NaxConfig } from "../../config";
 import { resolveModel } from "../../config/schema";
 import { type LoadedHooksConfig, fireHook } from "../../hooks";
@@ -19,6 +18,7 @@ import type { StoryMetrics } from "../../metrics";
 import type { PipelineEventEmitter } from "../../pipeline/events";
 import { runPipeline } from "../../pipeline/runner";
 import { defaultPipeline } from "../../pipeline/stages";
+import type { AgentGetFn } from "../../pipeline/types";
 import type { PipelineContext, RoutingResult } from "../../pipeline/types";
 import type { PluginRegistry } from "../../plugins";
 import { loadPRD, savePRD } from "../../prd";
@@ -42,6 +42,8 @@ export interface AcceptanceLoopContext {
   pluginRegistry: PluginRegistry;
   eventEmitter?: PipelineEventEmitter;
   statusWriter: StatusWriter;
+  /** Protocol-aware agent resolver — passed from registry at run start */
+  agentGetFn?: AgentGetFn;
 }
 
 export interface AcceptanceLoopResult {
@@ -80,7 +82,8 @@ async function generateAndAddFixStories(
   prd: PRD,
 ): Promise<FixStory[] | null> {
   const logger = getSafeLogger();
-  const agent = getAgent(ctx.config.autoMode.defaultAgent);
+  const { getAgent } = await import("../../agents");
+  const agent = (ctx.agentGetFn ?? getAgent)(ctx.config.autoMode.defaultAgent);
   if (!agent) {
     logger?.error("acceptance", "Agent not found, cannot generate fix stories");
     return null;

package/src/execution/lifecycle/run-initialization.ts

@@ -9,10 +9,10 @@
  */
 
 import chalk from "chalk";
-import { getAgent } from "../../agents";
 import type { NaxConfig } from "../../config";
 import { AgentNotFoundError, AgentNotInstalledError, StoryLimitExceededError } from "../../errors";
 import { getSafeLogger } from "../../logger";
+import type { AgentGetFn } from "../../pipeline/types";
 import { countStories, loadPRD, markStoryPassed, savePRD } from "../../prd";
 import type { PRD } from "../../prd/types";
 import { hasCommitsForStory } from "../../utils/git";
@@ -22,6 +22,8 @@ export interface InitializationContext {
   prdPath: string;
   workdir: string;
   dryRun: boolean;
+  /** Protocol-aware agent resolver — passed from registry at run start */
+  agentGetFn?: AgentGetFn;
 }
 
 export interface InitializationResult {
@@ -74,11 +76,12 @@ async function reconcileState(prd: PRD, prdPath: string, workdir: string): Promi
 /**
  * Validate agent installation
  */
-async function checkAgentInstalled(config: NaxConfig, dryRun: boolean): Promise<void> {
+async function checkAgentInstalled(config: NaxConfig, dryRun: boolean, agentGetFn?: AgentGetFn): Promise<void> {
   if (dryRun) return;
 
   const logger = getSafeLogger();
-  const agent = getAgent(config.autoMode.defaultAgent);
+  const { getAgent } = await import("../../agents");
+  const agent = (agentGetFn ?? getAgent)(config.autoMode.defaultAgent);
 
   if (!agent) {
     logger?.error("execution", "Agent not found", {
@@ -114,6 +117,15 @@ function validateStoryCount(counts: ReturnType<typeof countStories>, config: Nax
   }
 }
 
+/**
+ * Log the active agent protocol to aid debugging.
+ */
+export function logActiveProtocol(config: NaxConfig): void {
+  const logger = getSafeLogger();
+  const protocol = config.agent?.protocol ?? "cli";
+  logger?.info("run-initialization", `Agent protocol: ${protocol}`, { protocol });
+}
+
 /**
  * Initialize execution: validate agent, reconcile state, check limits
  */
@@ -121,7 +133,7 @@ export async function initializeRun(ctx: InitializationContext): Promise<Initial
   const logger = getSafeLogger();
 
   // Check agent installation
-  await checkAgentInstalled(ctx.config, ctx.dryRun);
+  await checkAgentInstalled(ctx.config, ctx.dryRun, ctx.agentGetFn);
 
   // Load and reconcile PRD
   let prd = await loadPRD(ctx.prdPath);