@nathapp/nax 0.42.8 → 0.43.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.43.0] - 2026-03-16
+
+### Added
+- **PERM-001:** `src/config/permissions.ts` — `resolvePermissions(config, stage)` as the single source of truth for all permission decisions across CLI and ACP adapters.
+- **New types:** `PermissionProfile` (`"unrestricted" | "safe" | "scoped"`), `PipelineStage`, `ResolvedPermissions` interface.
+- **Schema:** `execution.permissionProfile` config field — takes precedence over legacy `dangerouslySkipPermissions` boolean. `"scoped"` is a Phase 2 stub.
+- **`pipelineStage?`** added to `AgentRunOptions` — each call site sets the appropriate stage (`"plan"`, `"run"`, `"rectification"`, etc.).
+- **`config?`** added to `CompleteOptions` — all `complete()` call sites now thread config so permissions are resolved correctly.
+
+### Fixed
+- **Hardcoded `--dangerously-skip-permissions`** in `claude-plan.ts` — now resolved from config.
+- **`?? false` fallback** in `plan.ts` — removed; replaced with `resolvePermissions()`.
+- **`?? true` fallback** in `claude-execution.ts` — removed; replaced with `resolvePermissions()`.
+- **`resolvePermissions(undefined, ...)` in ACP `complete()`** — now passes `_options?.config`.
+- All ACP adapter permission ternaries replaced with `resolvePermissions()`.
+
+### Changed
+- `nax/config.json` — explicit `"permissionProfile": "unrestricted"` (was implicit via schema default).
+
 ## [0.30.0] - 2026-03-08
 
 ### Fixed

package/bin/nax.ts

@@ -656,6 +656,14 @@ program
     // Load config
     const config = await loadConfig(workdir);
 
