@nathapp/nax 0.45.0 → 0.46.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.45.0",
+  "version": "0.46.1",
   "description": "AI Coding Agent Orchestrator — loops until done",
   "type": "module",
   "bin": {

package/src/acceptance/generator.ts

@@ -124,7 +124,7 @@ Respond with ONLY the TypeScript test code (no markdown code fences, no explanat
     2,
   );
 
-  await _generatorPRDDeps.writeFile(join(options.workdir, "acceptance-refined.json"), refinedJsonContent);
+  await _generatorPRDDeps.writeFile(join(options.featureDir, "acceptance-refined.json"), refinedJsonContent);
 
   return { testCode, criteria };
 }

package/src/acceptance/types.ts

@@ -80,6 +80,8 @@ export interface GenerateFromPRDOptions {
   featureName: string;
   /** Working directory for context scanning */
   workdir: string;
+  /** Feature directory where acceptance-refined.json is written */
+  featureDir: string;
   /** Codebase context (file tree, dependencies, test patterns) */
   codebaseContext: string;
   /** Model tier to use for test generation */

package/src/agents/acp/adapter.ts

@@ -15,7 +15,7 @@ import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { resolvePermissions } from "../../config/permissions";
 import { getSafeLogger } from "../../logger";
-import { buildDecomposePrompt, parseDecomposeOutput } from "../claude-decompose";
+import { buildDecomposePrompt, parseDecomposeOutput } from "../shared/decompose";
 import { createSpawnAcpClient } from "./spawn-client";
 
 import type {
@@ -80,7 +80,14 @@ const DEFAULT_ENTRY: AgentRegistryEntry = {
 export interface AcpSessionResponse {
   messages: Array<{ role: string; content: string }>;
   stopReason: string;
-  cumulative_token_usage?: { input_tokens: number; output_tokens: number };
+  cumulative_token_usage?: {
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_input_tokens?: number;
+    cache_creation_input_tokens?: number;
+  };
+  /** Exact cost in USD from acpx usage_update event. Preferred over token-based estimation. */
+  exactCostUsd?: number;
 }
 
 export interface AcpSession {
@@ -555,7 +562,13 @@ export class AcpAgentAdapter implements AgentAdapter {
     // Tracks whether the run completed successfully — used by finally to decide
     // whether to close the session (success) or keep it open for retry (failure).
     const runState = { succeeded: false };
-    const totalTokenUsage = { input_tokens: 0, output_tokens: 0 };
+    const totalTokenUsage = {
+      input_tokens: 0,
+      output_tokens: 0,
+      cache_read_input_tokens: 0,
+      cache_creation_input_tokens: 0,
+    };
+    let totalExactCostUsd: number | undefined;
 
     try {
       // 5. Multi-turn loop
@@ -577,10 +590,16 @@ export class AcpAgentAdapter implements AgentAdapter {
         lastResponse = turnResult.response;
         if (!lastResponse) break;
 
-        // Accumulate token usage
+        // Accumulate token usage and exact cost
         if (lastResponse.cumulative_token_usage) {
           totalTokenUsage.input_tokens += lastResponse.cumulative_token_usage.input_tokens ?? 0;
           totalTokenUsage.output_tokens += lastResponse.cumulative_token_usage.output_tokens ?? 0;
+          totalTokenUsage.cache_read_input_tokens += lastResponse.cumulative_token_usage.cache_read_input_tokens ?? 0;
+          totalTokenUsage.cache_creation_input_tokens +=
+            lastResponse.cumulative_token_usage.cache_creation_input_tokens ?? 0;
+        }
+        if (lastResponse.exactCostUsd !== undefined) {
+          totalExactCostUsd = (totalExactCostUsd ?? 0) + lastResponse.exactCostUsd;
         }
 
         // Check for agent question → route to interaction bridge
@@ -643,10 +662,12 @@ export class AcpAgentAdapter implements AgentAdapter {
     const success = lastResponse?.stopReason === "end_turn";
     const output = extractOutput(lastResponse);
 
+    // Prefer exact cost from acpx usage_update; fall back to token-based estimation
     const estimatedCost =
-      totalTokenUsage.input_tokens > 0 || totalTokenUsage.output_tokens > 0
+      totalExactCostUsd ??
+      (totalTokenUsage.input_tokens > 0 || totalTokenUsage.output_tokens > 0
         ? estimateCostFromTokenUsage(totalTokenUsage, options.modelDef.model)
-        : 0;
+        : 0);
 
     return {
       success,
@@ -719,6 +740,13 @@ export class AcpAgentAdapter implements AgentAdapter {
           throw new CompleteError("complete() returned empty output");
         }
 
+        if (response.exactCostUsd !== undefined) {
+          getSafeLogger()?.info("acp-adapter", "complete() cost", {
+            costUsd: response.exactCostUsd,
+            model,
+          });
+        }
+
         return unwrapped;
       } catch (err) {
         const error = err instanceof Error ? err : new Error(String(err));

package/src/agents/acp/cost.ts

@@ -1,79 +1,9 @@
 /**
- * ACP cost estimation from token usage.
+ * ACP cost estimation — re-exports from the shared src/agents/cost/ module.
  *
- * Stub — implementation in ACP-006.
+ * Kept for zero-breakage backward compatibility.
+ * Import directly from src/agents/cost for new code.
  */
 
-/**
- * Token usage data from an ACP session's cumulative_token_usage field.
- */
-export interface SessionTokenUsage {
-  input_tokens: number;
-  output_tokens: number;
-  /** Cache read tokens — billed at a reduced rate */
-  cache_read_input_tokens?: number;
-  /** Cache creation tokens — billed at a higher creation rate */
-  cache_creation_input_tokens?: number;
-}
-
-/**
- * Per-model pricing in $/1M tokens: { input, output }
- */
-const MODEL_PRICING: Record<string, { input: number; output: number; cacheRead?: number; cacheCreation?: number }> = {
-  // Anthropic Claude models
-  "claude-sonnet-4": { input: 3, output: 15 },
-  "claude-sonnet-4-5": { input: 3, output: 15 },
-  "claude-haiku": { input: 0.8, output: 4.0, cacheRead: 0.1, cacheCreation: 1.0 },
-  "claude-haiku-4-5": { input: 0.8, output: 4.0, cacheRead: 0.1, cacheCreation: 1.0 },
-  "claude-opus": { input: 15, output: 75 },
-  "claude-opus-4": { input: 15, output: 75 },
-
-  // OpenAI models
-  "gpt-4.1": { input: 10, output: 30 },
-  "gpt-4": { input: 30, output: 60 },
-  "gpt-3.5-turbo": { input: 0.5, output: 1.5 },
-
-  // Google Gemini
-  "gemini-2.5-pro": { input: 0.075, output: 0.3 },
-  "gemini-2-pro": { input: 0.075, output: 0.3 },
-
-  // OpenAI Codex
-  codex: { input: 0.02, output: 0.06 },
-  "code-davinci-002": { input: 0.02, output: 0.06 },
-};
-
-/**
- * Calculate USD cost from ACP session token counts using per-model pricing.
- *
- * @param usage - Token counts from cumulative_token_usage
- * @param model - Model identifier (e.g., 'claude-sonnet-4', 'claude-haiku-4-5')
- * @returns Estimated cost in USD
- */
-export function estimateCostFromTokenUsage(usage: SessionTokenUsage, model: string): number {
-  const pricing = MODEL_PRICING[model];
-
-  if (!pricing) {
-    // Fallback: use average rate for unknown models
-    // Average of known rates: ~$5/1M tokens combined
-    const fallbackInputRate = 3 / 1_000_000;
-    const fallbackOutputRate = 15 / 1_000_000;
-    const inputCost = (usage.input_tokens ?? 0) * fallbackInputRate;
-    const outputCost = (usage.output_tokens ?? 0) * fallbackOutputRate;
-    const cacheReadCost = (usage.cache_read_input_tokens ?? 0) * (0.5 / 1_000_000);
-    const cacheCreationCost = (usage.cache_creation_input_tokens ?? 0) * (2 / 1_000_000);
-    return inputCost + outputCost + cacheReadCost + cacheCreationCost;
-  }
-
-  // Convert $/1M rates to $/token
-  const inputRate = pricing.input / 1_000_000;
-  const outputRate = pricing.output / 1_000_000;
-  const cacheReadRate = (pricing.cacheRead ?? pricing.input * 0.1) / 1_000_000;
-  const cacheCreationRate = (pricing.cacheCreation ?? pricing.input * 0.33) / 1_000_000;
-
-  const inputCost = (usage.input_tokens ?? 0) * inputRate;
-  const outputCost = (usage.output_tokens ?? 0) * outputRate;
-  const cacheReadCost = (usage.cache_read_input_tokens ?? 0) * cacheReadRate;
-  const cacheCreationCost = (usage.cache_creation_input_tokens ?? 0) * cacheCreationRate;
-
-  return inputCost + outputCost + cacheReadCost + cacheCreationCost;
-}
+export type { SessionTokenUsage } from "../cost";
+export { estimateCostFromTokenUsage } from "../cost";

package/src/agents/acp/index.ts

@@ -4,6 +4,4 @@
 
 export { AcpAgentAdapter, _acpAdapterDeps } from "./adapter";
 export { createSpawnAcpClient } from "./spawn-client";
-export { estimateCostFromTokenUsage } from "./cost";
-export type { SessionTokenUsage } from "./cost";
 export type { AgentRegistryEntry } from "./types";

package/src/agents/acp/parser.ts

@@ -2,11 +2,9 @@
  * ACP adapter — NDJSON and JSON-RPC output parsing helpers.
  *
  * Extracted from adapter.ts to keep that file within the 800-line limit.
- * Used only by _runOnce() (the spawn-based legacy path).
+ * Used by SpawnAcpSession.prompt() to parse acpx stdout.
  */
 
-import type { AgentRunOptions } from "../types";
-
 // ─────────────────────────────────────────────────────────────────────────────
 // Types
 // ─────────────────────────────────────────────────────────────────────────────
@@ -15,131 +13,86 @@ import type { AgentRunOptions } from "../types";
 export interface AcpxTokenUsage {
   input_tokens: number;
   output_tokens: number;
-}
-
-/** JSON-RPC message from acpx --format json --json-strict */
-interface JsonRpcMessage {
-  jsonrpc: "2.0";
-  method?: string;
-  params?: {
-    sessionId: string;
-    update?: {
-      sessionUpdate: string;
-      content?: { type: string; text?: string };
-      used?: number;
-      size?: number;
-      cost?: { amount: number; currency: string };
-    };
-  };
-  id?: number | string;
-  result?: unknown;
-  error?: { code: number; message: string };
+  cache_read_input_tokens?: number;
+  cache_creation_input_tokens?: number;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// streamJsonRpcEvents
+// parseAcpxJsonOutput
 // ─────────────────────────────────────────────────────────────────────────────
 
 /**
- * Stream stdout line-by-line, parse JSON-RPC, detect questions, call bridge.
+ * Parse acpx NDJSON output for assistant text, token usage, and exact cost.
+ *
+ * Handles the JSON-RPC envelope format emitted by acpx:
+ * - session/update agent_message_chunk → text accumulation
+ * - session/update usage_update → exact cost (cost.amount) + context size
+ * - id/result → token breakdown (inputTokens, outputTokens, cachedWriteTokens, cachedReadTokens)
+ *
+ * Also handles legacy flat NDJSON format for backward compatibility.
  */
-export async function streamJsonRpcEvents(
-  stdout: ReadableStream<Uint8Array>,
-  bridge: AgentRunOptions["interactionBridge"],
-  _sessionId: string,
-): Promise<{ text: string; tokenUsage?: AcpxTokenUsage }> {
-  let accumulatedText = "";
+export function parseAcpxJsonOutput(rawOutput: string): {
+  text: string;
+  tokenUsage?: AcpxTokenUsage;
+  exactCostUsd?: number;
+  stopReason?: string;
+  error?: string;
+} {
+  const lines = rawOutput.split("\n").filter((l) => l.trim());
+  let text = "";
   let tokenUsage: AcpxTokenUsage | undefined;
-  const decoder = new TextDecoder();
-  let buffer = "";
-
-  const reader = stdout.getReader();
-
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-
-      buffer += decoder.decode(value, { stream: true });
-      const lines = buffer.split("\n");
-      buffer = lines.pop() ?? "";
-
-      for (const line of lines) {
-        if (!line.trim()) continue;
+  let exactCostUsd: number | undefined;
+  let stopReason: string | undefined;
+  let error: string | undefined;
 
-        let msg: JsonRpcMessage;
-        try {
-          msg = JSON.parse(line);
-        } catch {
-          continue;
-        }
+  for (const line of lines) {
+    try {
+      const event = JSON.parse(line);
 
-        if (msg.method === "session/update" && msg.params?.update) {
-          const update = msg.params.update;
+      // ── JSON-RPC envelope format (acpx v0.3+) ──────────────────────────────
+      if (event.jsonrpc === "2.0") {
+        // session/update events
+        if (event.method === "session/update" && event.params?.update) {
+          const update = event.params.update;
 
+          // Text chunks
           if (
             update.sessionUpdate === "agent_message_chunk" &&
             update.content?.type === "text" &&
             update.content.text
           ) {
-            accumulatedText += update.content.text;
-
-            if (bridge?.detectQuestion && bridge.onQuestionDetected) {
-              const isQuestion = await bridge.detectQuestion(accumulatedText);
-              if (isQuestion) {
-                const response = await bridge.onQuestionDetected(accumulatedText);
-                accumulatedText += `\n\n[Human response: ${response}]`;
-              }
-            }
+            text += update.content.text;
           }
 
-          if (update.sessionUpdate === "usage_update" && update.used !== undefined) {
-            const total = update.used;
-            tokenUsage = {
-              input_tokens: Math.floor(total * 0.3),
-              output_tokens: Math.floor(total * 0.7),
-            };
+          // Exact cost from usage_update
+          if (update.sessionUpdate === "usage_update" && typeof update.cost?.amount === "number") {
+            exactCostUsd = update.cost.amount;
           }
         }
 
-        if (msg.result) {
-          const result = msg.result as Record<string, unknown>;
-          if (typeof result === "string") {
-            accumulatedText += result;
-          }
-        }
-      }
-    }
-  } finally {
-    reader.releaseLock();
-  }
-
-  return { text: accumulatedText.trim(), tokenUsage };
-}
+        // Final result with token breakdown (camelCase from acpx)
+        if (event.id !== undefined && event.result && typeof event.result === "object") {
+          const result = event.result as Record<string, unknown>;
 
-// ─────────────────────────────────────────────────────────────────────────────
-// parseAcpxJsonOutput
-// ─────────────────────────────────────────────────────────────────────────────
+          if (result.stopReason) stopReason = result.stopReason as string;
+          if (result.stop_reason) stopReason = result.stop_reason as string;
 
-/**
- * Parse acpx NDJSON output for assistant text and token usage.
- */
-export function parseAcpxJsonOutput(rawOutput: string): {
-  text: string;
-  tokenUsage?: AcpxTokenUsage;
-  stopReason?: string;
-  error?: string;
-} {
-  const lines = rawOutput.split("\n").filter((l) => l.trim());
-  let text = "";
-  let tokenUsage: AcpxTokenUsage | undefined;
-  let stopReason: string | undefined;
-  let error: string | undefined;
+          if (result.usage && typeof result.usage === "object") {
+            const u = result.usage as Record<string, unknown>;
+            tokenUsage = {
+              input_tokens: (u.inputTokens as number) ?? (u.input_tokens as number) ?? 0,
+              output_tokens: (u.outputTokens as number) ?? (u.output_tokens as number) ?? 0,
+              cache_read_input_tokens: (u.cachedReadTokens as number) ?? (u.cache_read_input_tokens as number) ?? 0,
+              cache_creation_input_tokens:
+                (u.cachedWriteTokens as number) ?? (u.cache_creation_input_tokens as number) ?? 0,
+            };
+          }
+        }
 
-  for (const line of lines) {
-    try {
-      const event = JSON.parse(line);
+        continue;
+      }
 
+      // ── Legacy flat NDJSON format ───────────────────────────────────────────
       if (event.content && typeof event.content === "string") text += event.content;
       if (event.text && typeof event.text === "string") text += event.text;
       if (event.result && typeof event.result === "string") text = event.result;
@@ -162,5 +115,5 @@ export function parseAcpxJsonOutput(rawOutput: string): {
     }
   }
 
-  return { text: text.trim(), tokenUsage, stopReason, error };
+  return { text: text.trim(), tokenUsage, exactCostUsd, stopReason, error };
 }

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

@@ -12,6 +12,8 @@
  *   acpx <agent> cancel                             → session.cancelActivePrompt()
  */
 
+import { homedir } from "node:os";
+import { isAbsolute } from "node:path";
 import type { PidRegistry } from "../../execution/pid-registry";
 import { getSafeLogger } from "../../logger";
 import type { AcpClient, AcpSession, AcpSessionResponse } from "./adapter";
@@ -60,11 +62,19 @@ export const _spawnClientDeps = {
 function buildAllowedEnv(extraEnv?: Record<string, string | undefined>): Record<string, string | undefined> {
   const allowed: Record<string, string | undefined> = {};
 
-  const essentialVars = ["PATH", "HOME", "TMPDIR", "NODE_ENV", "USER", "LOGNAME"];
+  const essentialVars = ["PATH", "TMPDIR", "NODE_ENV", "USER", "LOGNAME"];
   for (const varName of essentialVars) {
     if (process.env[varName]) allowed[varName] = process.env[varName];
   }
 
+  // Sanitize HOME — must be absolute path. Unexpanded "~" causes literal ~/dir in cwd.
+  const rawHome = process.env.HOME ?? "";
+  const safeHome = rawHome && isAbsolute(rawHome) ? rawHome : homedir();
+  if (rawHome !== safeHome) {
+    getSafeLogger()?.warn("env", `HOME env is not absolute ("${rawHome}"), falling back to os.homedir(): ${safeHome}`);
+  }
+  allowed.HOME = safeHome;
+
   const apiKeyVars = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GEMINI_API_KEY", "GOOGLE_API_KEY", "CLAUDE_API_KEY"];
   for (const varName of apiKeyVars) {
     if (process.env[varName]) allowed[varName] = process.env[varName];
@@ -180,8 +190,9 @@ class SpawnAcpSession implements AcpSession {
         const parsed = parseAcpxJsonOutput(stdout);
         return {
           messages: [{ role: "assistant", content: parsed.text || "" }],
-          stopReason: "end_turn",
+          stopReason: parsed.stopReason ?? "end_turn",
           cumulative_token_usage: parsed.tokenUsage,
+          exactCostUsd: parsed.exactCostUsd,
         };
       } catch (err) {
         getSafeLogger()?.warn("acp-adapter", "Failed to parse session prompt response", {

package/src/agents/{claude.ts → claude/adapter.ts}

@@ -4,15 +4,11 @@
  * Main adapter class coordinating execution, completion, decomposition, and interactive modes.
  */
 
-import { resolvePermissions } from "../config/permissions";
-import { PidRegistry } from "../execution/pid-registry";
-import { withProcessTimeout } from "../execution/timeout-handler";
-import { getLogger } from "../logger";
-import { _completeDeps, executeComplete } from "./claude-complete";
-import { buildDecomposePrompt, parseDecomposeOutput } from "./claude-decompose";
-import { _runOnceDeps, buildAllowedEnv, buildCommand, executeOnce } from "./claude-execution";
-import { runInteractiveMode } from "./claude-interactive";
-import { runPlan } from "./claude-plan";
+import { resolvePermissions } from "../../config/permissions";
+import { PidRegistry } from "../../execution/pid-registry";
+import { withProcessTimeout } from "../../execution/timeout-handler";
+import { getLogger } from "../../logger";
+import { buildDecomposePrompt, parseDecomposeOutput } from "../shared/decompose";
 import type {
   AgentAdapter,
   AgentCapabilities,
@@ -25,7 +21,11 @@ import type {
   PlanOptions,
   PlanResult,
   PtyHandle,
-} from "./types";
+} from "../types";
+import { _completeDeps, executeComplete } from "./complete";
+import { _runOnceDeps, buildAllowedEnv, buildCommand, executeOnce } from "./execution";
+import { runInteractiveMode } from "./interactive";
+import { runPlan } from "./plan";
 
 /**
  * Injectable dependencies for decompose() — allows tests to intercept
@@ -174,7 +174,7 @@ export class ClaudeCodeAdapter implements AgentAdapter {
   }
 
   async decompose(options: DecomposeOptions): Promise<DecomposeResult> {
-    const { resolveBalancedModelDef } = await import("./model-resolution");
+    const { resolveBalancedModelDef } = await import("../shared/model-resolution");
 
     const prompt = buildDecomposePrompt(options);
 
@@ -186,7 +186,10 @@ export class ClaudeCodeAdapter implements AgentAdapter {
       modelDef = resolveBalancedModelDef(options.config);
     }
 
-    const { skipPermissions } = resolvePermissions(options.config as import("../config").NaxConfig | undefined, "run");
+    const { skipPermissions } = resolvePermissions(
+      options.config as import("../../config").NaxConfig | undefined,
+      "run",
+    );
     const cmd = [this.binary, "--model", modelDef.model, "-p", prompt];
     if (skipPermissions) {
       cmd.splice(cmd.length - 2, 0, "--dangerously-skip-permissions");

package/src/agents/{claude-complete.ts → claude/complete.ts}

@@ -4,9 +4,9 @@
  * Standalone completion endpoint for simple prompts.
  */
 
-import { resolvePermissions } from "../config/permissions";
-import type { CompleteOptions } from "./types";
-import { CompleteError } from "./types";
+import { resolvePermissions } from "../../config/permissions";
+import type { CompleteOptions } from "../types";
+import { CompleteError } from "../types";
 
 /**
  * Injectable dependencies for complete() — allows tests to intercept

package/src/agents/claude/cost.ts

@@ -0,0 +1,16 @@
+/**
+ * Cost Tracking — re-exports from the shared src/agents/cost/ module.
+ *
+ * Kept for zero-breakage backward compatibility.
+ * Import directly from src/agents/cost for new code.
+ */
+
+export type { ModelCostRates, TokenUsage, CostEstimate, TokenUsageWithConfidence } from "../cost";
+export {
+  COST_RATES,
+  parseTokenUsage,
+  estimateCost,
+  estimateCostFromOutput,
+  estimateCostByDuration,
+  formatCostWithConfidence,
+} from "../cost";

package/src/agents/{claude-execution.ts → claude/execution.ts}

@@ -4,12 +4,14 @@
  * Handles building commands, preparing environment, and process execution.
  */
 
-import { resolvePermissions } from "../config/permissions";
-import type { PidRegistry } from "../execution/pid-registry";
-import { withProcessTimeout } from "../execution/timeout-handler";
-import { getLogger } from "../logger";
+import { homedir } from "node:os";
+import { isAbsolute } from "node:path";
+import { resolvePermissions } from "../../config/permissions";
+import type { PidRegistry } from "../../execution/pid-registry";
+import { withProcessTimeout } from "../../execution/timeout-handler";
+import { getLogger } from "../../logger";
+import type { AgentResult, AgentRunOptions } from "../types";
 import { estimateCostByDuration, estimateCostFromOutput } from "./cost";
-import type { AgentResult, AgentRunOptions } from "./types";
 
 /**
  * Maximum characters to capture from agent stdout.
@@ -65,13 +67,22 @@ export function buildCommand(binary: string, options: AgentRunOptions): string[]
 export function buildAllowedEnv(options: AgentRunOptions): Record<string, string | undefined> {
   const allowed: Record<string, string | undefined> = {};
 
-  const essentialVars = ["PATH", "HOME", "TMPDIR", "NODE_ENV", "USER", "LOGNAME"];
+  const essentialVars = ["PATH", "TMPDIR", "NODE_ENV", "USER", "LOGNAME"];
   for (const varName of essentialVars) {
     if (process.env[varName]) {
       allowed[varName] = process.env[varName];
     }
   }
 
+  // Sanitize HOME — must be absolute path. Unexpanded "~" causes literal ~/dir in cwd.
+  const rawHome = process.env.HOME ?? "";
+  const safeHome = rawHome && isAbsolute(rawHome) ? rawHome : homedir();
+  if (rawHome !== safeHome) {
+    const logger = getLogger();
+    logger.warn("env", `HOME env is not absolute ("${rawHome}"), falling back to os.homedir(): ${safeHome}`);
+  }
+  allowed.HOME = safeHome;
+
   const apiKeyVars = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"];
   for (const varName of apiKeyVars) {
     if (process.env[varName]) {

package/src/agents/claude/index.ts

@@ -0,0 +1,3 @@
+// Re-export everything external callers need from claude/
+export { ClaudeCodeAdapter, _completeDeps, _claudeAdapterDeps } from "./adapter";
+export { _runOnceDeps } from "./execution";

package/src/agents/{claude-interactive.ts → claude/interactive.ts}

@@ -4,10 +4,10 @@
  * Handles terminal UI interactions with the Claude agent.
  */
 
-import type { PidRegistry } from "../execution/pid-registry";
-import { getLogger } from "../logger";
-import { buildAllowedEnv } from "./claude-execution";
-import type { AgentRunOptions, InteractiveRunOptions, PtyHandle } from "./types";
+import type { PidRegistry } from "../../execution/pid-registry";
+import { getLogger } from "../../logger";
+import type { AgentRunOptions, InteractiveRunOptions, PtyHandle } from "../types";
+import { buildAllowedEnv } from "./execution";
 
 /**
  * Run Claude agent in interactive (TTY) mode for TUI output.

package/src/agents/{claude-plan.ts → claude/plan.ts}

@@ -7,13 +7,13 @@ import { join } from "node:path";
  * Extracted from claude.ts: plan(), buildPlanCommand()
  */
 
-import { resolvePermissions } from "../config/permissions";
-import type { PidRegistry } from "../execution/pid-registry";
-import { withProcessTimeout } from "../execution/timeout-handler";
-import { getLogger } from "../logger";
-import { resolveBalancedModelDef } from "./model-resolution";
-import type { AgentRunOptions } from "./types";
-import type { PlanOptions, PlanResult } from "./types-extended";
+import { resolvePermissions } from "../../config/permissions";
+import type { PidRegistry } from "../../execution/pid-registry";
+import { withProcessTimeout } from "../../execution/timeout-handler";
+import { getLogger } from "../../logger";
+import { resolveBalancedModelDef } from "../shared/model-resolution";
+import type { PlanOptions, PlanResult } from "../shared/types-extended";
+import type { AgentRunOptions } from "../types";
 
 /**
  * Build the CLI command for plan mode.
@@ -32,7 +32,10 @@ export function buildPlanCommand(binary: string, options: PlanOptions): string[]
   }
 
   // Resolve permission mode from config
-  const { skipPermissions } = resolvePermissions(options.config as import("../config").NaxConfig | undefined, "plan");
+  const { skipPermissions } = resolvePermissions(
+    options.config as import("../../config").NaxConfig | undefined,
+    "plan",
+  );
   if (skipPermissions) {
     cmd.push("--dangerously-skip-permissions");
   }
@@ -75,7 +78,7 @@ export async function runPlan(
   pidRegistry: PidRegistry,
   buildAllowedEnv: (options: AgentRunOptions) => Record<string, string | undefined>,
 ): Promise<PlanResult> {
-  const { resolveBalancedModelDef } = await import("./model-resolution");
+  const { resolveBalancedModelDef } = await import("../shared/model-resolution");
 
   const cmd = buildPlanCommand(binary, options);