@cruxy/cli 0.7.0 → 0.9.0

package/dist/cli/commands/run.js

@@ -3,8 +3,9 @@ import pc from "picocolors";
 import { logger } from "../../utils/logger.js";
 import { loadConfig, resolveApiKey } from "../../config/index.js";
 import { authMissingKey, usageError } from "../../errors/index.js";
+import { createRenderer } from "../../render/index.js";
+import { CheckpointService } from "../../checkpoint/index.js";
 import { runInteractive } from "../repl.js";
-import { createStreamPrinter } from "../stream-print.js";
 import { buildAgentSession } from "../session-factory.js";
 import { apiKeyEnvVar, maybeRunOnboarding } from "../onboard.js";
 export function runCommand() {
@@ -50,22 +51,35 @@ export function runCommand() {
         }
         // 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);
+        // One renderer for the whole run (U.2): the streaming path and the
+        // approval prompt's status-suspend hook must share the same live region.
+        const renderer = createRenderer();
+        // Checkpoint-before-first-mutation (C.32): the service is latched per run
+        // and fires from the approval seam inside the session, so one instance
+        // covers the one-shot path, every REPL turn, and plan-mode execution.
+        const checkpoints = config.checkpoint.enabled
+            ? new CheckpointService({ root: process.cwd(), config })
+            : undefined;
+        const session = buildAgentSession(config, apiKey, process.cwd(), Boolean(process.stdin.isTTY), planMode, renderer, checkpoints);
         if (interactive) {
-            await runInteractive(session);
+            await runInteractive(session, undefined, renderer, checkpoints);
             return;
         }
+        checkpoints?.beginRun(prompt);
         // One-shot: a single turn, then exit. Preserves scripting/pipe use.
-        // Assistant text streams to stdout delta by delta (same as the REPL),
-        // through a printer that trims the model's leading blank lines; the agent
-        // loop terminates the line.
+        // Assistant text streams to stdout delta by delta (same as the REPL);
+        // piped output degrades to the plain renderer (no ANSI, chrome on stderr).
         logger.print(`${pc.cyan("cruxy")} ${pc.dim("›")} ${prompt}\n`);
         // Provider/network/auth failures propagate to the top-level boundary,
         // which classifies them (e.g. CRUXY_E_GATEWAY_UNREACHABLE) and exits with
         // the matching code — a one-shot run must fail non-zero on error.
-        const print = createStreamPrinter((text) => process.stdout.write(text));
-        const result = await session.send(prompt, print);
-        logger.debug(`agent finished: ${result.stop} after ${result.iterations} turn(s); ` +
-            `tokens in/out ${result.usage.input_tokens}/${result.usage.output_tokens}`);
+        try {
+            const result = await session.send(prompt, renderer);
+            logger.debug(`agent finished: ${result.stop} after ${result.iterations} turn(s); ` +
+                `tokens in/out ${result.usage.input_tokens}/${result.usage.output_tokens}`);
+        }
+        finally {
+            renderer.close();
+        }
     });
 }

package/dist/cli/onboard.js

@@ -1,6 +1,6 @@
 import { resolveApiKey } from "../config/index.js";
 import { createDefaultDeps, defaultOnboardingIO, isFirstRun, runOnboarding, } from "../onboarding/index.js";
