@cruxy/cli 0.4.0 → 0.7.0

package/dist/approval/prompt.js

@@ -0,0 +1,212 @@
+import path from "node:path";
+import pc from "picocolors";
+/** Cap on rendered preview lines before collapsing the rest. */
+const PREVIEW_MAX_LINES = 40;
+/**
+ * Render the action, read one key, and map it to a {@link PromptChoice}. `n`/`t`
+ * read a follow-up line (reason / instruction). Anything else — including EOF —
+ * is a reject.
+ */
+export async function promptForApproval(request, io) {
+    io.write(render(request, io.color));
+    const key = (await io.readKey()).toLowerCase();
+    io.write("\n");
+    switch (key) {
+        case "y":
+            return { kind: "once" };
+        case "a":
+            return { kind: "session" };
+        case "n": {
+            io.write("  reason (optional, sent to the agent): ");
+            const reason = (await io.readLine()).trim();
+            return reason ? { kind: "reject", reason } : { kind: "reject" };
+        }
+        case "t": {
+            io.write("  what should the agent do instead? ");
+            const instruction = (await io.readLine()).trim();
+            return instruction
+                ? { kind: "instruct", instruction }
+                : { kind: "reject" };
+        }
+        default:
+            // n/a key, empty, EOF, Ctrl-C → default-deny.
+            return { kind: "reject" };
+    }
+}
+/** Render the full prompt block: header, detail (diff or command+cwd), choices. */
+export function render(request, color) {
+    const c = pc.createColors(color);
+    const destructive = request.tier === "destructive";
+    const mark = destructive ? c.red(c.bold("!")) : c.yellow("?");
+    const label = destructive ? c.red(c.bold(" (destructive)")) : "";
+    const lines = [];
+    lines.push(`${mark} cruxy wants to ${c.bold(request.summary)}${label}`);
+    lines.push(detail(request, c));
+    lines.push(choices(request.scope, c));
+    return lines.filter((l) => l !== "").join("\n") + " ";
+}
+/** The action detail: a diff for file actions, the command + cwd for shell. */
+function detail(request, c) {
+    if (request.action.kind === "shell") {
+        return [
+            `  ${c.dim("$")} ${request.action.command ?? ""}`,
+            `  ${c.dim(`in ${request.cwd}`)}`,
+        ].join("\n");
+    }
+    return renderPreview(request.action.preview, c);
+}
+/** The choices line, including a short label of what an `a` grant would cover. */
+function choices(scope, c) {
+    const grant = scopeLabel(scope);
+    const a = grant === null
+        ? `${c.dim("[a] allow this kind (n/a here)")}`
+        : `[a] allow ${c.bold(grant)} this session`;
+    return `  ${c.dim("[y] approve once ·")} ${a} ${c.dim("· [n] reject · [t] reject & instruct:")}`;
+}
+/** Short human label for what a session grant would allow, or null if none. */
+function scopeLabel(scope) {
+    if (scope.kind === "shell-prefix")
+        return `${scope.token} commands`;
+    if (scope.kind === "file-subtree")
+        return `changes under ${path.basename(scope.root)}/`;
+    return null;
+}
+// ── diff rendering (shared with the old C.6 renderer) ──────────────────────────
+function diffLines(oldStr, newStr, c) {
+    const removed = oldStr.split("\n").map((l) => c.red(`- ${l}`));
+    const added = newStr.split("\n").map((l) => c.green(`+ ${l}`));
+    return [...removed, ...added];
+}
+function renderPatchFiles(files, c) {
+    const out = [];
+    for (const file of files) {
+        if (file.op === "delete") {
+            out.push(c.red(`delete ${file.path}`));
+        }
+        else if (file.op === "create") {
+            out.push(c.green(`create ${file.path}`));
+            out.push(...file.lines.map((l) => c.green(`+ ${l}`)));
+            if (file.omittedLines > 0)
+                out.push(c.dim(`  ...${file.omittedLines} more lines`));
+        }
+        else {
+            out.push(c.yellow(`update ${file.path}`));
+            for (const hunk of file.hunks)
+                out.push(...diffLines(hunk.oldStr, hunk.newStr, c));
+        }
+    }
+    return out;
+}
+/** Render a `vcs` pull-request publish plan: branch, commit, and PR body. */
+function renderPrPreview(preview, c) {
+    const out = [];
+    out.push(`${c.bold("branch")}  ${c.green(preview.branch)} → ${preview.base}`);
+    out.push("");
+    out.push(c.bold("commit"));
+    out.push(`  ${preview.commitSubject}`);
+    for (const line of bodyLines(preview.commitBody))
+        out.push(c.dim(`  ${line}`));
+    out.push("");
+    out.push(`${c.bold("pull request")}  ${preview.prTitle}`);
+    for (const line of bodyLines(preview.prBody))
+        out.push(c.dim(`  ${line}`));
+    return out;
+}
+/** Split a multi-line body into trimmed-of-trailing lines, dropping a trailing blank. */
+function bodyLines(body) {
+    const lines = body.replace(/\s+$/, "").split("\n");
+    return lines.length === 1 && lines[0] === "" ? [] : lines;
+}
+function renderPreview(preview, c) {
+    if (!preview)
+        return "";
+    let lines;
+    if (preview.type === "edit") {
+        lines = diffLines(preview.oldStr, preview.newStr, c);
+    }
+    else if (preview.type === "patch") {
+        lines = renderPatchFiles(preview.files, c);
+    }
+    else if (preview.type === "pr") {
+        lines = renderPrPreview(preview, c);
+    }
+    else {
+        const header = preview.exists
+            ? c.yellow("OVERWRITE existing")
+            : c.green("create");
+        const body = preview.lines.map((l) => `  ${l}`);
+        if (preview.omittedLines > 0)
+            body.push(c.dim(`  ...${preview.omittedLines} more lines`));
+        lines = [header, ...body];
+    }
+    if (lines.length > PREVIEW_MAX_LINES) {
+        const hidden = lines.length - PREVIEW_MAX_LINES;
+        lines = [...lines.slice(0, PREVIEW_MAX_LINES), c.dim(`...${hidden} more`)];
+    }
+    return lines.map((l) => `  ${l}`).join("\n");
+}
+// ── default stdin-backed PromptIO ──────────────────────────────────────────────
+/** Build the real PromptIO: prompt to stderr, read keys/lines from stdin. */
+export function defaultPromptIO(color) {
+    return {
+        write: (text) => void process.stderr.write(text),
+        readKey: readKeyFromStdin,
+        readLine: readLineFromStdin,
+        color,
+    };
+}
+/** Read a single keypress in raw mode; "" on EOF. Always restores cooked mode. */
+function readKeyFromStdin() {
+    const stdin = process.stdin;
+    return new Promise((resolve) => {
+        const cleanup = () => {
+            stdin.removeListener("data", onData);
+            stdin.removeListener("end", onEnd);
+            if (stdin.isTTY)
+                stdin.setRawMode(false);
+            stdin.pause();
+        };
+        const onData = (buf) => {
+            cleanup();
+            resolve(buf.toString("utf8").slice(0, 1));
+        };
+        const onEnd = () => {
+            cleanup();
+            resolve("");
+        };
+        if (stdin.isTTY)
+            stdin.setRawMode(true);
+        stdin.resume();
+        stdin.once("data", onData);
+        stdin.once("end", onEnd);
+    });
+}
+/** Read one line in cooked mode; "" on EOF. */
+function readLineFromStdin() {
+    const stdin = process.stdin;
+    return new Promise((resolve) => {
+        let buf = "";
+        const cleanup = () => {
+            stdin.removeListener("data", onData);
+            stdin.removeListener("end", onEnd);
+            stdin.pause();
+        };
+        const onData = (chunk) => {
+            buf += chunk.toString("utf8");
+            const nl = buf.indexOf("\n");
+            if (nl !== -1) {
+                cleanup();
+                resolve(buf.slice(0, nl).replace(/\r$/, ""));
+            }
+        };
+        const onEnd = () => {
+            cleanup();
+            resolve(buf.replace(/\r$/, ""));
+        };
+        if (stdin.isTTY)
+            stdin.setRawMode(false);
+        stdin.resume();
+        stdin.on("data", onData);
+        stdin.once("end", onEnd);
+    });
+}

