@nathapp/nax 0.40.1 → 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/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/runtime-types.ts

@@ -465,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

@@ -48,6 +48,7 @@ export type {
   SmartTestRunnerConfig,
   DecomposeConfig,
   NaxConfig,
+  AgentConfig,
 } from "./types";
 
 export { resolveModel } from "./types";

package/src/config/schemas.ts

@@ -326,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,
 });
@@ -372,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

@@ -52,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);

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

@@ -22,6 +22,7 @@ import type { InteractionChain } from "../../interaction";
 import { initInteractionChain } from "../../interaction";
 import { getSafeLogger } from "../../logger";
 import { pipelineEventBus } from "../../pipeline/event-bus";
+import type { AgentGetFn } from "../../pipeline/types";
 import { loadPlugins } from "../../plugins/loader";
 import type { PluginRegistry } from "../../plugins/registry";
 import type { PRD } from "../../prd";
@@ -53,6 +54,8 @@ export interface RunSetupOptions {
   // BUG-017: Additional getters for run.complete event on SIGTERM
   getStoriesCompleted: () => number;
   getTotalStories: () => number;
+  /** Protocol-aware agent resolver — passed from runner.ts registry */
+  agentGetFn?: AgentGetFn;
 }
 
 export interface RunSetupResult {
@@ -206,6 +209,7 @@ export async function setupRun(options: RunSetupOptions): Promise<RunSetupResult
       prdPath,
       workdir,
       dryRun,
+      agentGetFn: options.agentGetFn,
     });
     prd = initResult.prd;
     const counts = initResult.storyCounts;

package/src/execution/runner-completion.ts

@@ -11,9 +11,11 @@ import { fireHook } from "../hooks";
 import { getSafeLogger } from "../logger";
 import type { StoryMetrics } from "../metrics";
 import type { PipelineEventEmitter } from "../pipeline/events";
+import type { AgentGetFn } from "../pipeline/types";
 import type { PluginRegistry } from "../plugins/registry";
 import { isComplete } from "../prd";
 import type { PRD } from "../prd";
+import { autoCommitIfDirty } from "../utils/git";
 import { stopHeartbeat, writeExitSummary } from "./crash-recovery";
 import { hookCtx } from "./story-context";
 