-import { createStreamPrinter } from "./stream-print.js";
+import { createRenderer } from "../render/index.js";
 import { buildAgentSession } from "./session-factory.js";
 /**
  * CLI-layer glue between the entry points and the onboarding module (U.6). Keeps
@@ -23,9 +23,14 @@ export async function runFirstWinTask(config, cwd, prompt) {
     const apiKey = resolveApiKey(config.model.provider);
     if (!apiKey)
         return; // defensive — the key was just persisted
-    const session = buildAgentSession(config, apiKey, cwd, true);
-    const print = createStreamPrinter((text) => process.stdout.write(text));
-    await session.send(prompt, print);
+    const renderer = createRenderer();
+    const session = buildAgentSession(config, apiKey, cwd, true, false, renderer);
+    try {
+        await session.send(prompt, renderer);
+    }
+    finally {
+        renderer.close();
+    }
 }
 /**
  * Run the guided first-run flow **iff** this is a first run; otherwise return

package/dist/cli/program.js

@@ -10,6 +10,8 @@ import { skillsCommand } from "./commands/skills.js";
 import { prCommand } from "./commands/pr.js";
 import { loginCommand } from "./commands/login.js";
 import { initCommand } from "./commands/init.js";
+import { checkpointCommand } from "./commands/checkpoint.js";
+import { rollbackCommand } from "./commands/rollback.js";
 import { loadConfig } from "../config/index.js";
 import { maybeRunOnboarding } from "./onboard.js";
 export function buildProgram() {
@@ -36,6 +38,8 @@ export function buildProgram() {
     program.addCommand(prCommand());
     program.addCommand(loginCommand());
     program.addCommand(initCommand());
+    program.addCommand(checkpointCommand());
+    program.addCommand(rollbackCommand());
     // Default action: bare `cruxy` -> entrypoint. An unrecognized first operand
     // means an unknown command (Commander runs the default action with it as an
     // operand rather than erroring), so reject it as a usage error.

package/dist/cli/repl.d.ts

@@ -1,5 +1,7 @@
 import type { Readable, Writable } from "node:stream";
 import type { Session } from "../agent/index.js";
+import type { CheckpointService } from "../checkpoint/index.js";
+import { type StreamRenderer } from "../render/index.js";
 /** The stdin/stdout pair the REPL reads from and prompts on. Injectable for tests. */
 export interface ReplIO {
     input: Readable;
@@ -7,9 +9,13 @@ export interface ReplIO {
 }
 /**
  * Drive an interactive multi-turn session: prompt, read a line, dispatch slash
- * commands or run a turn, repeat. Assistant text streams to stdout from within
- * `session.send` (via the logger); this loop only owns input and control.
+ * commands or run a turn, repeat. Assistant text and tool-call progress stream
+ * through the `renderer` from within `session.send`; this loop only owns input
+ * and control.
  *
- * `io` defaults to real stdin/stdout; tests inject a scripted stream pair.
+ * `io` defaults to real stdin/stdout; tests inject a scripted stream pair. The
+ * renderer defaults to whatever `io.output` supports (a TTY gets the managed
+ * live region, anything else the plain append-only renderer); `cruxy run`
+ * passes its own so the approval prompt's status-suspend hook shares it.
  */
-export declare function runInteractive(session: Session, io?: ReplIO): Promise<void>;
+export declare function runInteractive(session: Session, io?: ReplIO, renderer?: StreamRenderer, checkpoints?: CheckpointService): Promise<void>;

package/dist/cli/repl.js

@@ -1,8 +1,8 @@
 import readline from "node:readline";
 import pc from "picocolors";
 import { formatError, fromUnknown, isVerbose, shouldUseColor, } from "../errors/index.js";
+import { createRenderer } from "../render/index.js";
 import { logger } from "../utils/logger.js";
-import { createStreamPrinter } from "./stream-print.js";
 const PROMPT = `${pc.cyan("cruxy")} ${pc.dim("›")} `;
 const HELP = `Commands:
   /help          show this help
@@ -65,13 +65,25 @@ function printReplError(err) {
 }
 /**
  * Drive an interactive multi-turn session: prompt, read a line, dispatch slash
- * commands or run a turn, repeat. Assistant text streams to stdout from within
- * `session.send` (via the logger); this loop only owns input and control.
+ * commands or run a turn, repeat. Assistant text and tool-call progress stream
+ * through the `renderer` from within `session.send`; this loop only owns input
+ * and control.
  *
- * `io` defaults to real stdin/stdout; tests inject a scripted stream pair.
+ * `io` defaults to real stdin/stdout; tests inject a scripted stream pair. The
+ * renderer defaults to whatever `io.output` supports (a TTY gets the managed
+ * live region, anything else the plain append-only renderer); `cruxy run`
+ * passes its own so the approval prompt's status-suspend hook shares it.
  */
-export async function runInteractive(session, io = defaultIO()) {
+export async function runInteractive(session, io = defaultIO(), renderer = createRenderer(io.output, process.stderr), checkpoints) {
     logger.print(pc.dim("interactive session — /help for commands, /exit or Ctrl+D to quit"));
+    try {
+        await replLoop(session, io, renderer, checkpoints);
+    }
+    finally {
+        renderer.close();
+    }
+}
+async function replLoop(session, io, renderer, checkpoints) {
     for (;;) {
         const line = await readLine(io, PROMPT);
         // EOF / Ctrl+D.
@@ -120,14 +132,16 @@ export async function runInteractive(session, io = defaultIO()) {
             logger.print(HELP);
             continue;
         }
-        // A real turn. Assistant text streams to the output delta by delta through a
-        // single printer (which trims the model's leading blank lines); the agent
-        // loop closes the segment with one newline, so the next prompt lands on its
-        // own line. Errors (provider/API failures) log and return to the prompt
-        // rather than killing the REPL.
+        // A real turn. Assistant text streams through the renderer delta by delta
+        // (leading blank lines trimmed, code fences highlighted); the agent loop
+        // closes each segment with one newline, so the next prompt lands on its own
+        // line. Errors (provider/API failures) log and return to the prompt rather
+        // than killing the REPL.
         try {
-            const print = createStreamPrinter((text) => io.output.write(text));
-            await session.send(line, print);
+            // Each REPL turn is its own undo unit (C.32): a fresh checkpoint latch,
+            // so `cruxy rollback` reverts exactly one turn's mutations.
+            checkpoints?.beginRun(trimmed);
+            await session.send(line, renderer);
         }
         catch (err) {
             logger.error(err.message);

package/dist/cli/session-factory.d.ts

@@ -1,5 +1,19 @@
 import type { CruxyConfig } from "../config/index.js";
+import type { ApprovalDecision } from "../approval/index.js";
+import type { CheckpointService } from "../checkpoint/index.js";
+import type { StreamRenderer } from "../render/index.js";
+import { type ApproveAction } from "../tools/index.js";
 import { Session } from "../agent/index.js";
+/**
+ * Wrap the approval gate with the C.32 auto-checkpoint hook. Ordering is the
+ * whole point: a tool mutates only *after* `requestApproval` resolves, so
+ * snapshotting after an `allow` decision but before returning it means the
+ * checkpoint always lands before the run's first mutation — and a denied
+ * action never creates one. The same seam records which paths the run touched
+ * (file actions) or that attribution is lost (shell), for rollback's
+ * external-change detection.
+ */
+export declare function withCheckpointGate(requestApproval: (action: ApproveAction) => Promise<ApprovalDecision>, checkpoints: CheckpointService | undefined, cwd: string): (action: ApproveAction) => Promise<ApprovalDecision>;
 /**
  * Build a ready-to-run agent {@link Session} from a resolved key — the wiring
  * shared by `cruxy run` and the onboarding first-win task (so they can't drift).
@@ -9,4 +23,4 @@ import { Session } from "../agent/index.js";
  * over the shared U.3 allowlist and a `planRunner` so `session.send` proposes →
  * approves → executes. Plan mode is fully opt-in; the default path is unchanged.
  */
-export declare function buildAgentSession(config: CruxyConfig, apiKey: string, cwd: string, ttyInteractive: boolean, planMode?: boolean): Session;
+export declare function buildAgentSession(config: CruxyConfig, apiKey: string, cwd: string, ttyInteractive: boolean, planMode?: boolean, renderer?: StreamRenderer, checkpoints?: CheckpointService): Session;

package/dist/cli/session-factory.js

@@ -2,11 +2,78 @@ import { createProvider } from "@cruxy/sdk";
 import { loadProjectInstructions } from "../config/index.js";
 import { logger } from "../utils/logger.js";
 import { getGitInfo } from "../utils/git.js";
-import { ApprovalService, InteractivePolicy, SessionAllowlist, defaultPromptIO, } from "../approval/index.js";
+import { ApprovalService, InteractivePolicy, SessionAllowlist, classify, defaultPromptIO, } from "../approval/index.js";
 import { shouldUseColor } from "../errors/index.js";
 import { buildDefaultRegistry } from "../tools/index.js";
 import { Session } from "../agent/index.js";
 import { PlanExecutionPolicy, runPlanSession } from "../plan/index.js";
+import { SubagentOrchestrator, makeSpawnSubagentTool, } from "../subagent/index.js";
+/**
+ * Wrap a PromptIO so the live region yields before any prompt text lands
+ * (U.2/U.4): the prompt writes to stderr while the status line owns the last
+ * stdout row of the same terminal. Entering the `awaiting-approval` phase
+ * hides the live line (the prompt IS the visible state) while keeping the
+ * step-progress register intact, so the line comes back with full context on
+ * the next transition after the user decides.
+ */
+function suspendStatusOnPrompt(io, renderer) {
+    if (!renderer)
+        return io;
+    return {
+        ...io,
+        write: (text) => {
+            renderer.setPhase({ kind: "awaiting-approval" });
+            io.write(text);
+        },
+    };
+}
+/**
+ * Restore the live line once an approval request fully settles (U.4). The
+ * settle point must be the service call, not the prompt's key read: the
+ * prompt writes a trailing newline AFTER the read, which re-enters
+ * `awaiting-approval` — resolving here is the first moment no more prompt
+ * bytes can follow. Fires on every decision (prompted or not); the renderer
+ * treats it as a no-op unless a prompt actually displaced the line.
+ */
+function resumeLineAfterApproval(requestApproval, renderer) {
+    if (!renderer)
+        return requestApproval;
+    return async (action) => {
+        try {
+            return await requestApproval(action);
+        }
+        finally {
+            renderer.promptResolved();
+        }
+    };
+}
+/**
+ * Wrap the approval gate with the C.32 auto-checkpoint hook. Ordering is the
+ * whole point: a tool mutates only *after* `requestApproval` resolves, so
+ * snapshotting after an `allow` decision but before returning it means the
+ * checkpoint always lands before the run's first mutation — and a denied
+ * action never creates one. The same seam records which paths the run touched
+ * (file actions) or that attribution is lost (shell), for rollback's
+ * external-change detection.
+ */
+export function withCheckpointGate(requestApproval, checkpoints, cwd) {
+    if (!checkpoints)
+        return requestApproval;
+    return async (action) => {
+        const decision = await requestApproval(action);
+        if (!decision.allow)
+            return decision;
+        const request = classify(action, cwd);
+        if (request.tier === "read")
+            return decision;
+        await checkpoints.ensureCheckpoint();
+        if (action.kind === "shell")
+            await checkpoints.recordShellMutation();
+        else
+            await checkpoints.recordTouched([...request.targets]);
+        return decision;
+    };
+}
 /**
  * Build a ready-to-run agent {@link Session} from a resolved key — the wiring
  * shared by `cruxy run` and the onboarding first-win task (so they can't drift).
@@ -16,7 +83,7 @@ import { PlanExecutionPolicy, runPlanSession } from "../plan/index.js";
  * over the shared U.3 allowlist and a `planRunner` so `session.send` proposes →
  * approves → executes. Plan mode is fully opt-in; the default path is unchanged.
  */
-export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode = false) {
+export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode = false, renderer, checkpoints) {
     const provider = createProvider({
         provider: config.model.provider,
         apiKey,
@@ -28,10 +95,35 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
     const execRegistry = buildDefaultRegistry();
     const git = getGitInfo(cwd);
     const projectInstructions = loadProjectInstructions(cwd);
+    // One io shared by every prompt in the session (plan approval, the U.3 gate,
+    // and any gate inside a subagent), so they all coordinate with the same live
+    // region. The full wrapper stack around an ApprovalService is factored here
+    // because subagents must get the *identical* stack over a FRESH service: same
+    // prompt + same checkpoint hook, but a new (empty) session allowlist — a
+    // grant in the parent never silently widens a child's authority.
+    const io = suspendStatusOnPrompt(defaultPromptIO(shouldUseColor()), renderer);
+    const gate = (approval) => withCheckpointGate(resumeLineAfterApproval((action) => approval.requestApproval(action), renderer), checkpoints, cwd);
+    // Subagent orchestration (C.14): spawn_subagent goes on the main registry
+    // only when depth allows (maxDepth 0 disables the feature structurally).
+    // Registered before the plan wiring so plan-mode execution steps can
+    // dispatch subagents too; the propose phase filters it out (read-only).
+    const orchestrator = new SubagentOrchestrator({
+        provider,
+        config,
+        parentRegistry: execRegistry,
+        cwd,
+        logger,
+        git,
+        projectInstructions,
+        renderer,
+        makeChildApproval: () => gate(new ApprovalService({ cwd, interactive: ttyInteractive, io })),
+    });
+    if (config.subagent.maxDepth > 0) {
+        execRegistry.register(makeSpawnSubagentTool(orchestrator, 0));
+    }
     if (planMode) {
-        // One io + allowlist shared by the plan-approval prompt and the per-action
+        // One allowlist shared by the plan-approval prompt and the per-action
         // gate, so a grant recorded during execution is honored by U.3's own check.
-        const io = defaultPromptIO(shouldUseColor());
         const allowlist = new SessionAllowlist();
         const planPolicy = new PlanExecutionPolicy(allowlist, new InteractivePolicy(allowlist, io));
         const approval = new ApprovalService({
@@ -40,13 +132,8 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
             policy: planPolicy,
             io,
         });
-        const ctx = {
-            cwd,
-            config,
-            logger,
-            requestApproval: (action) => approval.requestApproval(action),
-        };
-        const planRunner = ({ messages, projectInstructions, onText, }) => runPlanSession({
+        const ctx = { cwd, config, logger, requestApproval: gate(approval) };
+        const planRunner = ({ messages, projectInstructions, renderer: turnRenderer, }) => runPlanSession({
             provider,
             config,
             ctx,
@@ -57,7 +144,7 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
             messages,
             git,
             projectInstructions,
-            onText,
+            renderer: turnRenderer,
         });
         return new Session({
             provider,
@@ -70,13 +157,12 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
             planRunner,
         });
     }
-    const approval = new ApprovalService({ cwd, interactive: ttyInteractive });
-    const ctx = {
+    const approval = new ApprovalService({
         cwd,
-        config,
-        logger,
-        requestApproval: (action) => approval.requestApproval(action),
-    };
+        interactive: ttyInteractive,
+        io,
+    });
+    const ctx = { cwd, config, logger, requestApproval: gate(approval) };
     return new Session({
         provider,
         registry: execRegistry,

package/dist/config/schema.d.ts

@@ -203,6 +203,65 @@ export declare const IndexConfigSchema: z.ZodObject<{
         overlapLines?: number | undefined;
     } | undefined;
 }>;
+/**
+ * Working-tree checkpoints (C.32): a snapshot taken before an agent run's first
+ * file mutation, so `cruxy rollback` can undo the whole run atomically.
+ */
+export declare const CheckpointConfigSchema: z.ZodObject<{
+    /** Auto-checkpoint before a run's first mutation (and enable `cruxy rollback`). */
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    /** How many checkpoints to keep; older ones are pruned oldest-first. */
+    retention: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    enabled: boolean;
+    retention: number;
+}, {
+    enabled?: boolean | undefined;
+    retention?: number | undefined;
+}>;
+/**
+ * Subagent orchestration (C.14): scoped child agents the main agent can spawn
+ * for bounded subtasks. Every cap here is a hard bound — a subagent can narrow
+ * its budget at spawn time but never exceed these ceilings.
+ */
+export declare const SubagentConfigSchema: z.ZodObject<{
+    /**
+     * Maximum subagent nesting depth. The main agent is depth 0; the default of
+     * 1 lets it spawn subagents that cannot themselves spawn (no fork bombs).
+     */
+    maxDepth: z.ZodDefault<z.ZodNumber>;
+    /** Per-subagent budget ceilings; spawn-time overrides are clamped to these. */
+    defaultBudget: z.ZodDefault<z.ZodObject<{
+        /** Hard cap on the subagent's model turns. */
+        maxIterations: z.ZodDefault<z.ZodNumber>;
+        /** Hard cap on the subagent's combined input+output tokens. */
+        maxTokens: z.ZodDefault<z.ZodNumber>;
+        /** Optional wall-clock cap; unset means no time limit. */
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        maxTokens: number;
+        maxIterations: number;
+        timeoutMs?: number | undefined;
+    }, {
+        maxTokens?: number | undefined;
+        maxIterations?: number | undefined;
+        timeoutMs?: number | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    maxDepth: number;
+    defaultBudget: {
+        maxTokens: number;
+        maxIterations: number;
+        timeoutMs?: number | undefined;
+    };
+}, {
+    maxDepth?: number | undefined;
+    defaultBudget?: {
+        maxTokens?: number | undefined;
+        maxIterations?: number | undefined;
+        timeoutMs?: number | undefined;
+    } | undefined;
+}>;
 /** MCP server entry — stdio or URL transport (wired up in a later phase). */
 export declare const McpServerSchema: z.ZodObject<{
     command: z.ZodOptional<z.ZodString>;
@@ -405,6 +464,56 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             overlapLines?: number | undefined;
         } | undefined;
     }>>;
+    checkpoint: z.ZodDefault<z.ZodObject<{
+        /** Auto-checkpoint before a run's first mutation (and enable `cruxy rollback`). */
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        /** How many checkpoints to keep; older ones are pruned oldest-first. */
+        retention: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        enabled: boolean;
+        retention: number;
+    }, {
+        enabled?: boolean | undefined;
+        retention?: number | undefined;
+    }>>;
+    subagent: z.ZodDefault<z.ZodObject<{
+        /**
+         * Maximum subagent nesting depth. The main agent is depth 0; the default of
+         * 1 lets it spawn subagents that cannot themselves spawn (no fork bombs).
+         */
+        maxDepth: z.ZodDefault<z.ZodNumber>;
+        /** Per-subagent budget ceilings; spawn-time overrides are clamped to these. */
+        defaultBudget: z.ZodDefault<z.ZodObject<{
+            /** Hard cap on the subagent's model turns. */
+            maxIterations: z.ZodDefault<z.ZodNumber>;
+            /** Hard cap on the subagent's combined input+output tokens. */
+            maxTokens: z.ZodDefault<z.ZodNumber>;
+            /** Optional wall-clock cap; unset means no time limit. */
+            timeoutMs: z.ZodOptional<z.ZodNumber>;
+        }, "strict", z.ZodTypeAny, {
+            maxTokens: number;
+            maxIterations: number;
+            timeoutMs?: number | undefined;
+        }, {
+            maxTokens?: number | undefined;
+            maxIterations?: number | undefined;
+            timeoutMs?: number | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        maxDepth: number;
+        defaultBudget: {
+            maxTokens: number;
+            maxIterations: number;
+            timeoutMs?: number | undefined;
+        };
+    }, {
+        maxDepth?: number | undefined;
+        defaultBudget?: {
+            maxTokens?: number | undefined;
+            maxIterations?: number | undefined;
+            timeoutMs?: number | undefined;
+        } | undefined;
+    }>>;
     mcpServers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         command: z.ZodOptional<z.ZodString>;
         args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -471,6 +580,18 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             overlapLines: number;
         };
     };
+    checkpoint: {
+        enabled: boolean;
+        retention: number;
+    };
+    subagent: {
+        maxDepth: number;
+        defaultBudget: {
+            maxTokens: number;
+            maxIterations: number;
+            timeoutMs?: number | undefined;
+        };
+    };
     mcpServers: Record<string, {
         command?: string | undefined;
         args?: string[] | undefined;
@@ -529,6 +650,18 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             overlapLines?: number | undefined;
         } | undefined;
     } | undefined;
+    checkpoint?: {
+        enabled?: boolean | undefined;
+        retention?: number | undefined;
+    } | undefined;
+    subagent?: {
+        maxDepth?: number | undefined;
+        defaultBudget?: {
+            maxTokens?: number | undefined;
+            maxIterations?: number | undefined;
+            timeoutMs?: number | undefined;
+        } | undefined;
+    } | undefined;
     mcpServers?: Record<string, {
         command?: string | undefined;
         args?: string[] | undefined;

package/dist/config/schema.js

@@ -137,6 +137,44 @@ export const IndexConfigSchema = z
         .default({}),
 })
     .strict();
+/**
+ * Working-tree checkpoints (C.32): a snapshot taken before an agent run's first
+ * file mutation, so `cruxy rollback` can undo the whole run atomically.
+ */
+export const CheckpointConfigSchema = z
+    .object({
+    /** Auto-checkpoint before a run's first mutation (and enable `cruxy rollback`). */
+    enabled: z.boolean().default(true),
+    /** How many checkpoints to keep; older ones are pruned oldest-first. */
+    retention: z.number().int().positive().default(10),
+})
+    .strict();
+/**
+ * Subagent orchestration (C.14): scoped child agents the main agent can spawn
+ * for bounded subtasks. Every cap here is a hard bound — a subagent can narrow
+ * its budget at spawn time but never exceed these ceilings.
+ */
+export const SubagentConfigSchema = z
+    .object({
+    /**
+     * Maximum subagent nesting depth. The main agent is depth 0; the default of
+     * 1 lets it spawn subagents that cannot themselves spawn (no fork bombs).
+     */
+    maxDepth: z.number().int().nonnegative().default(1),
+    /** Per-subagent budget ceilings; spawn-time overrides are clamped to these. */
+    defaultBudget: z
+        .object({
+        /** Hard cap on the subagent's model turns. */
+        maxIterations: z.number().int().positive().default(10),
+        /** Hard cap on the subagent's combined input+output tokens. */
+        maxTokens: z.number().int().positive().default(32000),
+        /** Optional wall-clock cap; unset means no time limit. */
+        timeoutMs: z.number().int().positive().optional(),
+    })
+        .strict()
+        .default({}),
+})
+    .strict();
 /** MCP server entry — stdio or URL transport (wired up in a later phase). */
 export const McpServerSchema = z
     .object({
@@ -156,6 +194,8 @@ export const CruxyConfigSchema = z
     context: ContextConfigSchema.default({}),
     approval: ApprovalConfigSchema.default({}),
     index: IndexConfigSchema.default({}),
+    checkpoint: CheckpointConfigSchema.default({}),
+    subagent: SubagentConfigSchema.default({}),
     mcpServers: z.record(z.string(), McpServerSchema).default({}),
     logLevel: z.enum(LOG_LEVELS).default("info"),
 })

package/dist/errors/constructors.d.ts

@@ -53,6 +53,31 @@ export declare function planRevisionLimit(limit: number): CruxyError;
  * tell it apart from a per-action approval requirement.
  */
 export declare function planApprovalRequired(): CruxyError;
+/**
+ * Creating, reading, or restoring a working-tree checkpoint failed (C.32).
+ * Fail-loud by design: an agent run never mutates files without its undo
+ * protection unless the user explicitly disables it.
+ */
+export declare function checkpointFailed(reason: string, underlying?: unknown): CruxyError;
+/** The requested checkpoint id doesn't exist (or no checkpoints exist at all). */
+export declare function checkpointNotFound(id?: string): CruxyError;
+/**
+ * Rollback needs interactive approval but cruxy is running non-interactively.
+ * Restoring is destructive and deliberate — there is no auto-rollback path, ever.
+ */
+export declare function rollbackApprovalRequired(): CruxyError;
+/**
+ * A subagent spawn was attempted past the configured nesting cap (C.14). The
+ * spawn tool is structurally withheld at the cap, so reaching this means the
+ * orchestrator seam was driven directly — fail loud, never spawn.
+ */
+export declare function subagentDepthExceeded(depth: number, maxDepth: number): CruxyError;
+/**
+ * A subagent run failed outright (provider error, tool crash) before producing
+ * a result. Normally folded into the structured `SubagentResult` the parent
+ * reasons over; thrown only when the orchestrator itself cannot proceed.
+ */
+export declare function subagentFailed(underlying?: unknown): CruxyError;
 export declare function internal(underlying?: unknown): CruxyError;
 /**
  * Map a known provider/transport error (from `@cruxy/sdk`) to a typed