package/dist/approval/service.d.ts

@@ -0,0 +1,36 @@
+import type { ApproveAction } from "../tools/types.js";
+import { type PromptIO } from "./prompt.js";
+import type { ApprovalDecision, ApprovalPolicy } from "./types.js";
+/**
+ * The approval gate, called by the tool layer **before any side effect**. It
+ * classifies the action, lets read-only actions through, **throws
+ * CRUXY_E_APPROVAL_REQUIRED when it can't ask** (non-interactive — default-deny,
+ * never auto-approve), and otherwise defers to the policy. It owns the
+ * per-session allowlist, so a new service ⇒ a fresh session.
+ */
+export interface ApprovalServiceOptions {
+    /** Resolved project root the actions run in. */
+    cwd: string;
+    /** Whether cruxy can actually prompt (stdin is a TTY). */
+    interactive: boolean;
+    /** Override the decision policy (the seam — tests / a future CI policy). */
+    policy?: ApprovalPolicy;
+    /** Override the prompt I/O (tests script keys/lines). */
+    io?: PromptIO;
+}
+export declare class ApprovalService {
+    private readonly cwd;
+    private readonly interactive;
+    private readonly allowlist;
+    private readonly policy;
+    constructor(opts: ApprovalServiceOptions);
+    /**
+     * Decide whether `action` may proceed. Read-only ⇒ allow. Non-interactive ⇒
+     * throw {@link approvalRequired} (the U.5 error system, exit 10). Otherwise the
+     * policy prompts. A returned `{allow:false}` is a clean rejection (fed back to
+     * the agent), not an error.
+     */
+    requestApproval(action: ApproveAction): Promise<ApprovalDecision>;
+    /** Clear all session grants (a fresh session). */
+    resetSession(): void;
+}

