@nathapp/nax 0.42.1 → 0.42.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 William Khoo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/nax.ts

@@ -330,8 +330,8 @@ program
       formatterMode = "quiet";
     }
 
-    const config = await loadConfig();
     const naxDir = findProjectDir(workdir);
+    const config = await loadConfig(naxDir ?? undefined);
 
     if (!naxDir) {
       console.error(chalk.red("nax not initialized. Run: nax init"));

package/dist/nax.js

@@ -17804,7 +17804,7 @@ var init_schemas3 = __esm(() => {
   });
   AgentConfigSchema = exports_external.object({
     protocol: exports_external.enum(["acp", "cli"]).default("acp"),
-    acpPermissionMode: exports_external.string().optional()
+    maxInteractionTurns: exports_external.number().int().min(1).max(100).default(10)
   });
   PrecheckConfigSchema = exports_external.object({
     storySizeGate: StorySizeGateConfigSchema
@@ -17928,7 +17928,6 @@ var init_defaults = __esm(() => {
       detectOpenHandles: true,
       detectOpenHandlesRetries: 1,
       gracePeriodMs: 5000,
-      dangerouslySkipPermissions: true,
       drainTimeoutMs: 2000,
       shell: "/bin/sh",
       stripEnvVars: [
@@ -18055,6 +18054,13 @@ var init_defaults = __esm(() => {
 });
 
 // src/config/schema.ts
+var exports_schema = {};
+__export(exports_schema, {
+  resolveModel: () => resolveModel,
+  NaxConfigSchema: () => NaxConfigSchema,
+  DEFAULT_CONFIG: () => DEFAULT_CONFIG,
+  AcceptanceConfigSchema: () => AcceptanceConfigSchema
+});
 var init_schema = __esm(() => {
   init_types3();
   init_schemas3();
@@ -18969,8 +18975,6 @@ class SpawnAcpSession {
       "--cwd",
       this.cwd,
       ...this.permissionMode === "approve-all" ? ["--approve-all"] : [],
-      "--format",
-      "json",
       "--model",
       this.model,
       "--timeout",
@@ -19057,7 +19061,7 @@ class SpawnAcpClient {
   async start() {}
   async createSession(opts) {
     const sessionName = opts.sessionName || `nax-${Date.now()}`;
-    const cmd = ["acpx", opts.agentName, "sessions", "ensure", "--name", sessionName];
+    const cmd = ["acpx", "--cwd", this.cwd, opts.agentName, "sessions", "ensure", "--name", sessionName];
     getSafeLogger()?.debug("acp-adapter", `Ensuring session: ${sessionName}`);
     const proc = _spawnClientDeps.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
     const exitCode = await proc.exited;
@@ -19076,7 +19080,7 @@ class SpawnAcpClient {
     });
   }
   async loadSession(sessionName) {
-    const cmd = ["acpx", this.agentName, "sessions", "ensure", "--name", sessionName];
+    const cmd = ["acpx", "--cwd", this.cwd, this.agentName, "sessions", "ensure", "--name", sessionName];
     const proc = _spawnClientDeps.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
     const exitCode = await proc.exited;
     if (exitCode !== 0) {
@@ -19360,7 +19364,7 @@ class AcpAgentAdapter {
       sessionName = await readAcpSession(options.workdir, options.featureName, options.storyId) ?? undefined;
     }
     sessionName ??= buildSessionName(options.workdir, options.featureName, options.storyId, options.sessionRole);
-    const permissionMode = options.dangerouslySkipPermissions ? "approve-all" : "default";
+    const permissionMode = options.dangerouslySkipPermissions ? "approve-all" : "approve-reads";
     const session = await ensureAcpSession(client, sessionName, this.name, permissionMode);
     if (options.featureName && options.storyId) {
       await saveAcpSession(options.workdir, options.featureName, options.storyId, sessionName);
@@ -19371,7 +19375,7 @@ class AcpAgentAdapter {
     try {
       let currentPrompt = options.prompt;
       let turnCount = 0;
-      const MAX_TURNS = options.interactionBridge ? 10 : 1;
+      const MAX_TURNS = options.interactionBridge ? options.maxInteractionTurns ?? 10 : 1;
       while (turnCount < MAX_TURNS) {
         turnCount++;
         getSafeLogger()?.debug("acp-adapter", `Session turn ${turnCount}/${MAX_TURNS}`, { sessionName });
@@ -19466,10 +19470,17 @@ class AcpAgentAdapter {
         }
         const text = response.messages.filter((m) => m.role === "assistant").map((m) => m.content).join(`
 `).trim();
-        if (!text) {
+        let unwrapped = text;
+        try {
+          const envelope = JSON.parse(text);
+          if (envelope?.type === "result" && typeof envelope?.result === "string") {
+            unwrapped = envelope.result;
+          }
+        } catch {}
+        if (!unwrapped) {
           throw new CompleteError("complete() returned empty output");
         }
-        return text;
+        return unwrapped;
       } catch (err) {
         const error48 = err instanceof Error ? err : new Error(String(err));
         lastError = error48;
@@ -19492,7 +19503,19 @@ class AcpAgentAdapter {
     throw lastError ?? new CompleteError("complete() failed with unknown error");
   }
   async plan(options) {
-    const modelDef = options.modelDef ?? { provider: "anthropic", model: "default" };
+    let modelDef = options.modelDef;
+    if (!modelDef && options.config?.models) {
+      const tier = options.modelTier ?? "balanced";
+      const { resolveModel: resolveModel2 } = await Promise.resolve().then(() => (init_schema(), exports_schema));
+      const models = options.config.models;
+      const entry = models[tier] ?? models.balanced;
+      if (entry) {
+        try {
+          modelDef = resolveModel2(entry);
+        } catch {}
+      }
+    }
+    modelDef ??= { provider: "anthropic", model: "claude-sonnet-4-5-20250514" };
     const timeoutSeconds = options.timeoutSeconds ?? options.config?.execution?.sessionTimeoutSeconds ?? 600;
     const result = await this.run({
       prompt: options.prompt,
@@ -19502,6 +19525,7 @@ class AcpAgentAdapter {
       timeoutSeconds,
       dangerouslySkipPermissions: options.dangerouslySkipPermissions ?? false,
       interactionBridge: options.interactionBridge,
+      maxInteractionTurns: options.maxInteractionTurns,
       featureName: options.featureName,
       storyId: options.storyId,
       sessionRole: options.sessionRole
@@ -21835,7 +21859,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@nathapp/nax",
-    version: "0.42.1",
+    version: "0.42.3",
     description: "AI Coding Agent Orchestrator \u2014 loops until done",
     type: "module",
     bin: {
@@ -21889,7 +21913,15 @@ var init_package = __esm(() => {
       "bin/",
       "README.md",
       "CHANGELOG.md"
-    ]
+    ],
+    repository: {
+      type: "git",
+      url: "https://github.com/nathapp-io/nax.git"
+    },
+    homepage: "https://github.com/nathapp-io/nax",
+    bugs: {
+      url: "https://github.com/nathapp-io/nax/issues"
+    }
   };
 });
 
@@ -21900,8 +21932,8 @@ var init_version = __esm(() => {
   NAX_VERSION = package_default.version;
   NAX_COMMIT = (() => {
     try {
-      if (/^[0-9a-f]{6,10}$/.test("29c340c"))
-        return "29c340c";
+      if (/^[0-9a-f]{6,10}$/.test("b051dcb"))
+        return "b051dcb";
     } catch {}
     try {
       const result = Bun.spawnSync(["git", "rev-parse", "--short", "HEAD"], {
@@ -26222,6 +26254,7 @@ async function runRectificationLoop(story, config2, workdir, agent, implementerT
       modelDef: resolveModel(config2.models[implementerTier]),
       timeoutSeconds: config2.execution.sessionTimeoutSeconds,
       dangerouslySkipPermissions: config2.execution.dangerouslySkipPermissions,
+      maxInteractionTurns: config2.agent?.maxInteractionTurns,
       featureName,
       storyId: story.id,
       sessionRole: "implementer"
@@ -26829,6 +26862,7 @@ async function runTddSession(role, agent, story, config2, workdir, modelTier, be
     modelDef: resolveModel(config2.models[modelTier]),
     timeoutSeconds: config2.execution.sessionTimeoutSeconds,
     dangerouslySkipPermissions: config2.execution.dangerouslySkipPermissions,
+    maxInteractionTurns: config2.agent?.maxInteractionTurns,
     featureName,
     storyId: story.id,
     sessionRole: role
@@ -27578,6 +27612,7 @@ Category: ${tddResult.failureCategory ?? "unknown"}`,
         modelDef: resolveModel(ctx.config.models[ctx.routing.modelTier]),
         timeoutSeconds: ctx.config.execution.sessionTimeoutSeconds,
         dangerouslySkipPermissions: ctx.config.execution.dangerouslySkipPermissions,
+        maxInteractionTurns: ctx.config.agent?.maxInteractionTurns,
         pidRegistry: ctx.pidRegistry,
         featureName: ctx.prd.feature,
         storyId: ctx.story.id,
@@ -28126,7 +28161,8 @@ ${rectificationPrompt}`;
       modelTier,
       modelDef,
       timeoutSeconds: config2.execution.sessionTimeoutSeconds,
-      dangerouslySkipPermissions: config2.execution.dangerouslySkipPermissions
+      dangerouslySkipPermissions: config2.execution.dangerouslySkipPermissions,
+      maxInteractionTurns: config2.agent?.maxInteractionTurns
     });
     if (agentResult.success) {
       logger?.info("rectification", `Agent ${label} session complete`, {
@@ -28628,6 +28664,9 @@ function buildScopedCommand(testFiles, baseCommand, testScopedTemplate) {
   }
   return _scopedDeps.buildSmartTestCommand(testFiles, baseCommand);
 }
+function isMonorepoOrchestratorCommand(command) {
+  return /\bturbo\b/.test(command) || /\bnx\b/.test(command);
+}
 
 class ScopedStrategy {
   name = "scoped";
@@ -28635,9 +28674,10 @@ class ScopedStrategy {
     const logger = getLogger();
     const smartCfg = coerceSmartRunner(ctx.smartRunnerConfig);
     const regressionMode = ctx.regressionMode ?? "deferred";
+    const isMonorepoOrchestrator = isMonorepoOrchestratorCommand(ctx.testCommand);
     let effectiveCommand = ctx.testCommand;
     let isFullSuite = true;
-    if (smartCfg.enabled && ctx.storyGitRef) {
+    if (smartCfg.enabled && ctx.storyGitRef && !isMonorepoOrchestrator) {
       const sourceFiles = await _scopedDeps.getChangedSourceFiles(ctx.workdir, ctx.storyGitRef);
       const pass1Files = await _scopedDeps.mapSourceToTests(sourceFiles, ctx.workdir);
       if (pass1Files.length > 0) {
@@ -28657,14 +28697,19 @@ class ScopedStrategy {
         }
       }
     }
-    if (isFullSuite && regressionMode === "deferred") {
+    if (isFullSuite && regressionMode === "deferred" && !isMonorepoOrchestrator) {
       logger.info("verify[scoped]", "No mapped tests \u2014 deferring to run-end (mode: deferred)", {
         storyId: ctx.storyId
       });
       return makeSkippedResult(ctx.storyId, "scoped");
     }
-    if (isFullSuite) {
+    if (isFullSuite && !isMonorepoOrchestrator) {
       logger.info("verify[scoped]", "No mapped tests \u2014 falling back to full suite", { storyId: ctx.storyId });
+    } else if (isMonorepoOrchestrator) {
+      logger.info("verify[scoped]", "Monorepo orchestrator detected \u2014 delegating scoping to tool", {
+        storyId: ctx.storyId,
+        command: effectiveCommand
+      });
     }
     const start = Date.now();
     const result = await _scopedDeps.regression({
@@ -65702,13 +65747,14 @@ var _deps2 = {
   readFile: (path) => Bun.file(path).text(),
   writeFile: (path, content) => Bun.write(path, content).then(() => {}),
   scanCodebase: (workdir) => scanCodebase(workdir),
-  getAgent: (name) => getAgent(name),
+  getAgent: (name, cfg) => cfg ? createAgentRegistry(cfg).getAgent(name) : getAgent(name),
   readPackageJson: (workdir) => Bun.file(join10(workdir, "package.json")).json().catch(() => null),
   spawnSync: (cmd, opts) => {
     const result = Bun.spawnSync(cmd, opts ? { cwd: opts.cwd } : {});
     return { stdout: result.stdout, exitCode: result.exitCode };
   },
-  mkdirp: (path) => Bun.spawn(["mkdir", "-p", path]).exited.then(() => {})
+  mkdirp: (path) => Bun.spawn(["mkdir", "-p", path]).exited.then(() => {}),
+  existsSync: (path) => existsSync9(path)
 };
 async function planCommand(workdir, config2, options) {
   const naxDir = join10(workdir, "nax");
@@ -65724,37 +65770,53 @@ async function planCommand(workdir, config2, options) {
   const pkg = await _deps2.readPackageJson(workdir);
   const projectName = detectProjectName(workdir, pkg);
   const branchName = options.branch ?? `feat/${options.feature}`;
-  const prompt = buildPlanningPrompt(specContent, codebaseContext);
+  const outputDir = join10(naxDir, "features", options.feature);
+  const outputPath = join10(outputDir, "prd.json");
+  await _deps2.mkdirp(outputDir);
   const agentName = config2?.autoMode?.defaultAgent ?? "claude";
-  const adapter = _deps2.getAgent(agentName);
-  if (!adapter) {
-    throw new Error(`[plan] No agent adapter found for '${agentName}'`);
-  }
   const timeoutSeconds = config2?.execution?.sessionTimeoutSeconds ?? 600;
   let rawResponse;
   if (options.auto) {
-    rawResponse = await adapter.complete(prompt, { jsonMode: true });
+    const prompt = buildPlanningPrompt(specContent, codebaseContext);
+    const cliAdapter = _deps2.getAgent(agentName);
+    if (!cliAdapter)
+      throw new Error(`[plan] No agent adapter found for '${agentName}'`);
+    rawResponse = await cliAdapter.complete(prompt, { jsonMode: true });
+    try {
+      const envelope = JSON.parse(rawResponse);
+      if (envelope?.type === "result" && typeof envelope?.result === "string") {
+        rawResponse = envelope.result;
+      }
+    } catch {}
   } else {
+    const prompt = buildPlanningPrompt(specContent, codebaseContext, outputPath);
+    const adapter = _deps2.getAgent(agentName, config2);
+    if (!adapter)
+      throw new Error(`[plan] No agent adapter found for '${agentName}'`);
     const interactionBridge = createCliInteractionBridge();
     logger?.info("plan", "Starting interactive planning session...", { agent: agentName });
     try {
-      const result = await adapter.plan({
+      await adapter.plan({
         prompt,
         workdir,
         interactive: true,
         timeoutSeconds,
-        interactionBridge
+        interactionBridge,
+        config: config2,
+        modelTier: config2?.plan?.model ?? "balanced",
+        dangerouslySkipPermissions: config2?.execution?.dangerouslySkipPermissions ?? false,
+        maxInteractionTurns: config2?.agent?.maxInteractionTurns
       });
-      rawResponse = result.specContent;
     } finally {
       logger?.info("plan", "Interactive session ended");
     }
+    if (!_deps2.existsSync(outputPath)) {
+      throw new Error(`[plan] Agent did not write PRD to ${outputPath}. Check agent logs for errors.`);
+    }
+    rawResponse = await _deps2.readFile(outputPath);
   }
   const finalPrd = validatePlanOutput(rawResponse, options.feature, branchName);
   finalPrd.project = projectName;
-  const outputDir = join10(naxDir, "features", options.feature);
-  const outputPath = join10(outputDir, "prd.json");
-  await _deps2.mkdirp(outputDir);
   await _deps2.writeFile(outputPath, JSON.stringify(finalPrd, null, 2));
   logger?.info("plan", "[OK] PRD written", { outputPath });
   return outputPath;
@@ -65821,7 +65883,7 @@ function buildCodebaseContext2(scan) {
   return sections.join(`
 `);
 }
-function buildPlanningPrompt(specContent, codebaseContext) {
+function buildPlanningPrompt(specContent, codebaseContext, outputFilePath) {
   return `You are a senior software architect generating a product requirements document (PRD) as JSON.
 
 ## Spec
@@ -65877,7 +65939,8 @@ Generate a JSON object with this exact structure (no markdown, no explanation \u
 - three-session-tdd: Complex stories. Full TDD cycle with separate test-writer and implementer sessions.
 - three-session-tdd-lite: Expert/high-risk stories. Full TDD with additional verifier session.
 
-Output ONLY the JSON object. Do not wrap in markdown code blocks.`;
+${outputFilePath ? `Write the PRD JSON directly to this file path: ${outputFilePath}
+Do NOT output the JSON to the conversation. Write the file, then reply with a brief confirmation.` : "Output ONLY the JSON object. Do not wrap in markdown code blocks."}`;
 }
 // src/cli/accept.ts
 init_config();
@@ -67848,7 +67911,10 @@ var FIELD_DESCRIPTIONS = {
   "decompose.maxSubstories": "Max number of substories to generate (default: 5)",
   "decompose.maxSubstoryComplexity": "Max complexity for any generated substory (default: 'medium')",
   "decompose.maxRetries": "Max retries on decomposition validation failure (default: 2)",
-  "decompose.model": "Model tier for decomposition LLM calls (default: 'balanced')"
+  "decompose.model": "Model tier for decomposition LLM calls (default: 'balanced')",
+  agent: "Agent protocol configuration (ACP-003)",
+  "agent.protocol": "Protocol for agent communication: 'acp' | 'cli' (default: 'acp')",
+  "agent.maxInteractionTurns": "Max turns in multi-turn interaction loop when interactionBridge is active (default: 10)"
 };
 
 // src/cli/config-diff.ts
@@ -76600,8 +76666,8 @@ program2.command("run").description("Run the orchestration loop for a feature").
   } else if (options.quiet || options.silent) {
     formatterMode = "quiet";
   }
-  const config2 = await loadConfig();
   const naxDir = findProjectDir(workdir);
+  const config2 = await loadConfig(naxDir ?? undefined);
   if (!naxDir) {
     console.error(source_default.red("nax not initialized. Run: nax init"));
     process.exit(1);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.42.1",
-  "description": "AI Coding Agent Orchestrator \u2014 loops until done",
+  "version": "0.42.3",
+  "description": "AI Coding Agent Orchestrator — loops until done",
   "type": "module",
   "bin": {
     "nax": "./dist/nax.js"
@@ -54,5 +54,13 @@
     "bin/",
     "README.md",
     "CHANGELOG.md"
-  ]
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nathapp-io/nax.git"
+  },
+  "homepage": "https://github.com/nathapp-io/nax",
+  "bugs": {
+    "url": "https://github.com/nathapp-io/nax/issues"
+  }
 }

package/src/agents/acp/adapter.ts

@@ -442,8 +442,8 @@ export class AcpAgentAdapter implements AgentAdapter {
     }
     sessionName ??= buildSessionName(options.workdir, options.featureName, options.storyId, options.sessionRole);
 
-    // 2. Permission mode follows dangerouslySkipPermissions
-    const permissionMode = options.dangerouslySkipPermissions ? "approve-all" : "default";
+    // 2. Permission mode follows dangerouslySkipPermissions, default is "approve-reads". or should --deny-all be the default?
+    const permissionMode = options.dangerouslySkipPermissions ? "approve-all" : "approve-reads";
 
     // 3. Ensure session (resume existing or create new)
     const session = await ensureAcpSession(client, sessionName, this.name, permissionMode);
@@ -461,7 +461,7 @@ export class AcpAgentAdapter implements AgentAdapter {
       // 5. Multi-turn loop
       let currentPrompt = options.prompt;
       let turnCount = 0;
-      const MAX_TURNS = options.interactionBridge ? 10 : 1;
+      const MAX_TURNS = options.interactionBridge ? (options.maxInteractionTurns ?? 10) : 1;
 
       while (turnCount < MAX_TURNS) {
         turnCount++;
@@ -593,11 +593,24 @@ export class AcpAgentAdapter implements AgentAdapter {
           .join("\n")
           .trim();
 
-        if (!text) {
+        // ACP one-shot sessions wrap the response in a result envelope:
+        // {"type":"result","subtype":"success","result":"<actual output>"}
+        // Unwrap to return the actual content.
+        let unwrapped = text;
+        try {
+          const envelope = JSON.parse(text) as Record<string, unknown>;
+          if (envelope?.type === "result" && typeof envelope?.result === "string") {
+            unwrapped = envelope.result;
+          }
+        } catch {
+          // Not an envelope — use text as-is
+        }
+
+        if (!unwrapped) {
           throw new CompleteError("complete() returned empty output");
         }
 
-        return text;
+        return unwrapped;
       } catch (err) {
         const error = err instanceof Error ? err : new Error(String(err));
         lastError = error;
@@ -623,7 +636,22 @@ export class AcpAgentAdapter implements AgentAdapter {
   }
 
   async plan(options: PlanOptions): Promise<PlanResult> {
-    const modelDef = options.modelDef ?? { provider: "anthropic", model: "default" };
+    // Resolve model: explicit > config.models[tier] > config.models.balanced > fallback
+    let modelDef = options.modelDef;
+    if (!modelDef && options.config?.models) {
+      const tier = options.modelTier ?? "balanced";
+      const { resolveModel } = await import("../../config/schema");
+      const models = options.config.models as Record<string, unknown>;
+      const entry = models[tier] ?? models.balanced;
+      if (entry) {
+        try {
+          modelDef = resolveModel(entry as Parameters<typeof resolveModel>[0]);
+        } catch {
+          // resolveModel can throw on malformed entries
+        }
+      }
+    }
+    modelDef ??= { provider: "anthropic", model: "claude-sonnet-4-5-20250514" };
     // Timeout: from options, or config, or fallback to 600s
     const timeoutSeconds =
       options.timeoutSeconds ?? (options.config?.execution?.sessionTimeoutSeconds as number | undefined) ?? 600;
@@ -636,6 +664,7 @@ export class AcpAgentAdapter implements AgentAdapter {
       timeoutSeconds,
       dangerouslySkipPermissions: options.dangerouslySkipPermissions ?? false,
       interactionBridge: options.interactionBridge,
+      maxInteractionTurns: options.maxInteractionTurns,
       featureName: options.featureName,
       storyId: options.storyId,
       sessionRole: options.sessionRole,

package/src/agents/acp/spawn-client.ts

@@ -121,8 +121,6 @@ class SpawnAcpSession implements AcpSession {
       "--cwd",
       this.cwd,
       ...(this.permissionMode === "approve-all" ? ["--approve-all"] : []),
-      "--format",
-      "json",
       "--model",
       this.model,
       "--timeout",
@@ -247,7 +245,7 @@ export class SpawnAcpClient implements AcpClient {
     const sessionName = opts.sessionName || `nax-${Date.now()}`;
 
     // Ensure session exists via CLI
-    const cmd = ["acpx", opts.agentName, "sessions", "ensure", "--name", sessionName];
+    const cmd = ["acpx", "--cwd", this.cwd, opts.agentName, "sessions", "ensure", "--name", sessionName];
     getSafeLogger()?.debug("acp-adapter", `Ensuring session: ${sessionName}`);
 
     const proc = _spawnClientDeps.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
@@ -271,7 +269,7 @@ export class SpawnAcpClient implements AcpClient {
 
   async loadSession(sessionName: string): Promise<AcpSession | null> {
     // Try to ensure session exists — if it does, acpx returns success
-    const cmd = ["acpx", this.agentName, "sessions", "ensure", "--name", sessionName];
+    const cmd = ["acpx", "--cwd", this.cwd, this.agentName, "sessions", "ensure", "--name", sessionName];
 
     const proc = _spawnClientDeps.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
     const exitCode = await proc.exited;

package/src/agents/types-extended.ts

@@ -48,6 +48,8 @@ export interface PlanOptions {
   timeoutSeconds?: number;
   /** Whether to skip permission prompts (maps to permissionMode in ACP) */
   dangerouslySkipPermissions?: boolean;
+  /** Max interaction turns when interactionBridge is active (default: 10) */
+  maxInteractionTurns?: number;
   /**
    * 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.

package/src/agents/types.ts

@@ -74,6 +74,8 @@ export interface AgentRunOptions {
   storyId?: string;
   /** Session role for TDD isolation (e.g. "test-writer" | "implementer" | "verifier") */
   sessionRole?: string;
+  /** Max turns in multi-turn interaction loop when interactionBridge is active (default: 10) */
+  maxInteractionTurns?: number;
 }
 
 /**

package/src/cli/config-descriptions.ts

@@ -203,4 +203,10 @@ export const FIELD_DESCRIPTIONS: Record<string, string> = {
   "decompose.maxSubstoryComplexity": "Max complexity for any generated substory (default: 'medium')",
   "decompose.maxRetries": "Max retries on decomposition validation failure (default: 2)",
   "decompose.model": "Model tier for decomposition LLM calls (default: 'balanced')",
+
+  // Agent protocol
+  agent: "Agent protocol configuration (ACP-003)",
+  "agent.protocol": "Protocol for agent communication: 'acp' | 'cli' (default: 'acp')",
+  "agent.maxInteractionTurns":
+    "Max turns in multi-turn interaction loop when interactionBridge is active (default: 10)",
 };

package/src/cli/init-detect.ts

@@ -26,6 +26,7 @@ interface PackageJson {
   devDependencies?: Record<string, string>;
   peerDependencies?: Record<string, string>;
   bin?: Record<string, string> | string;
+  workspaces?: string[] | { packages: string[] };
 }
 
 function readPackageJson(projectRoot: string): PackageJson | undefined {
@@ -80,7 +81,7 @@ export type Language = "typescript" | "python" | "rust" | "go" | "unknown";
 export type Linter = "biome" | "eslint" | "ruff" | "clippy" | "golangci-lint" | "unknown";
 
 /** Detected monorepo tooling */
-export type Monorepo = "turborepo" | "none";
+export type Monorepo = "turborepo" | "nx" | "pnpm-workspaces" | "bun-workspaces" | "none";
 
 /** Full detected project stack */
 export interface ProjectStack {
@@ -137,6 +138,11 @@ function detectLinter(projectRoot: string): Linter {
 
 function detectMonorepo(projectRoot: string): Monorepo {
   if (existsSync(join(projectRoot, "turbo.json"))) return "turborepo";
+  if (existsSync(join(projectRoot, "nx.json"))) return "nx";
+  if (existsSync(join(projectRoot, "pnpm-workspace.yaml"))) return "pnpm-workspaces";
+  // Bun/npm/yarn workspaces: package.json with "workspaces" field
+  const pkg = readPackageJson(projectRoot);
+  if (pkg?.workspaces) return "bun-workspaces";
   return "none";
 }
 
@@ -158,10 +164,52 @@ function resolveLintCommand(stack: ProjectStack, fallback: string): string {
   return fallback;
 }
 
+/**
+ * Build quality.commands for monorepo orchestrators.
+ *
+ * Turborepo and Nx support change-aware filtering natively — delegate
+ * scoping to the tool rather than nax's smart test runner.
+ * pnpm/bun workspaces have no built-in affected detection, so nax's
+ * smart runner still applies; commands run across all packages.
+ */
+function buildMonorepoQualityCommands(stack: ProjectStack): QualityCommands | null {
+  if (stack.monorepo === "turborepo") {
+    return {
+      typecheck: "turbo run typecheck --filter=...[HEAD~1]",
+      lint: "turbo run lint --filter=...[HEAD~1]",
+      test: "turbo run test --filter=...[HEAD~1]",
+    };
+  }
+  if (stack.monorepo === "nx") {
+    return {
+      typecheck: "nx affected --target=typecheck",
+      lint: "nx affected --target=lint",
+      test: "nx affected --target=test",
+    };
+  }
+  if (stack.monorepo === "pnpm-workspaces") {
+    return {
+      lint: resolveLintCommand(stack, "pnpm run --recursive lint"),
+      test: "pnpm run --recursive test",
+    };
+  }
+  if (stack.monorepo === "bun-workspaces") {
+    return {
+      lint: resolveLintCommand(stack, "bun run lint"),
+      test: "bun run --filter '*' test",
+    };
+  }
+  return null;
+}
+
 /**
  * Build quality.commands from a detected project stack.
  */
 export function buildQualityCommands(stack: ProjectStack): QualityCommands {
+  // Monorepo orchestrators: delegate to the tool's own scoping
+  const monorepoCommands = buildMonorepoQualityCommands(stack);
+  if (monorepoCommands) return monorepoCommands;
+
   if (stack.runtime === "bun" && stack.language === "typescript") {
     return {
       typecheck: "bun run tsc --noEmit",

package/src/cli/init.ts

@@ -103,11 +103,21 @@ function buildConstitution(stack: ProjectStack): string {
     sections.push("- Use type annotations for variables where non-obvious\n");
   }
 
-  if (stack.monorepo === "turborepo") {
+  if (stack.monorepo !== "none") {
     sections.push("## Monorepo Conventions");
     sections.push("- Respect package boundaries — do not import across packages without explicit dependency");
     sections.push("- Each package should be independently buildable and testable");
-    sections.push("- Shared utilities go in a dedicated `packages/shared` (or equivalent) package\n");
+    sections.push("- Shared utilities go in a dedicated `packages/shared` (or equivalent) package");
+    if (stack.monorepo === "turborepo") {
+      sections.push("- Use `turbo run <task> --filter=<package>` to run tasks scoped to a single package");
+    } else if (stack.monorepo === "nx") {
+      sections.push("- Use `nx run <package>:<task>` to run tasks scoped to a single package");
+    } else if (stack.monorepo === "pnpm-workspaces") {
+      sections.push("- Use `pnpm --filter <package> run <task>` to run tasks scoped to a single package");
+    } else if (stack.monorepo === "bun-workspaces") {
+      sections.push("- Use `bun run --filter <package> <task>` to run tasks scoped to a single package");
+    }
+    sections.push("");
   }
 
   sections.push("## Preferences");

package/src/cli/plan.ts

@@ -10,7 +10,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { createInterface } from "node:readline";
-import { getAgent } from "../agents/registry";
+import { createAgentRegistry, getAgent } from "../agents/registry";
 import type { AgentAdapter } from "../agents/types";
 import { scanCodebase } from "../analyze/scanner";
 import type { CodebaseScan } from "../analyze/types";
@@ -26,7 +26,8 @@ export const _deps = {
   readFile: (path: string): Promise<string> => Bun.file(path).text(),
   writeFile: (path: string, content: string): Promise<void> => Bun.write(path, content).then(() => {}),
   scanCodebase: (workdir: string): Promise<CodebaseScan> => scanCodebase(workdir),
-  getAgent: (name: string): AgentAdapter | undefined => getAgent(name),
+  getAgent: (name: string, cfg?: NaxConfig): AgentAdapter | undefined =>
+    cfg ? createAgentRegistry(cfg).getAgent(name) : getAgent(name),
   readPackageJson: (workdir: string): Promise<Record<string, unknown> | null> =>
     Bun.file(join(workdir, "package.json"))
       .json()
@@ -36,6 +37,7 @@ export const _deps = {
     return { stdout: result.stdout as Buffer, exitCode: result.exitCode };
   },
   mkdirp: (path: string): Promise<void> => Bun.spawn(["mkdir", "-p", path]).exited.then(() => {}),
+  existsSync: (path: string): boolean => existsSync(path),
 };
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -87,16 +89,13 @@ export async function planCommand(workdir: string, config: NaxConfig, options: P
   const pkg = await _deps.readPackageJson(workdir);
   const projectName = detectProjectName(workdir, pkg);
 
-  // Build prompt
+  // Compute output path early — needed for interactive file-write prompt
   const branchName = options.branch ?? `feat/${options.feature}`;
-  const prompt = buildPlanningPrompt(specContent, codebaseContext);
+  const outputDir = join(naxDir, "features", options.feature);
+  const outputPath = join(outputDir, "prd.json");
+  await _deps.mkdirp(outputDir);
 
-  // Get agent adapter
   const agentName = config?.autoMode?.defaultAgent ?? "claude";
-  const adapter = _deps.getAgent(agentName);
-  if (!adapter) {
-    throw new Error(`[plan] No agent adapter found for '${agentName}'`);
-  }
 
   // Timeout: from config, or default to 600 seconds (10 min)
   const timeoutSeconds = config?.execution?.sessionTimeoutSeconds ?? 600;
@@ -104,22 +103,47 @@ export async function planCommand(workdir: string, config: NaxConfig, options: P
   // Route to auto (one-shot) or interactive (multi-turn) mode
   let rawResponse: string;
   if (options.auto) {
-    rawResponse = await adapter.complete(prompt, { jsonMode: true });
+    // One-shot: use CLI adapter directly — simple completion doesn't need ACP session overhead
+    const prompt = buildPlanningPrompt(specContent, codebaseContext);
+    const cliAdapter = _deps.getAgent(agentName);
+    if (!cliAdapter) throw new Error(`[plan] No agent adapter found for '${agentName}'`);
+    rawResponse = await cliAdapter.complete(prompt, { jsonMode: true });
+    // CLI adapter returns {"type":"result","result":"..."} envelope — unwrap it
+    try {
+      const envelope = JSON.parse(rawResponse) as Record<string, unknown>;
+      if (envelope?.type === "result" && typeof envelope?.result === "string") {
+        rawResponse = envelope.result;
+      }
+    } catch {
+      // Not an envelope — use rawResponse as-is
+    }
   } else {
+    // Interactive: agent writes PRD JSON directly to outputPath (avoids output truncation)
+    const prompt = buildPlanningPrompt(specContent, codebaseContext, outputPath);
+    const adapter = _deps.getAgent(agentName, config);
+    if (!adapter) throw new Error(`[plan] No agent adapter found for '${agentName}'`);
     const interactionBridge = createCliInteractionBridge();
     logger?.info("plan", "Starting interactive planning session...", { agent: agentName });
     try {
-      const result = await adapter.plan({
+      await adapter.plan({
         prompt,
         workdir,
         interactive: true,
         timeoutSeconds,
         interactionBridge,
+        config,
+        modelTier: config?.plan?.model ?? "balanced",
+        dangerouslySkipPermissions: config?.execution?.dangerouslySkipPermissions ?? false,
+        maxInteractionTurns: config?.agent?.maxInteractionTurns,
       });
-      rawResponse = result.specContent;
     } finally {
       logger?.info("plan", "Interactive session ended");
     }
+    // Read back from file written by agent
+    if (!_deps.existsSync(outputPath)) {
+      throw new Error(`[plan] Agent did not write PRD to ${outputPath}. Check agent logs for errors.`);
+    }
+    rawResponse = await _deps.readFile(outputPath);
   }
 
   // Validate and normalize: handles markdown extraction, trailing commas, LLM quirks,
@@ -129,10 +153,7 @@ export async function planCommand(workdir: string, config: NaxConfig, options: P
   // Override project with auto-detected name (validatePlanOutput fills feature/branchName already)
   finalPrd.project = projectName;
 
-  // Write output
-  const outputDir = join(naxDir, "features", options.feature);
-  const outputPath = join(outputDir, "prd.json");
-  await _deps.mkdirp(outputDir);
+  // Write normalized PRD (overwrites agent-written file with validated/normalized version)
   await _deps.writeFile(outputPath, JSON.stringify(finalPrd, null, 2));
 
   logger?.info("plan", "[OK] PRD written", { outputPath });
@@ -241,7 +262,7 @@ function buildCodebaseContext(scan: CodebaseScan): string {
  * - Complexity classification guide
  * - Test strategy guide
  */
-function buildPlanningPrompt(specContent: string, codebaseContext: string): string {
+function buildPlanningPrompt(specContent: string, codebaseContext: string, outputFilePath?: string): string {
   return `You are a senior software architect generating a product requirements document (PRD) as JSON.
 
 ## Spec
@@ -297,5 +318,9 @@ Generate a JSON object with this exact structure (no markdown, no explanation
 - three-session-tdd: Complex stories. Full TDD cycle with separate test-writer and implementer sessions.
 - three-session-tdd-lite: Expert/high-risk stories. Full TDD with additional verifier session.
 
-Output ONLY the JSON object. Do not wrap in markdown code blocks.`;
+${
+  outputFilePath
+    ? `Write the PRD JSON directly to this file path: ${outputFilePath}\nDo NOT output the JSON to the conversation. Write the file, then reply with a brief confirmation.`
+    : "Output ONLY the JSON object. Do not wrap in markdown code blocks."
+}`;
 }

package/src/config/defaults.ts

@@ -81,7 +81,6 @@ export const DEFAULT_CONFIG: NaxConfig = {
     detectOpenHandles: true,
     detectOpenHandlesRetries: 1,
     gracePeriodMs: 5000,
-    dangerouslySkipPermissions: true,
     drainTimeoutMs: 2000,
     shell: "/bin/sh",
     stripEnvVars: [

package/src/config/runtime-types.ts

@@ -141,8 +141,6 @@ export interface QualityConfig {
   detectOpenHandlesRetries: number;
   /** Grace period in ms after SIGTERM before sending SIGKILL (default: 5000) */
   gracePeriodMs: number;
-  /** Use --dangerously-skip-permissions for agent sessions (default: false) */
-  dangerouslySkipPermissions: boolean;
   /** Deadline in ms to drain stdout/stderr after killing process (Bun stream workaround, default: 2000) */
   drainTimeoutMs: number;
   /** Shell to use for running verification commands (default: /bin/sh) */
@@ -473,6 +471,6 @@ export interface NaxConfig {
 export interface AgentConfig {
   /** Protocol to use for agent communication (default: 'acp') */
   protocol?: "acp" | "cli";
-  /** ACP permission mode (default: 'approve-all') */
-  acpPermissionMode?: string;
+  /** Max interaction turns when interactionBridge is active (default: 10) */
+  maxInteractionTurns?: number;
 }

package/src/config/schemas.ts

@@ -328,7 +328,7 @@ const StorySizeGateConfigSchema = z.object({
 
 const AgentConfigSchema = z.object({
   protocol: z.enum(["acp", "cli"]).default("acp"),
-  acpPermissionMode: z.string().optional(),
+  maxInteractionTurns: z.number().int().min(1).max(100).default(10),
 });
 
 const PrecheckConfigSchema = z.object({

package/src/pipeline/stages/execution.ts

@@ -218,6 +218,7 @@ export const executionStage: PipelineStage = {
       modelDef: resolveModel(ctx.config.models[ctx.routing.modelTier]),
       timeoutSeconds: ctx.config.execution.sessionTimeoutSeconds,
       dangerouslySkipPermissions: ctx.config.execution.dangerouslySkipPermissions,
+      maxInteractionTurns: ctx.config.agent?.maxInteractionTurns,
       pidRegistry: ctx.pidRegistry,
       featureName: ctx.prd.feature,
       storyId: ctx.story.id,

package/src/tdd/rectification-gate.ts

@@ -159,6 +159,7 @@ async function runRectificationLoop(
       modelDef: resolveModel(config.models[implementerTier]),
       timeoutSeconds: config.execution.sessionTimeoutSeconds,
       dangerouslySkipPermissions: config.execution.dangerouslySkipPermissions,
+      maxInteractionTurns: config.agent?.maxInteractionTurns,
       featureName,
       storyId: story.id,
       sessionRole: "implementer",

package/src/tdd/session-runner.ts

@@ -140,6 +140,7 @@ export async function runTddSession(
     modelDef: resolveModel(config.models[modelTier]),
     timeoutSeconds: config.execution.sessionTimeoutSeconds,
     dangerouslySkipPermissions: config.execution.dangerouslySkipPermissions,
+    maxInteractionTurns: config.agent?.maxInteractionTurns,
     featureName,
     storyId: story.id,
     sessionRole: role,

package/src/verification/rectification-loop.ts

@@ -74,6 +74,7 @@ export async function runRectificationLoop(opts: RectificationLoopOptions): Prom
       modelDef,
       timeoutSeconds: config.execution.sessionTimeoutSeconds,
       dangerouslySkipPermissions: config.execution.dangerouslySkipPermissions,
+      maxInteractionTurns: config.agent?.maxInteractionTurns,
     });
 
     if (agentResult.success) {

package/src/verification/strategies/scoped.ts

@@ -36,6 +36,18 @@ function buildScopedCommand(testFiles: string[], baseCommand: string, testScoped
   return _scopedDeps.buildSmartTestCommand(testFiles, baseCommand);
 }
 
+/**
+ * Returns true when the test command delegates to a monorepo orchestrator
+ * (Turborepo, Nx) that handles change-aware scoping natively.
+ *
+ * These tools use their own filter syntax (e.g. `--filter=...[HEAD~1]`,
+ * `nx affected`) — nax's smart test runner must not attempt to append
+ * file paths to such commands, as it would produce invalid syntax.
+ */
+export function isMonorepoOrchestratorCommand(command: string): boolean {
+  return /\bturbo\b/.test(command) || /\bnx\b/.test(command);
+}
+
 export class ScopedStrategy implements IVerificationStrategy {
   readonly name = "scoped" as const;
 
@@ -44,10 +56,16 @@ export class ScopedStrategy implements IVerificationStrategy {
     const smartCfg = coerceSmartRunner(ctx.smartRunnerConfig);
     const regressionMode = ctx.regressionMode ?? "deferred";
 
+    // Monorepo orchestrators (turbo, nx) handle change-aware scoping themselves.
+    // Skip nax's smart runner — appending file paths would produce invalid syntax.
+    // Also bypass deferred mode: run per-story so the orchestrator's own filter
+    // (e.g. --filter=...[HEAD~1]) can pick up the story's changes immediately.
+    const isMonorepoOrchestrator = isMonorepoOrchestratorCommand(ctx.testCommand);
+
     let effectiveCommand = ctx.testCommand;
     let isFullSuite = true;
 
-    if (smartCfg.enabled && ctx.storyGitRef) {
+    if (smartCfg.enabled && ctx.storyGitRef && !isMonorepoOrchestrator) {
       const sourceFiles = await _scopedDeps.getChangedSourceFiles(ctx.workdir, ctx.storyGitRef);
 
       const pass1Files = await _scopedDeps.mapSourceToTests(sourceFiles, ctx.workdir);
@@ -69,16 +87,22 @@ export class ScopedStrategy implements IVerificationStrategy {
       }
     }
 
-    // Defer to regression gate when no scoped tests found and mode is deferred
-    if (isFullSuite && regressionMode === "deferred") {
+    // Defer to regression gate when no scoped tests found and mode is deferred.
+    // Exception: monorepo orchestrators run per-story (they carry their own change filter).
+    if (isFullSuite && regressionMode === "deferred" && !isMonorepoOrchestrator) {
       logger.info("verify[scoped]", "No mapped tests — deferring to run-end (mode: deferred)", {
         storyId: ctx.storyId,
       });
       return makeSkippedResult(ctx.storyId, "scoped");
     }
 
-    if (isFullSuite) {
+    if (isFullSuite && !isMonorepoOrchestrator) {
       logger.info("verify[scoped]", "No mapped tests — falling back to full suite", { storyId: ctx.storyId });
+    } else if (isMonorepoOrchestrator) {
+      logger.info("verify[scoped]", "Monorepo orchestrator detected — delegating scoping to tool", {
+        storyId: ctx.storyId,
+        command: effectiveCommand,
+      });
     }
 
     const start = Date.now();