@@ -42,6 +44,10 @@ export interface RunnerCompletionOptions {
   statusWriter: any;
   pluginRegistry: PluginRegistry;
   eventEmitter?: PipelineEventEmitter;
+  /** Protocol-aware agent resolver */
+  agentGetFn?: AgentGetFn;
+  /** Path to prd.json — required for acceptance fix story writes */
+  prdPath: string;
 }
 
 /**
@@ -67,7 +73,7 @@ export async function runCompletionPhase(options: RunnerCompletionOptions): Prom
     const acceptanceResult = await runAcceptanceLoop({
       config: options.config,
       prd: options.prd,
-      prdPath: "", // Not needed for this extraction
+      prdPath: options.prdPath,
       workdir: options.workdir,
       featureDir: options.featureDir,
       hooks: options.hooks,
@@ -79,6 +85,7 @@ export async function runCompletionPhase(options: RunnerCompletionOptions): Prom
       pluginRegistry: options.pluginRegistry,
       eventEmitter: options.eventEmitter,
       statusWriter: options.statusWriter,
+      agentGetFn: options.agentGetFn,
     });
 
     Object.assign(options, {
@@ -153,6 +160,9 @@ export async function runCompletionPhase(options: RunnerCompletionOptions): Prom
     durationMs,
   );
 
+  // Commit status.json and any other nax runtime files left dirty at run end
+  await autoCommitIfDirty(options.workdir, "run.complete", "run-summary", options.feature);
+
   return {
     durationMs,
     runCompletedAt,

package/src/execution/runner-execution.ts

@@ -10,6 +10,7 @@ import type { LoadedHooksConfig } from "../hooks";
 import { getSafeLogger } from "../logger";
 import type { StoryMetrics } from "../metrics";
 import type { PipelineEventEmitter } from "../pipeline/events";
+import type { AgentGetFn } from "../pipeline/types";
 import type { PluginRegistry } from "../plugins/registry";
 import type { PRD } from "../prd";
 import { tryLlmBatchRoute } from "../routing/batch-route";
@@ -17,6 +18,7 @@ import { clearCache as clearLlmCache, routeBatch as llmRouteBatch } from "../rou
 import { precomputeBatchPlan } from "./batching";
 import { getAllReadyStories } from "./helpers";
 import type { ParallelExecutorOptions, ParallelExecutorResult } from "./parallel-executor";
+import type { PidRegistry } from "./pid-registry";
 
 /**
  * Options for the execution phase.
@@ -42,6 +44,10 @@ export interface RunnerExecutionOptions {
   headless: boolean;
   parallel?: number;
   runParallelExecution?: (options: ParallelExecutorOptions, prd: PRD) => Promise<ParallelExecutorResult>;
+  /** Protocol-aware agent resolver — created once in runner.ts from createAgentRegistry(config) */
+  agentGetFn?: AgentGetFn;
+  /** PID registry for crash recovery — passed to agent.run() to register child processes. */
+  pidRegistry?: PidRegistry;
 }
 
 /**
@@ -198,6 +204,8 @@ export async function runExecutionPhase(
       runId: options.runId,
       startTime: options.startTime,
       batchPlan,
+      agentGetFn: options.agentGetFn,
+      pidRegistry: options.pidRegistry,
     },
     prd,
   );

package/src/execution/runner-setup.ts

@@ -7,6 +7,7 @@
 
 import type { NaxConfig } from "../config";
 import type { LoadedHooksConfig } from "../hooks";
+import type { AgentGetFn } from "../pipeline/types";
 
 /**
  * Options for the setup phase.
@@ -31,6 +32,8 @@ export interface RunnerSetupOptions {
   getIterations: () => number;
   getStoriesCompleted: () => number;
   getTotalStories: () => number;
+  /** Protocol-aware agent resolver — created from createAgentRegistry(config) in runner.ts */
+  agentGetFn?: AgentGetFn;
 }
 
 /**
@@ -76,6 +79,7 @@ export async function runSetupPhase(options: RunnerSetupOptions): Promise<Runner
     // BUG-017: Pass getters for run.complete event on SIGTERM
     getStoriesCompleted: options.getStoriesCompleted,
     getTotalStories: options.getTotalStories,
+    agentGetFn: options.agentGetFn,
   });
 
   return setupResult;

package/src/execution/runner.ts

@@ -13,6 +13,7 @@
  * - runner-completion.ts: Acceptance loop, hooks, metrics
  */
 
+import { createAgentRegistry } from "../agents/registry";
 import type { NaxConfig } from "../config";
 import type { LoadedHooksConfig } from "../hooks";
 import { fireHook } from "../hooks";
@@ -116,6 +117,10 @@ export async function run(options: RunOptions): Promise<RunResult> {
 
   const logger = getSafeLogger();
 
+  // Create protocol-aware agent registry (ACP wiring — ACP-003/registry-wiring)
+  const registry = createAgentRegistry(config);
+  const agentGetFn = registry.getAgent.bind(registry);
+
   // Declare prd before crash handler setup to avoid TDZ if SIGTERM arrives during setup
   // biome-ignore lint/suspicious/noExplicitAny: PRD type initialized during setup
   let prd: any | undefined;
@@ -137,6 +142,7 @@ export async function run(options: RunOptions): Promise<RunResult> {
     skipPrecheck,
     headless,
     formatterMode,
+    agentGetFn,
     getTotalCost: () => totalCost,
     getIterations: () => iterations,
     // BUG-017: Pass getters for run.complete event on SIGTERM
@@ -170,6 +176,8 @@ export async function run(options: RunOptions): Promise<RunResult> {
         headless,
         parallel,
         runParallelExecution: _runnerDeps.runParallelExecution ?? undefined,
+        agentGetFn,
+        pidRegistry,
       },
       prd,
       pluginRegistry,
@@ -198,6 +206,7 @@ export async function run(options: RunOptions): Promise<RunResult> {
       hooks,
       feature,
       workdir,
+      prdPath,
       statusFile,
       logFilePath,
       runId,
@@ -214,6 +223,7 @@ export async function run(options: RunOptions): Promise<RunResult> {
       statusWriter,
       pluginRegistry,
       eventEmitter,
+      agentGetFn,
     });
 
     const { durationMs } = completionResult;