package/dist/approval/service.js

@@ -0,0 +1,37 @@
+import { approvalRequired } from "../errors/index.js";
+import { shouldUseColor } from "../errors/index.js";
+import { classify } from "./classify.js";
+import { InteractivePolicy, SessionAllowlist } from "./policy.js";
+import { defaultPromptIO } from "./prompt.js";
+export class ApprovalService {
+    cwd;
+    interactive;
+    allowlist = new SessionAllowlist();
+    policy;
+    constructor(opts) {
+        this.cwd = opts.cwd;
+        this.interactive = opts.interactive;
+        this.policy =
+            opts.policy ??
+                new InteractivePolicy(this.allowlist, opts.io ?? defaultPromptIO(shouldUseColor()));
+    }
+    /**
+     * Decide whether `action` may proceed. Read-only ⇒ allow. Non-interactive ⇒
+     * throw {@link approvalRequired} (the U.5 error system, exit 10). Otherwise the
+     * policy prompts. A returned `{allow:false}` is a clean rejection (fed back to
+     * the agent), not an error.
+     */
+    async requestApproval(action) {
+        const request = classify(action, this.cwd);
+        if (request.tier === "read")
+            return { allow: true };
+        if (!this.interactive) {
+            throw approvalRequired(request.summary);
+        }
+        return this.policy.decide(request);
+    }
+    /** Clear all session grants (a fresh session). */
+    resetSession() {
+        this.allowlist.clear();
+    }
+}

package/dist/approval/types.d.ts