+    // Initialize logger — writes to nax/features/<feature>/plan-<timestamp>.jsonl
+    const featureLogDir = join(naxDir, "features", options.feature);
+    mkdirSync(featureLogDir, { recursive: true });
+    const planLogId = new Date().toISOString().replace(/:/g, "-").replace(/\..+/, "");
+    const planLogPath = join(featureLogDir, `plan-${planLogId}.jsonl`);
+    initLogger({ level: "info", filePath: planLogPath, useChalk: false, headless: true });
+    console.log(chalk.dim(`   [Plan log: ${planLogPath}]`));
+
     try {
       const prdPath = await planCommand(workdir, config, {
         from: options.from,
@@ -666,6 +674,7 @@ program
 
       console.log(chalk.green("\n[OK] PRD generated"));
       console.log(chalk.dim(`   PRD: ${prdPath}`));
+      console.log(chalk.dim(`   Log: ${planLogPath}`));
       console.log(chalk.dim(`\nNext: nax run -f ${options.feature}`));
     } catch (err) {
       console.error(chalk.red(`Error: ${(err as Error).message}`));

package/dist/nax.js

@@ -2552,6 +2552,24 @@ var require_commander = __commonJS((exports) => {
   exports.InvalidOptionArgumentError = InvalidArgumentError;
 });
 
+// src/config/permissions.ts
+function resolvePermissions(config, _stage) {
+  const profile = config?.execution?.permissionProfile ?? (config?.execution?.dangerouslySkipPermissions ? "unrestricted" : "safe");
+  switch (profile) {
+    case "unrestricted":
+      return { mode: "approve-all", skipPermissions: true };
+    case "safe":
+      return { mode: "approve-reads", skipPermissions: false };
+    case "scoped":
+      return resolveScopedPermissions(config, _stage);
+    default:
+      return { mode: "approve-reads", skipPermissions: false };
+  }
+}
+function resolveScopedPermissions(_config, _stage) {
+  return { mode: "approve-reads", skipPermissions: false };
+}
+
 // src/logging/types.ts
 var EMOJI;
 var init_types = __esm(() => {
@@ -3244,6 +3262,10 @@ async function executeComplete(binary, prompt, options) {
   if (options?.jsonMode) {
     cmd.push("--output-format", "json");
   }
+  const { skipPermissions } = resolvePermissions(options?.config, "complete");
+  if (skipPermissions) {
+    cmd.push("--dangerously-skip-permissions");
+  }
   const spawnOpts = { stdout: "pipe", stderr: "pipe" };
   if (options?.workdir)
     spawnOpts.cwd = options.workdir;
@@ -3501,7 +3523,7 @@ var init_cost = __esm(() => {
 // src/agents/claude-execution.ts
 function buildCommand(binary, options) {
   const model = options.modelDef.model;
-  const skipPermissions = options.dangerouslySkipPermissions ?? true;
+  const { skipPermissions } = resolvePermissions(options.config, options.pipelineStage ?? "run");
   const permArgs = skipPermissions ? ["--dangerously-skip-permissions"] : [];
   return [binary, "--model", model, ...permArgs, "-p", options.prompt];
 }
@@ -17619,6 +17641,12 @@ var init_schemas3 = __esm(() => {
     lintCommand: exports_external.string().nullable().optional(),
     typecheckCommand: exports_external.string().nullable().optional(),
     dangerouslySkipPermissions: exports_external.boolean().default(true),
+    permissionProfile: exports_external.enum(["unrestricted", "safe", "scoped"]).optional(),
+    permissions: exports_external.record(exports_external.string(), exports_external.object({
+      mode: exports_external.enum(["approve-all", "approve-reads", "scoped"]),
+      allowedTools: exports_external.array(exports_external.string()).optional(),
+      inherit: exports_external.string().optional()
+    })).optional(),
     smartTestRunner: smartTestRunnerFieldSchema
   });
   QualityConfigSchema = exports_external.object({
@@ -18104,7 +18132,10 @@ function buildPlanCommand(binary, options) {
   if (modelDef) {
     cmd.push("--model", modelDef.model);
   }
-  cmd.push("--dangerously-skip-permissions");
+  const { skipPermissions } = resolvePermissions(options.config, "plan");
+  if (skipPermissions) {
+    cmd.push("--dangerously-skip-permissions");
+  }
   let fullPrompt = options.prompt;
   if (options.codebaseContext) {
     fullPrompt = `${options.codebaseContext}
@@ -18306,7 +18337,11 @@ class ClaudeCodeAdapter {
       }
       modelDef = resolveBalancedModelDef2(options.config);
     }
-    const cmd = [this.binary, "--model", modelDef.model, "--dangerously-skip-permissions", "-p", prompt];
+    const { skipPermissions } = resolvePermissions(options.config, "run");
+    const cmd = [this.binary, "--model", modelDef.model, "-p", prompt];
+    if (skipPermissions) {
+      cmd.splice(cmd.length - 2, 0, "--dangerously-skip-permissions");
+    }
     const pidRegistry = this.getPidRegistry(options.workdir);
     const proc = _decomposeDeps.spawn(cmd, {
       cwd: options.workdir,
@@ -18497,7 +18532,8 @@ async function refineAcceptanceCriteria(criteria, context) {
     response = await _refineDeps.adapter.complete(prompt, {
       jsonMode: true,
       maxTokens: 4096,
-      model: modelDef.model
+      model: modelDef.model,
+      config: config2
     });
   } catch (error48) {
     const reason = errorMessage(error48);
@@ -18579,7 +18615,7 @@ describe("${options.featureName} - Acceptance Tests", () => {
 
 Respond with ONLY the TypeScript test code (no markdown code fences, no explanation).`;
   logger.info("acceptance", "Generating tests from PRD refined criteria", { count: refinedCriteria.length });
-  const testCode = await _generatorPRDDeps.adapter.complete(prompt);
+  const testCode = await _generatorPRDDeps.adapter.complete(prompt, { config: options.config });
   const refinedJsonContent = JSON.stringify(refinedCriteria.map((c, i) => ({
     acId: `AC-${i + 1}`,
     original: c.original,
@@ -18702,7 +18738,8 @@ async function generateAcceptanceTests(adapter, options) {
   const prompt = buildAcceptanceTestPrompt(criteria, options.featureName, options.codebaseContext);
   try {
     const output = await adapter.complete(prompt, {
-      model: options.modelDef.model
+      model: options.modelDef.model,
+      config: options.config
     });
     const testCode = extractTestCode(output);
     return {
@@ -18823,7 +18860,8 @@ async function generateFixStories(adapter, options) {
     const prompt = buildFixPrompt(failedAC, acText, testOutput, relatedStories, prd);
     try {
       const fixDescription = await adapter.complete(prompt, {
-        model: modelDef.model
+        model: modelDef.model,
+        config: options.config
       });
       fixStories.push({
         id: `US-FIX-${String(i + 1).padStart(3, "0")}`,
@@ -19120,7 +19158,7 @@ class SpawnAcpClient {
       pidRegistry: this.pidRegistry
     });
   }
-  async loadSession(sessionName, agentName) {
+  async loadSession(sessionName, agentName, permissionMode) {
     const cmd = ["acpx", "--cwd", this.cwd, agentName, "sessions", "ensure", "--name", sessionName];
     const proc = _spawnClientDeps.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
     const exitCode = await proc.exited;
@@ -19133,7 +19171,7 @@ class SpawnAcpClient {
       cwd: this.cwd,
       model: this.model,
       timeoutSeconds: this.timeoutSeconds,
-      permissionMode: this.permissionMode,
+      permissionMode,
       env: this.env,
       pidRegistry: this.pidRegistry
     });
@@ -19224,7 +19262,7 @@ async function ensureAcpSession(client, sessionName, agentName, permissionMode)
   }
   if (client.loadSession) {
     try {
-      const existing = await client.loadSession(sessionName, agentName);
+      const existing = await client.loadSession(sessionName, agentName, permissionMode);
       if (existing) {
         getSafeLogger()?.debug("acp-adapter", `Resumed existing session: ${sessionName}`);
         return existing;
@@ -19409,11 +19447,11 @@ 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" : "approve-reads";
+    const resolvedPerm = resolvePermissions(options.config, options.pipelineStage ?? "run");
+    const permissionMode = resolvedPerm.mode;
     getSafeLogger()?.info("acp-adapter", "Permission mode resolved", {
       permission: permissionMode,
-      dangerouslySkipPermissions: options.dangerouslySkipPermissions ?? false,
-      stage: options.featureName ? "run" : "plan"
+      stage: options.pipelineStage ?? "run"
     });
     const session = await ensureAcpSession(client, sessionName, this.name, permissionMode);
     if (options.featureName && options.storyId) {
@@ -19494,7 +19532,7 @@ class AcpAgentAdapter {
   async complete(prompt, _options) {
     const model = _options?.model ?? "default";
     const timeoutMs = _options?.timeoutMs ?? 120000;
-    const permissionMode = _options?.dangerouslySkipPermissions ? "approve-all" : "default";
+    const permissionMode = resolvePermissions(_options?.config, "complete").mode;
     const workdir = _options?.workdir;
     let lastError;
     for (let attempt = 0;attempt < MAX_RATE_LIMIT_RETRIES; attempt++) {
@@ -19574,7 +19612,9 @@ class AcpAgentAdapter {
       modelTier: options.modelTier ?? "balanced",
       modelDef,
       timeoutSeconds,
-      dangerouslySkipPermissions: options.dangerouslySkipPermissions ?? false,
+      dangerouslySkipPermissions: resolvePermissions(options.config, "plan").skipPermissions,
+      pipelineStage: "plan",
+      config: options.config,
       interactionBridge: options.interactionBridge,
       maxInteractionTurns: options.maxInteractionTurns,
       featureName: options.featureName,
@@ -19596,7 +19636,11 @@ class AcpAgentAdapter {
     const prompt = buildDecomposePrompt(options);
     let output;
     try {
-      output = await this.complete(prompt, { model, jsonMode: true });
+      output = await this.complete(prompt, {
+        model,
+        jsonMode: true,
+        config: options.config
+      });
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       throw new Error(`[acp-adapter] decompose() failed: ${msg}`, { cause: err });
@@ -20854,7 +20898,7 @@ async function callLlmOnce(adapter, modelTier, prompt, config2, timeoutMs) {
     }, timeoutMs);
   });
   timeoutPromise.catch(() => {});
-  const outputPromise = adapter.complete(prompt, { model: modelArg });
+  const outputPromise = adapter.complete(prompt, { model: modelArg, config: config2 });
   try {
     const result = await Promise.race([outputPromise, timeoutPromise]);
     clearTimeout(timeoutId);
@@ -21924,7 +21968,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@nathapp/nax",
-    version: "0.42.8",
+    version: "0.43.0",
     description: "AI Coding Agent Orchestrator \u2014 loops until done",
     type: "module",
     bin: {
@@ -21997,8 +22041,8 @@ var init_version = __esm(() => {
   NAX_VERSION = package_default.version;
   NAX_COMMIT = (() => {
     try {
-      if (/^[0-9a-f]{6,10}$/.test("5dc5b37"))
-        return "5dc5b37";
+      if (/^[0-9a-f]{6,10}$/.test("d725ea0"))
+        return "d725ea0";
     } catch {}
     try {
       const result = Bun.spawnSync(["git", "rev-parse", "--short", "HEAD"], {
@@ -23230,7 +23274,8 @@ class AutoInteractionPlugin {
     }
     const output = await adapter.complete(prompt, {
       ...modelArg && { model: modelArg },
-      jsonMode: true
+      jsonMode: true,
+      ...this.config.naxConfig && { config: this.config.naxConfig }
     });
     return this.parseResponse(output);
   }
@@ -26315,7 +26360,9 @@ async function runRectificationLoop(story, config2, workdir, agent, implementerT
       modelTier: implementerTier,
       modelDef: resolveModel(config2.models[implementerTier]),
       timeoutSeconds: config2.execution.sessionTimeoutSeconds,
-      dangerouslySkipPermissions: config2.execution.dangerouslySkipPermissions,
+      dangerouslySkipPermissions: resolvePermissions(config2, "rectification").skipPermissions,
+      pipelineStage: "rectification",
+      config: config2,
       maxInteractionTurns: config2.agent?.maxInteractionTurns,
       featureName,
       storyId: story.id,
@@ -26923,7 +26970,9 @@ async function runTddSession(role, agent, story, config2, workdir, modelTier, be
     modelTier,
     modelDef: resolveModel(config2.models[modelTier]),
     timeoutSeconds: config2.execution.sessionTimeoutSeconds,
-    dangerouslySkipPermissions: config2.execution.dangerouslySkipPermissions,
+    dangerouslySkipPermissions: resolvePermissions(config2, "run").skipPermissions,
+    pipelineStage: "run",
+    config: config2,
     maxInteractionTurns: config2.agent?.maxInteractionTurns,
     featureName,
     storyId: story.id,
@@ -27673,7 +27722,9 @@ Category: ${tddResult.failureCategory ?? "unknown"}`,
         modelTier: ctx.routing.modelTier,
         modelDef: resolveModel(ctx.config.models[ctx.routing.modelTier]),
         timeoutSeconds: ctx.config.execution.sessionTimeoutSeconds,
-        dangerouslySkipPermissions: ctx.config.execution.dangerouslySkipPermissions,
+        dangerouslySkipPermissions: resolvePermissions(ctx.config, "run").skipPermissions,
+        pipelineStage: "run",
+        config: ctx.config,
         maxInteractionTurns: ctx.config.agent?.maxInteractionTurns,
         pidRegistry: ctx.pidRegistry,
         featureName: ctx.prd.feature,
@@ -28223,7 +28274,9 @@ ${rectificationPrompt}`;
       modelTier,
       modelDef,
       timeoutSeconds: config2.execution.sessionTimeoutSeconds,
-      dangerouslySkipPermissions: config2.execution.dangerouslySkipPermissions,
+      dangerouslySkipPermissions: resolvePermissions(config2, "rectification").skipPermissions,
+      pipelineStage: "rectification",
+      config: config2,
       maxInteractionTurns: config2.agent?.maxInteractionTurns
     });
     if (agentResult.success) {
@@ -28944,7 +28997,7 @@ async function runDecompose(story, prd, config2, _workdir, agentGetFn) {
   }
   const adapter = {
     async decompose(prompt) {
-      return agent.complete(prompt, { jsonMode: true });
+      return agent.complete(prompt, { jsonMode: true, config: config2 });
     }
   };
   return DecomposeBuilder.for(story).prd(prd).config(builderConfig).decompose(adapter);
@@ -65845,7 +65898,7 @@ async function planCommand(workdir, config2, options) {
     const cliAdapter = _deps2.getAgent(agentName);
     if (!cliAdapter)
       throw new Error(`[plan] No agent adapter found for '${agentName}'`);
-    rawResponse = await cliAdapter.complete(prompt, { jsonMode: true, workdir });
+    rawResponse = await cliAdapter.complete(prompt, { jsonMode: true, workdir, config: config2 });
     try {
       const envelope = JSON.parse(rawResponse);
       if (envelope?.type === "result" && typeof envelope?.result === "string") {
@@ -65859,13 +65912,12 @@ async function planCommand(workdir, config2, options) {
       throw new Error(`[plan] No agent adapter found for '${agentName}'`);
     const interactionBridge = createCliInteractionBridge();
     const pidRegistry = new PidRegistry(workdir);
-    const dangerouslySkipPermissions = config2?.execution?.dangerouslySkipPermissions ?? false;
-    const permissionMode = dangerouslySkipPermissions ? "approve-all" : "approve-reads";
+    const resolvedPerm = resolvePermissions(config2, "plan");
     const resolvedModel = config2?.plan?.model ?? "balanced";
     logger?.info("plan", "Starting interactive planning session", {
       agent: agentName,
       model: resolvedModel,
-      permission: permissionMode,
+      permission: resolvedPerm.mode,
       workdir,
       feature: options.feature,
       timeoutSeconds
@@ -65880,7 +65932,7 @@ async function planCommand(workdir, config2, options) {
         interactionBridge,
         config: config2,
         modelTier: resolvedModel,
-        dangerouslySkipPermissions,
+        dangerouslySkipPermissions: resolvedPerm.skipPermissions,
         maxInteractionTurns: config2?.agent?.maxInteractionTurns,
         featureName: options.feature,
         pidRegistry
@@ -76996,6 +77048,12 @@ Use: nax plan -f <feature> --from <spec>`));
     process.exit(1);
   }
   const config2 = await loadConfig(workdir);
+  const featureLogDir = join43(naxDir, "features", options.feature);
+  mkdirSync6(featureLogDir, { recursive: true });
+  const planLogId = new Date().toISOString().replace(/:/g, "-").replace(/\..+/, "");
+  const planLogPath = join43(featureLogDir, `plan-${planLogId}.jsonl`);
+  initLogger({ level: "info", filePath: planLogPath, useChalk: false, headless: true });
+  console.log(source_default.dim(`   [Plan log: ${planLogPath}]`));
   try {
     const prdPath = await planCommand(workdir, config2, {
       from: options.from,
@@ -77006,6 +77064,7 @@ Use: nax plan -f <feature> --from <spec>`));
     console.log(source_default.green(`
 [OK] PRD generated`));
     console.log(source_default.dim(`   PRD: ${prdPath}`));
+    console.log(source_default.dim(`   Log: ${planLogPath}`));
     console.log(source_default.dim(`
 Next: nax run -f ${options.feature}`));
   } catch (err) {

package/package.json

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

package/src/acceptance/fix-generator.ts

@@ -228,6 +228,7 @@ export async function generateFixStories(
       // Call adapter to generate fix description
       const fixDescription = await adapter.complete(prompt, {
         model: modelDef.model,
+        config: options.config,
       });
 
       fixStories.push({

package/src/acceptance/generator.ts

@@ -110,7 +110,7 @@ Respond with ONLY the TypeScript test code (no markdown code fences, no explanat
 
   logger.info("acceptance", "Generating tests from PRD refined criteria", { count: refinedCriteria.length });
 
-  const testCode = await _generatorPRDDeps.adapter.complete(prompt);
+  const testCode = await _generatorPRDDeps.adapter.complete(prompt, { config: options.config });
 
   const refinedJsonContent = JSON.stringify(
     refinedCriteria.map((c, i) => ({
@@ -298,6 +298,7 @@ export async function generateAcceptanceTests(
     // Call adapter to generate tests
     const output = await adapter.complete(prompt, {
       model: options.modelDef.model,
+      config: options.config,
     });
 
     // Extract test code from output

package/src/acceptance/refinement.ts

@@ -192,6 +192,7 @@ export async function refineAcceptanceCriteria(
       jsonMode: true,
       maxTokens: 4096,
       model: modelDef.model,
+      config,
     });
   } catch (error) {
     const reason = errorMessage(error);

package/src/agents/acp/adapter.ts

@@ -13,6 +13,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 { createSpawnAcpClient } from "./spawn-client";
@@ -92,7 +93,7 @@ export interface AcpClient {
   start(): Promise<void>;
   createSession(opts: { agentName: string; permissionMode: string; sessionName?: string }): Promise<AcpSession>;
   /** Resume an existing named session. Returns null if the session is not found. */
-  loadSession?(sessionName: string, agentName: string): Promise<AcpSession | null>;
+  loadSession?(sessionName: string, agentName: string, permissionMode: string): Promise<AcpSession | null>;
   close(): Promise<void>;
 }
 
@@ -192,7 +193,7 @@ export async function ensureAcpSession(
   // Try to resume existing session first
   if (client.loadSession) {
     try {
-      const existing = await client.loadSession(sessionName, agentName);
+      const existing = await client.loadSession(sessionName, agentName, permissionMode);
       if (existing) {
         getSafeLogger()?.debug("acp-adapter", `Resumed existing session: ${sessionName}`);
         return existing;
@@ -451,12 +452,12 @@ export class AcpAgentAdapter implements AgentAdapter {
     }
     sessionName ??= buildSessionName(options.workdir, options.featureName, options.storyId, options.sessionRole);
 
-    // 2. Permission mode follows dangerouslySkipPermissions, default is "approve-reads". or should --deny-all be the default?
-    const permissionMode = options.dangerouslySkipPermissions ? "approve-all" : "approve-reads";
+    // 2. Resolve permission mode from config via single source of truth.
+    const resolvedPerm = resolvePermissions(options.config, options.pipelineStage ?? "run");
+    const permissionMode = resolvedPerm.mode;
     getSafeLogger()?.info("acp-adapter", "Permission mode resolved", {
       permission: permissionMode,
-      dangerouslySkipPermissions: options.dangerouslySkipPermissions ?? false,
-      stage: options.featureName ? "run" : "plan",
+      stage: options.pipelineStage ?? "run",
     });
 
     // 3. Ensure session (resume existing or create new)
@@ -567,7 +568,7 @@ export class AcpAgentAdapter implements AgentAdapter {
   async complete(prompt: string, _options?: CompleteOptions): Promise<string> {
     const model = _options?.model ?? "default";
     const timeoutMs = _options?.timeoutMs ?? 120_000; // 2-min safety net by default
-    const permissionMode = _options?.dangerouslySkipPermissions ? "approve-all" : "default";
+    const permissionMode = resolvePermissions(_options?.config, "complete").mode;
     const workdir = _options?.workdir;
 
     let lastError: Error | undefined;
@@ -677,7 +678,12 @@ export class AcpAgentAdapter implements AgentAdapter {
       modelTier: options.modelTier ?? "balanced",
       modelDef,
       timeoutSeconds,
-      dangerouslySkipPermissions: options.dangerouslySkipPermissions ?? false,
+      dangerouslySkipPermissions: resolvePermissions(
+        options.config as import("../../config").NaxConfig | undefined,
+        "plan",
+      ).skipPermissions,
+      pipelineStage: "plan",
+      config: options.config as import("../../config").NaxConfig | undefined,
       interactionBridge: options.interactionBridge,
       maxInteractionTurns: options.maxInteractionTurns,
       featureName: options.featureName,
@@ -704,7 +710,11 @@ export class AcpAgentAdapter implements AgentAdapter {
 
     let output: string;
     try {
-      output = await this.complete(prompt, { model, jsonMode: true });
+      output = await this.complete(prompt, {
+        model,
+        jsonMode: true,
+        config: options.config as import("../../config").NaxConfig | undefined,
+      });
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       throw new Error(`[acp-adapter] decompose() failed: ${msg}`, { cause: err });

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

@@ -316,7 +316,7 @@ export class SpawnAcpClient implements AcpClient {
     });
   }
 
-  async loadSession(sessionName: string, agentName: string): Promise<AcpSession | null> {
+  async loadSession(sessionName: string, agentName: string, permissionMode: string): Promise<AcpSession | null> {
     // Try to ensure session exists — if it does, acpx returns success
     const cmd = ["acpx", "--cwd", this.cwd, agentName, "sessions", "ensure", "--name", sessionName];
 
@@ -333,7 +333,7 @@ export class SpawnAcpClient implements AcpClient {
       cwd: this.cwd,
       model: this.model,
       timeoutSeconds: this.timeoutSeconds,
-      permissionMode: this.permissionMode,
+      permissionMode,
       env: this.env,
       pidRegistry: this.pidRegistry,
     });

package/src/agents/claude-complete.ts

@@ -4,6 +4,7 @@
  * Standalone completion endpoint for simple prompts.
  */
 
+import { resolvePermissions } from "../config/permissions";
 import type { CompleteOptions } from "./types";
 import { CompleteError } from "./types";
 
@@ -51,6 +52,11 @@ export async function executeComplete(binary: string, prompt: string, options?:
     cmd.push("--output-format", "json");
   }
 
+  const { skipPermissions } = resolvePermissions(options?.config, "complete");
+  if (skipPermissions) {
+    cmd.push("--dangerously-skip-permissions");
+  }
+
   const spawnOpts: { stdout: "pipe"; stderr: "pipe"; cwd?: string } = { stdout: "pipe", stderr: "pipe" };
   if (options?.workdir) spawnOpts.cwd = options.workdir;
   const proc = _completeDeps.spawn(cmd, spawnOpts);

package/src/agents/claude-execution.ts

@@ -4,6 +4,7 @@
  * 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";
@@ -49,7 +50,7 @@ export const _runOnceDeps = {
  */
 export function buildCommand(binary: string, options: AgentRunOptions): string[] {
   const model = options.modelDef.model;
-  const skipPermissions = options.dangerouslySkipPermissions ?? true;
+  const { skipPermissions } = resolvePermissions(options.config, options.pipelineStage ?? "run");
   const permArgs = skipPermissions ? ["--dangerously-skip-permissions"] : [];
   return [binary, "--model", model, ...permArgs, "-p", options.prompt];
 }

package/src/agents/claude-plan.ts

@@ -7,6 +7,7 @@ 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";
@@ -30,8 +31,11 @@ export function buildPlanCommand(binary: string, options: PlanOptions): string[]
     cmd.push("--model", modelDef.model);
   }
 
-  // Add dangerously-skip-permissions for automation
-  cmd.push("--dangerously-skip-permissions");
+  // Resolve permission mode from config
+  const { skipPermissions } = resolvePermissions(options.config as import("../config").NaxConfig | undefined, "plan");
+  if (skipPermissions) {
+    cmd.push("--dangerously-skip-permissions");
+  }
 
   // Add prompt with codebase context and input file if available
   let fullPrompt = options.prompt;

package/src/agents/claude.ts

@@ -4,6 +4,7 @@
  * 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";
@@ -185,7 +186,11 @@ export class ClaudeCodeAdapter implements AgentAdapter {
       modelDef = resolveBalancedModelDef(options.config);
     }
 
-    const cmd = [this.binary, "--model", modelDef.model, "--dangerously-skip-permissions", "-p", prompt];
+    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");
+    }
 
     const pidRegistry = this.getPidRegistry(options.workdir);
 

package/src/agents/types.ts

@@ -6,6 +6,7 @@
  * collect results from them uniformly.
  */
 
+import type { NaxConfig } from "../config";
 import type { ModelDef, ModelTier } from "../config/schema";
 
 // Re-export extended types for backward compatibility
@@ -76,6 +77,10 @@ export interface AgentRunOptions {
   sessionRole?: string;
   /** Max turns in multi-turn interaction loop when interactionBridge is active (default: 10) */
   maxInteractionTurns?: number;
+  /** Pipeline stage this run belongs to — used by resolvePermissions() (default: "run") */
+  pipelineStage?: import("../config/permissions").PipelineStage;
+  /** Full nax config — passed through so adapters can call resolvePermissions() */
+  config?: NaxConfig;
 }
 
 /**
@@ -114,6 +119,11 @@ export interface CompleteOptions {
    * Callers may also wrap complete() in their own Promise.race for shorter timeouts.
    */
   timeoutMs?: number;
+  /**
+   * Full nax config — used by resolvePermissions() to determine permission mode.
+   * Pass when available so complete() honours permissionProfile / dangerouslySkipPermissions.
+   */
+  config?: NaxConfig;
 }
 
 /**

package/src/analyze/classifier.ts

@@ -120,6 +120,7 @@ async function classifyWithLLM(
     jsonMode: true,
     maxTokens: 4096,
     model: modelDef.model,
+    config,
   });
 
   // Parse JSON response

package/src/cli/analyze.ts

@@ -229,7 +229,7 @@ async function runDecomposeDefault(
   }
   const adapter = {
     async decompose(prompt: string): Promise<string> {
-      return agent.complete(prompt, { jsonMode: true });
+      return agent.complete(prompt, { jsonMode: true, config });
     },
   };
   return DecomposeBuilder.for(story).prd(prd).config(builderConfig).decompose(adapter);

package/src/cli/plan.ts

@@ -15,6 +15,7 @@ import type { AgentAdapter } from "../agents/types";
 import { scanCodebase } from "../analyze/scanner";
 import type { CodebaseScan } from "../analyze/types";
 import type { NaxConfig } from "../config";
+import { resolvePermissions } from "../config/permissions";
 import { PidRegistry } from "../execution/pid-registry";
 import { getLogger } from "../logger";
 import { validatePlanOutput } from "../prd/schema";
@@ -108,7 +109,7 @@ export async function planCommand(workdir: string, config: NaxConfig, options: P
     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, workdir });
+    rawResponse = await cliAdapter.complete(prompt, { jsonMode: true, workdir, config });
     // CLI adapter returns {"type":"result","result":"..."} envelope — unwrap it
     try {
       const envelope = JSON.parse(rawResponse) as Record<string, unknown>;
@@ -125,13 +126,12 @@ export async function planCommand(workdir: string, config: NaxConfig, options: P
     if (!adapter) throw new Error(`[plan] No agent adapter found for '${agentName}'`);
     const interactionBridge = createCliInteractionBridge();
     const pidRegistry = new PidRegistry(workdir);
-    const dangerouslySkipPermissions = config?.execution?.dangerouslySkipPermissions ?? false;
-    const permissionMode = dangerouslySkipPermissions ? "approve-all" : "approve-reads";
+    const resolvedPerm = resolvePermissions(config, "plan");
     const resolvedModel = config?.plan?.model ?? "balanced";
     logger?.info("plan", "Starting interactive planning session", {
       agent: agentName,
       model: resolvedModel,
-      permission: permissionMode,
+      permission: resolvedPerm.mode,
       workdir,
       feature: options.feature,
       timeoutSeconds,
@@ -146,7 +146,7 @@ export async function planCommand(workdir: string, config: NaxConfig, options: P
         interactionBridge,
         config,
         modelTier: resolvedModel,
-        dangerouslySkipPermissions,
+        dangerouslySkipPermissions: resolvedPerm.skipPermissions,
         maxInteractionTurns: config?.agent?.maxInteractionTurns,
         featureName: options.feature,
         pidRegistry,

package/src/config/permissions.ts

@@ -0,0 +1,63 @@
+/**
+ * Permission Resolver — Single Source of Truth
+ *
+ * All adapters call resolvePermissions() to determine permission mode.
+ * No local fallbacks allowed elsewhere in the codebase.
+ *
+ * Phase 1: permissionProfile field + legacy boolean backward compat.
+ * Phase 2: per-stage scoped allowlists (stub below).
+ */
+
+import type { NaxConfig } from "./schema";
+
+export type PermissionProfile = "unrestricted" | "safe" | "scoped";
+
+export type PipelineStage =
+  | "plan"
+  | "run"
+  | "verify"
+  | "review"
+  | "rectification"
+  | "regression"
+  | "acceptance"
+  | "complete";
+
+export interface ResolvedPermissions {
+  /** ACP permission mode string */
+  mode: "approve-all" | "approve-reads" | "default";
+  /** CLI adapter: whether to pass --dangerously-skip-permissions */
+  skipPermissions: boolean;
+  /** Future: scoped tool allowlist (Phase 2) */
+  allowedTools?: string[];
+}
+
+/**
+ * Resolve permissions for a given pipeline stage.
+ * Single source of truth — all adapters call this.
+ *
+ * Precedence: permissionProfile > dangerouslySkipPermissions boolean > safe default.
+ */
+export function resolvePermissions(config: NaxConfig | undefined, _stage: PipelineStage): ResolvedPermissions {
+  const profile: PermissionProfile =
+    config?.execution?.permissionProfile ?? (config?.execution?.dangerouslySkipPermissions ? "unrestricted" : "safe");
+
+  switch (profile) {
+    case "unrestricted":
+      return { mode: "approve-all", skipPermissions: true };
+    case "safe":
+      return { mode: "approve-reads", skipPermissions: false };
+    case "scoped":
+      return resolveScopedPermissions(config, _stage);
+    default:
+      return { mode: "approve-reads", skipPermissions: false };
+  }
+}
+
+/**
+ * Phase 2 stub — resolves per-stage permissions from config block.
+ * Returns safe defaults until Phase 2 is implemented.
+ */
+function resolveScopedPermissions(_config: NaxConfig | undefined, _stage: PipelineStage): ResolvedPermissions {
+  // Phase 2 implementation goes here
+  return { mode: "approve-reads", skipPermissions: false };
+}

package/src/config/runtime-types.ts

@@ -97,6 +97,17 @@ export interface ExecutionConfig {
   typecheckCommand?: string | null;
   /** Use --dangerously-skip-permissions flag for agent (default: true for backward compat, SEC-1 fix) */
   dangerouslySkipPermissions?: boolean;
+  /** Permission profile — takes precedence over dangerouslySkipPermissions (Phase 1) */
+  permissionProfile?: "unrestricted" | "safe" | "scoped";
+  /** Per-stage permission overrides — only read when permissionProfile = "scoped" (Phase 2) */
+  permissions?: Record<
+    string,
+    {
+      mode: "approve-all" | "approve-reads" | "scoped";
+      allowedTools?: string[];
+      inherit?: string;
+    }
+  >;
   /** Enable smart test runner to scope test runs to changed files (default: true).
    * Accepts boolean for backward compat or a SmartTestRunnerConfig object. */
   smartTestRunner?: boolean | SmartTestRunnerConfig;

package/src/config/schemas.ts

@@ -105,7 +105,21 @@ const ExecutionConfigSchema = z.object({
     .default(2000),
   lintCommand: z.string().nullable().optional(),
   typecheckCommand: z.string().nullable().optional(),
+  // DEPRECATED — use permissionProfile instead. Kept for backward compat.
   dangerouslySkipPermissions: z.boolean().default(true),
+  // NEW — takes precedence over dangerouslySkipPermissions
+  permissionProfile: z.enum(["unrestricted", "safe", "scoped"]).optional(),
+  // Phase 2: per-stage permission overrides (only read when profile = "scoped")
+  permissions: z
+    .record(
+      z.string(),
+      z.object({
+        mode: z.enum(["approve-all", "approve-reads", "scoped"]),
+        allowedTools: z.array(z.string()).optional(),
+        inherit: z.string().optional(),
+      }),
+    )
+    .optional(),
   smartTestRunner: smartTestRunnerFieldSchema,
 });
 

package/src/interaction/plugins/auto.ts

@@ -156,6 +156,7 @@ export class AutoInteractionPlugin implements InteractionPlugin {
     const output = await adapter.complete(prompt, {
       ...(modelArg && { model: modelArg }),
       jsonMode: true,
+      ...(this.config.naxConfig && { config: this.config.naxConfig }),
     });
 
     return this.parseResponse(output);

package/src/pipeline/stages/execution.ts

@@ -32,6 +32,7 @@
 
 import { getAgent, validateAgentForTier } from "../../agents";
 import { resolveModel } from "../../config";
+import { resolvePermissions } from "../../config/permissions";
 import { checkMergeConflict, checkStoryAmbiguity, isTriggerEnabled } from "../../interaction/triggers";
 import { getLogger } from "../../logger";
 import type { FailureCategory } from "../../tdd";
@@ -217,7 +218,9 @@ export const executionStage: PipelineStage = {
       modelTier: ctx.routing.modelTier,
       modelDef: resolveModel(ctx.config.models[ctx.routing.modelTier]),
       timeoutSeconds: ctx.config.execution.sessionTimeoutSeconds,
-      dangerouslySkipPermissions: ctx.config.execution.dangerouslySkipPermissions,
+      dangerouslySkipPermissions: resolvePermissions(ctx.config, "run").skipPermissions,
+      pipelineStage: "run",
+      config: ctx.config,
       maxInteractionTurns: ctx.config.agent?.maxInteractionTurns,
       pidRegistry: ctx.pidRegistry,
       featureName: ctx.prd.feature,

package/src/pipeline/stages/routing.ts

@@ -66,7 +66,7 @@ async function runDecompose(
   }
   const adapter = {
     async decompose(prompt: string): Promise<string> {
-      return agent.complete(prompt, { jsonMode: true });
+      return agent.complete(prompt, { jsonMode: true, config });
     },
   };
 

package/src/routing/strategies/llm.ts

@@ -111,7 +111,7 @@ async function callLlmOnce(
   // Prevent unhandled rejection if timer fires between race resolution and clearTimeout
   timeoutPromise.catch(() => {});
 
-  const outputPromise = adapter.complete(prompt, { model: modelArg });
+  const outputPromise = adapter.complete(prompt, { model: modelArg, config });
 
   try {
     const result = await Promise.race([outputPromise, timeoutPromise]);

package/src/tdd/rectification-gate.ts

@@ -9,6 +9,7 @@
 import type { AgentAdapter } from "../agents";
 import type { ModelTier, NaxConfig } from "../config";
 import { resolveModel } from "../config";
+import { resolvePermissions } from "../config/permissions";
 import type { getLogger } from "../logger";
 import type { UserStory } from "../prd";
 import { autoCommitIfDirty, captureGitRef } from "../utils/git";
@@ -158,7 +159,9 @@ async function runRectificationLoop(
       modelTier: implementerTier,
       modelDef: resolveModel(config.models[implementerTier]),
       timeoutSeconds: config.execution.sessionTimeoutSeconds,
-      dangerouslySkipPermissions: config.execution.dangerouslySkipPermissions,
+      dangerouslySkipPermissions: resolvePermissions(config, "rectification").skipPermissions,
+      pipelineStage: "rectification",
+      config,
       maxInteractionTurns: config.agent?.maxInteractionTurns,
       featureName,
       storyId: story.id,

package/src/tdd/session-runner.ts

@@ -7,6 +7,7 @@
 import type { AgentAdapter } from "../agents";
 import type { ModelTier, NaxConfig } from "../config";
 import { resolveModel } from "../config";
+import { resolvePermissions } from "../config/permissions";
 import { getLogger } from "../logger";
 import type { UserStory } from "../prd";
 import { PromptBuilder } from "../prompts";
@@ -139,7 +140,9 @@ export async function runTddSession(
     modelTier,
     modelDef: resolveModel(config.models[modelTier]),
     timeoutSeconds: config.execution.sessionTimeoutSeconds,
-    dangerouslySkipPermissions: config.execution.dangerouslySkipPermissions,
+    dangerouslySkipPermissions: resolvePermissions(config, "run").skipPermissions,
+    pipelineStage: "run",
+    config,
     maxInteractionTurns: config.agent?.maxInteractionTurns,
     featureName,
     storyId: story.id,

package/src/verification/rectification-loop.ts

@@ -10,6 +10,7 @@
 import { getAgent } from "../agents";
 import type { NaxConfig } from "../config";
 import { resolveModel } from "../config";
+import { resolvePermissions } from "../config/permissions";
 import { parseBunTestOutput } from "../execution/test-output-parser";
 import { getSafeLogger } from "../logger";
 import type { UserStory } from "../prd";
@@ -73,7 +74,9 @@ export async function runRectificationLoop(opts: RectificationLoopOptions): Prom
       modelTier,
       modelDef,
       timeoutSeconds: config.execution.sessionTimeoutSeconds,
-      dangerouslySkipPermissions: config.execution.dangerouslySkipPermissions,
+      dangerouslySkipPermissions: resolvePermissions(config, "rectification").skipPermissions,
+      pipelineStage: "rectification",
+      config,
       maxInteractionTurns: config.agent?.maxInteractionTurns,
     });