@@ -0,0 +1,64 @@
+import type { ApproveAction } from "../tools/types.js";
+/**
+ * Types for the approval gate (U.3) — the security boundary between the agent
+ * and side-effecting actions. The gate is **default-deny**: no response means
+ * reject, never auto-approve.
+ */
+/**
+ * Risk classification for a pending action. Friction is reserved for what's
+ * risky, so users don't rubber-stamp.
+ * - `read` — read-only, auto-allowed (read tools bypass the gate entirely).
+ * - `mutate` — reversible-ish mutation (file write/edit) → approve, normal style.
+ * - `destructive` — irreversible / high blast radius (shell, delete) → approve,
+ *   visually distinct. **Unknown actions classify here.**
+ */
+export type RiskTier = "read" | "mutate" | "destructive";
+/**
+ * The tight scope a session grant is keyed by. Never blanket.
+ * - `shell-prefix` — a command's leading program token (e.g. `git`); only ever
+ *   matches commands we can *positively* prove are simple (no shell features).
+ * - `file-subtree` — an absolute directory (or, under the root-cap, an exact
+ *   file path); matches targets that resolve inside it.
+ * - `none` — nothing safe to grant (e.g. a multi-file patch spanning the root).
+ */
+export type Scope = {
+    readonly kind: "shell-prefix";
+    readonly token: string;
+} | {
+    readonly kind: "file-subtree";
+    readonly root: string;
+} | {
+    readonly kind: "none";
+};
+/** A pending action, classified and ready to show / decide on. */
+export interface ApprovalRequest {
+    /** The raw tool action (kind, path/command, preview). */
+    readonly action: ApproveAction;
+    /** Risk classification. */
+    readonly tier: RiskTier;
+    /** The tight scope a session grant would use. */
+    readonly scope: Scope;
+    /** One plain line describing the action (e.g. "run: git status"). */
+    readonly summary: string;
+    /** Absolute resolved target paths for file actions; `[]` for shell. */
+    readonly targets: readonly string[];
+    /** Resolved project root the action runs in (shown as the shell cwd). */
+    readonly cwd: string;
+}
+/**
+ * The gate's verdict. On reject, `feedback` (if any) is fed back to the agent as
+ * the tool result so it can adapt — a rejection is data, not an error.
+ */
+export type ApprovalDecision = {
+    readonly allow: true;
+} | {
+    readonly allow: false;
+    readonly feedback?: string;
+};
+/**
+ * Pluggable decision strategy — the seam. Only `InteractivePolicy` ships in U.3;
+ * a future non-interactive/CI policy slots in here without touching call sites.
+ */
+export interface ApprovalPolicy {
+    decide(request: ApprovalRequest): Promise<ApprovalDecision>;
+}

package/dist/approval/types.js

@@ -0,0 +1 @@
+export {};

package/dist/cli/commands/init.d.ts

@@ -0,0 +1,7 @@
+import { Command } from "commander";
+/**
+ * `cruxy init` — set up a project (U.6): ensure a key (acquired only if missing),
+ * offer to scaffold a project `CRUXY.md`, and offer a first-win demo run. Like
+ * `login`, it's interactive-only.
+ */
+export declare function initCommand(): Command;

package/dist/cli/commands/init.js

@@ -0,0 +1,40 @@
+import { Command } from "commander";
+import pc from "picocolors";
+import { logger } from "../../utils/logger.js";
+import { loadConfig } from "../../config/index.js";
+import { createDefaultDeps, defaultOnboardingIO, runOnboarding, } from "../../onboarding/index.js";
+import { runFirstWinTask } from "../onboard.js";
+/**
+ * `cruxy init` — set up a project (U.6): ensure a key (acquired only if missing),
+ * offer to scaffold a project `CRUXY.md`, and offer a first-win demo run. Like
+ * `login`, it's interactive-only.
+ */
+export function initCommand() {
+    return new Command("init")
+        .description("set up cruxy in this project (key + CRUXY.md + a first run)")
+        .action(async () => {
+        if (!process.stdin.isTTY) {
+            logger.print(pc.dim("cruxy init is interactive — run it in a terminal, or export your key as an environment variable."));
+            process.exitCode = 1;
+            return;
+        }
+        const cwd = process.cwd();
+        const { config } = loadConfig();
+        const result = await runOnboarding({
+            provider: config.model.provider,
+            mode: "init",
+            offerScaffold: true,
+            offerFirstWin: true,
+            io: defaultOnboardingIO(),
+            deps: createDefaultDeps({
+                config,
+                cwd,
+                runTask: (prompt) => runFirstWinTask(config, cwd, prompt),
+            }),
+        });
+        if (!result.completed) {
+            logger.print(pc.dim("setup not completed — run `cruxy init` again to resume."));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/login.d.ts

@@ -0,0 +1,8 @@
+import { Command } from "commander";
+/**
+ * `cruxy login` — set or replace the API key on demand (U.6). Runs the key step
+ * of onboarding (always, even if a key already resolves — this is how you
+ * re-key / switch), validates it live, and persists it to the credentials store.
+ * Non-interactive invocations fail loud rather than hang.
+ */
+export declare function loginCommand(): Command;

package/dist/cli/commands/login.js

@@ -0,0 +1,36 @@
+import { Command } from "commander";
+import pc from "picocolors";
+import { logger } from "../../utils/logger.js";
+import { loadConfig } from "../../config/index.js";
+import { createDefaultDeps, defaultOnboardingIO, runOnboarding, } from "../../onboarding/index.js";
+/**
+ * `cruxy login` — set or replace the API key on demand (U.6). Runs the key step
+ * of onboarding (always, even if a key already resolves — this is how you
+ * re-key / switch), validates it live, and persists it to the credentials store.
+ * Non-interactive invocations fail loud rather than hang.
+ */
+export function loginCommand() {
+    return new Command("login")
+        .description("set or replace your API key (validated, saved to ~/.cruxy)")
+        .action(async () => {
+        if (!process.stdin.isTTY) {
+            logger.print(pc.dim("cruxy login is interactive — run it in a terminal, or export your key as an environment variable."));
+            process.exitCode = 1;
+            return;
+        }
+        const { config } = loadConfig();
+        const result = await runOnboarding({
+            provider: config.model.provider,
+            mode: "login",
+            forceKey: true,
+            offerFirstWin: false,
+            offerScaffold: false,
+            io: defaultOnboardingIO(),
+            deps: createDefaultDeps({ config, cwd: process.cwd() }),
+        });
+        if (!result.completed) {
+            logger.print(pc.dim("login not completed."));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/pr.d.ts

@@ -0,0 +1,8 @@
+import { Command } from "commander";
+/**
+ * `cruxy pr` — turn the current changes into a pull request (C.15). Generates the
+ * branch name, conventional commit, and PR title/body from the diff with the
+ * model, then runs branch → commit → push → open-PR behind the one U.3 approval.
+ * The forge token comes from the environment / `gh`; it's never prompted or stored.
+ */
+export declare function prCommand(): Command;

package/dist/cli/commands/pr.js

@@ -0,0 +1,87 @@
+import { Command } from "commander";
+import pc from "picocolors";
+import { createProvider } from "@cruxy/sdk";
+import { logger } from "../../utils/logger.js";
+import { loadConfig, resolveApiKey } from "../../config/index.js";
+import { authMissingKey } from "../../errors/index.js";
+import { ApprovalService } from "../../approval/index.js";
+import { createForgeProvider, createPrService, generateWithLlm, loadCommitGuidance, resolveForgeToken, } from "../../vcs/index.js";
+/**
+ * `cruxy pr` — turn the current changes into a pull request (C.15). Generates the
+ * branch name, conventional commit, and PR title/body from the diff with the
+ * model, then runs branch → commit → push → open-PR behind the one U.3 approval.
+ * The forge token comes from the environment / `gh`; it's never prompted or stored.
+ */
+export function prCommand() {
+    return new Command("pr")
+        .description("open a pull request from the current changes (generated + gated)")
+        .option("-b, --base <branch>", "base branch to merge into")
+        .option("-t, --title <title>", "PR title (conventional-commit subject)")
+        .option("--body <body>", "PR body")
+        .option("--draft", "open the pull request as a draft")
+        .action(async (opts) => {
+        const cwd = process.cwd();
+        const { config } = loadConfig();
+        // The model writes the PR content, so we need a provider key just like
+        // `cruxy run`. The forge token is resolved separately (env / gh).
+        const apiKey = resolveApiKey(config.model.provider);
+        if (!apiKey) {
+            throw authMissingKey(config.model.provider, apiKeyEnvVar(config.model.provider));
+        }
+        const provider = createProvider({
+            provider: config.model.provider,
+            apiKey,
+            model: config.model.model,
+            maxTokens: config.model.maxTokens,
+            temperature: config.model.temperature,
+            gatewayUrl: config.cruxy.gatewayUrl,
+        });
+        // resolveForgeToken throws CRUXY_E_FORGE_AUTH (exit 4) if none is found.
+        const forge = createForgeProvider(resolveForgeToken());
+        const guidance = await loadCommitGuidance(cwd);
+        const approval = new ApprovalService({
+            cwd,
+            interactive: Boolean(process.stdin.isTTY),
+        });
+        const service = createPrService({
+            cwd,
+            config,
+            forge,
+            requestApproval: (action) => approval.requestApproval(action),
+            generate: (i) => generateWithLlm(provider, {
+                ...i,
+                scopes: guidance.scopes,
+                skillBody: guidance.skillBody,
+            }),
+        });
+        logger.info(pc.dim("generating pull request content…"));
+        const outcome = await service.openPullRequest({
+            base: opts.base,
+            title: opts.title,
+            body: opts.body,
+            draft: opts.draft,
+        });
+        if (!outcome.approved) {
+            logger.print(pc.yellow("pull request not opened — approval declined."));
+            if (outcome.feedback)
+                logger.print(pc.dim(outcome.feedback));
+            return;
+        }
+        const label = outcome.alreadyExists
+            ? "a pull request already exists"
+            : "opened pull request";
+        logger.print(`${pc.green("✓")} ${label} (${outcome.branch} → ${outcome.base})`);
+        logger.print(pc.cyan(outcome.url));
+    });
+}
+/** Environment variable that holds the API key for a provider. */
+function apiKeyEnvVar(provider) {
+    switch (provider) {
+        case "anthropic":
+            return "ANTHROPIC_API_KEY";
+        case "openai":
+            return "OPENAI_API_KEY";
+        default:
+            return "CRUXY_API_KEY";
+    }
+}

package/dist/cli/commands/run.js

@@ -1,20 +1,17 @@
 import { Command } from "commander";
 import pc from "picocolors";
-import { createProvider } from "@cruxy/sdk";
 import { logger } from "../../utils/logger.js";
-import { loadConfig, resolveApiKey, loadProjectInstructions, } from "../../config/index.js";
+import { loadConfig, resolveApiKey } from "../../config/index.js";
 import { authMissingKey, usageError } from "../../errors/index.js";
-import { buildDefaultRegistry } from "../../tools/index.js";
-import { Session, createApprover } from "../../agent/index.js";
 import { runInteractive } from "../repl.js";
 import { createStreamPrinter } from "../stream-print.js";
-import { getGitInfo } from "../../utils/git.js";
+import { buildAgentSession } from "../session-factory.js";
+import { apiKeyEnvVar, maybeRunOnboarding } from "../onboard.js";
 export function runCommand() {
     return new Command("run")
         .description("run cruxy on a prompt (one-shot), or with no prompt for an interactive session")
         .argument("[prompt...]", "the task for cruxy to perform (omit for interactive)")
-        .option("-y, --yes", "auto-approve all tool actions (run unattended)")
-        .option("--dangerously-approve", "alias for --yes: approve every action without prompting")
+        .option("--plan", "plan mode: propose a step-by-step plan for approval before executing")
         .action(async (promptParts, opts) => {
         const prompt = promptParts.join(" ").trim();
         const interactive = prompt === "";
@@ -24,44 +21,36 @@ export function runCommand() {
             throw usageError("cruxy run needs a prompt when stdin is not a terminal", ['provide a task, e.g. cruxy run "fix the failing test"']);
         }
         const { config, sources } = loadConfig();
-        const apiKey = resolveApiKey(config.model.provider);
+        let apiKey = resolveApiKey(config.model.provider);
         logger.info(pc.dim(`model:   ${config.model.provider}/${config.model.model}`));
         logger.info(pc.dim(`config:  ${sources.project ?? sources.global ?? "defaults"}`));
+        // First-run with no key (and a TTY) → guided onboarding instead of the
+        // dead-end auth error. The first-win demo is offered only in the no-prompt
+        // (REPL) path; with a real prompt, that prompt IS the first win.
         if (!apiKey) {
-            throw authMissingKey(config.model.provider, apiKeyEnvVar(config.model.provider));
+            const onboarding = maybeRunOnboarding(config, {
+                ttyInteractive: Boolean(process.stdin.isTTY),
+                offerFirstWin: interactive,
+                cwd: process.cwd(),
+            });
+            if (onboarding === null) {
+                // Not a first run (non-TTY, or onboarded then key removed) → fail loud.
+                throw authMissingKey(config.model.provider, apiKeyEnvVar(config.model.provider));
+            }
+            const result = await onboarding;
+            if (!result.completed) {
+                // Aborted/failed mid-setup — guidance already shown; exit cleanly.
+                logger.print(pc.dim("run `cruxy login` to finish setup."));
+                return;
+            }
+            apiKey = result.apiKey ?? resolveApiKey(config.model.provider);
+            if (!apiKey) {
+                throw authMissingKey(config.model.provider, apiKeyEnvVar(config.model.provider));
+            }
         }
-        const provider = createProvider({
-            provider: config.model.provider,
-            apiKey,
-            model: config.model.model,
-            maxTokens: config.model.maxTokens,
-            temperature: config.model.temperature,
-            gatewayUrl: config.cruxy.gatewayUrl,
-        });
-        const registry = buildDefaultRegistry();
-        const approver = createApprover({
-            mode: config.approval.mode,
-            cwd: process.cwd(),
-            isInteractive: Boolean(process.stdin.isTTY),
-            autoApprove: Boolean(opts.yes || opts.dangerouslyApprove),
-            logger,
-        });
-        const ctx = {
-            cwd: process.cwd(),
-            config,
-            logger,
-            approve: (action) => approver.approve(action),
-        };
-        const projectInstructions = loadProjectInstructions(process.cwd());
-        const git = getGitInfo(process.cwd());
-        const session = new Session({
-            provider,
-            registry,
-            config,
-            ctx,
-            git,
-            projectInstructions,
-        });
+        // Plan mode is opt-in: --plan flag overrides the config default.
+        const planMode = opts.plan ?? config.agent.planMode;
+        const session = buildAgentSession(config, apiKey, process.cwd(), Boolean(process.stdin.isTTY), planMode);
         if (interactive) {
             await runInteractive(session);
             return;
@@ -80,14 +69,3 @@ export function runCommand() {
             `tokens in/out ${result.usage.input_tokens}/${result.usage.output_tokens}`);
     });
 }
-/** Environment variable that holds the API key for a provider. */
-function apiKeyEnvVar(provider) {
-    switch (provider) {
-        case "anthropic":
-            return "ANTHROPIC_API_KEY";
-        case "openai":
-            return "OPENAI_API_KEY";
-        default:
-            return "CRUXY_API_KEY";
-    }
-}