@cruxy/cli 0.22.1 → 0.24.0

package/dist/cli/commands/rollback.js

@@ -1,7 +1,8 @@
+import path from "node:path";
 import { Command } from "commander";
 import { themeForColor } from "../../theme/index.js";
 import { loadConfig } from "../../config/index.js";
-import { CheckpointService } from "../../checkpoint/index.js";
+import { CheckpointService, applySet, buildSetPreview, listSets, setIsNoop, validateSet, } from "../../checkpoint/index.js";
 import { ApprovalService, defaultPromptIO } from "../../approval/index.js";
 import { fuzzyFind, selectList } from "../../components/index.js";
 import { rollbackApprovalRequired, shouldUseColor, } from "../../errors/index.js";
@@ -41,17 +42,88 @@ async function pickCheckpoint(service) {
     return result.kind === "selected" ? result.value : null;
 }
 /**
- * `cruxy rollback [id]` (C.32) — restore the working tree to a checkpoint,
- * undoing everything an agent run changed (creates, edits, deletes) in one
- * operation. Destructive by definition, so it is preview-first and gated
- * through U.3 at the destructive tier, ungrantable; non-TTY is refused with a
- * coded error before anything is computed. Out of scope, stated in the
- * preview: commits, pushes, and PRs made during the run are not undone.
+ * Legacy single-root rollback (C.32): restore one root's checkpoint. Reached for
+ * an explicit `cruxy rollback <id>` (the per-member escape hatch — including when
+ * the primary root was removed mid-session and its set index is gone, ⚖︎#7) and as
+ * the JC-F back-compat fallback for a pre-set-manifest run.
+ */
+async function legacyRollback(root, config, approval, interactive, id, t) {
+    const service = new CheckpointService({ root, config });
+    if (id === undefined) {
+        const picked = await pickCheckpoint(service);
+        if (picked === null) {
+            logger.print(t.muted("rollback cancelled — nothing was changed"));
+            return;
+        }
+        id = picked?.id;
+    }
+    const result = await service.rollback(id, {
+        requestApproval: (action) => approval.requestApproval(action),
+        interactive,
+    });
+    if (result.kind === "noop") {
+        logger.print(t.muted(`working tree already matches checkpoint ${result.checkpoint.id} — nothing to roll back`));
+        return;
+    }
+    if (result.kind === "rejected") {
+        logger.print(t.muted("rollback declined — nothing was changed"));
+        return;
+    }
+    const { recreated, reverted, deleted } = result.applied;
+    logger.print(`${t.success(t.glyph.success)} restored checkpoint ${t.accent(result.checkpoint.id)} — ` +
+        `${reverted} reverted, ${recreated} recreated, ${deleted} deleted`);
+    logger.print(t.muted("note: commits, pushes, and PRs made during the run are not undone"));
+}
+/**
+ * Set-based rollback (C.26): restore every touched root of the latest run as one
+ * gated operation. Validate-ALL members up front (missing/corrupt →
+ * `CHECKPOINT_SET_INCOMPLETE`, nothing applied), one combined per-root preview and
+ * one U.3 approval, then a sequential apply that stops on first failure
+ * (`CHECKPOINT_SET_PARTIAL`, R3). Both coded errors propagate to the boundary.
+ */
+async function setRollback(primaryRoot, config, approval, t) {
+    const sets = await listSets(primaryRoot); // newest first
+    const set = sets[0];
+    // Validate-all BEFORE any apply — a missing/corrupt member throws here.
+    const members = await validateSet(set, config);
+    if (setIsNoop(members)) {
+        logger.print(t.muted(`working tree already matches run ${set.runId} — nothing to roll back`));
+        return;
+    }
+    const decision = await approval.requestApproval({
+        kind: "rollback",
+        preview: buildSetPreview(set, members),
+    });
+    if (!decision.allow) {
+        logger.print(t.muted("rollback declined — nothing was changed"));
+        return;
+    }
+    const applied = await applySet(set, members);
+    const parts = applied.restored.map((name) => {
+        const counts = applied.perRoot[name];
+        return `${name} (${counts.reverted} reverted, ${counts.recreated} recreated, ${counts.deleted} deleted)`;
+    });
+    logger.print(`${t.success(t.glyph.success)} restored run ${t.accent(set.runId)} across ` +
+        `${applied.restored.length} root${applied.restored.length === 1 ? "" : "s"} — ${parts.join("; ")}`);
+    logger.print(t.muted("note: commits, pushes, and PRs made during the run are not undone"));
+}
+/**
+ * `cruxy rollback [id]` (C.32/C.26) — restore the working tree to a run's
+ * checkpoint(s), undoing everything an agent run changed in one operation.
+ * Destructive by definition, so it is preview-first and gated through U.3 at the
+ * destructive tier, ungrantable; non-TTY is refused with a coded error before
+ * anything is computed. Out of scope, stated in the preview: commits, pushes, and
+ * PRs made during the run are not undone.
+ *
+ * Routing:
+ *   • an explicit `<id>` → single-root rollback of that checkpoint (escape hatch);
+ *   • no id, a set manifest exists → set-based rollback of the latest run;
+ *   • no id, no set manifest → JC-F fallback to legacy single-root, logged.
  */
 export function rollbackCommand() {
     return new Command("rollback")
         .description("restore the working tree to a checkpoint, undoing a run's file changes")
-        .argument("[id]", "checkpoint id (defaults to the most recent)")
+        .argument("[id]", "checkpoint id (defaults to the most recent run)")
         .action(async (id) => {
         const interactive = Boolean(process.stdin.isTTY);
         // Refuse before touching anything: rollback is a deliberate, interactive
@@ -60,38 +132,26 @@ export function rollbackCommand() {
             throw rollbackApprovalRequired();
         const t = themeForColor(shouldUseColor(process.stdout));
         const { config } = loadConfig();
-        const root = process.cwd();
-        const service = new CheckpointService({ root, config });
+        const primaryRoot = process.cwd();
         const approval = new ApprovalService({
-            cwd: root,
+            cwd: primaryRoot,
             interactive,
             io: defaultPromptIO(shouldUseColor()),
         });
-        // No id given → pick one interactively (U.7). Enter-once still restores
-        // the newest, exactly as before the picker existed.
-        if (id === undefined) {
-            const picked = await pickCheckpoint(service);
-            if (picked === null) {
-                logger.print(t.muted("rollback cancelled — nothing was changed"));
-                return;
-            }
-            id = picked?.id;
-        }
-        const result = await service.rollback(id, {
-            requestApproval: (action) => approval.requestApproval(action),
-            interactive,
-        });
-        if (result.kind === "noop") {
-            logger.print(t.muted(`working tree already matches checkpoint ${result.checkpoint.id} — nothing to roll back`));
+        // Explicit id → single-root path (the per-member escape hatch; also the
+        // recovery route if the primary root — and its set index — was removed).
+        if (id !== undefined) {
+            await legacyRollback(primaryRoot, config, approval, interactive, id, t);
             return;
         }
-        if (result.kind === "rejected") {
-            logger.print(t.muted("rollback declined — nothing was changed"));
+        // No set manifest → JC-F: fall back to legacy single-root, logged (never
+        // silent). The primary root name matches single-root workspace naming.
+        const sets = await listSets(primaryRoot);
+        if (sets.length === 0) {
+            logger.info(`no set manifest — single-root rollback against ${path.basename(primaryRoot)}`);
+            await legacyRollback(primaryRoot, config, approval, interactive, undefined, t);
             return;
         }
-        const { recreated, reverted, deleted } = result.applied;
-        logger.print(`${t.success(t.glyph.success)} restored checkpoint ${t.accent(result.checkpoint.id)} — ` +
-            `${reverted} reverted, ${recreated} recreated, ${deleted} deleted`);
-        logger.print(t.muted("note: commits, pushes, and PRs made during the run are not undone"));
+        await setRollback(primaryRoot, config, approval, t);
     });
 }

package/dist/cli/commands/run.js

@@ -5,21 +5,36 @@ import { authMissingKey, shouldUseColor, usageError, } from "../../errors/index.
 import { createRenderer } from "../../render/index.js";
 import { themeForColor } from "../../theme/index.js";
 import { summarizeRuns, renderSummary, } from "../../usage/index.js";
-import { CheckpointService } from "../../checkpoint/index.js";
+import { CheckpointGate } from "../../checkpoint/index.js";
 import { SandboxService } from "../../sandbox/index.js";
-import { buildHooksService } from "../../hooks/index.js";
+import { buildHooksService, buildHooksRouter } from "../../hooks/index.js";
 import { runInteractive } from "../repl.js";
 import { buildAgentSession } from "../session-factory.js";
 import { apiKeyEnvVar, maybeRunOnboarding } from "../onboard.js";
 import { resetLspServices } from "../../lsp/index.js";
-import { connectMcpTools, resetMcpServices } from "../../mcp/index.js";
+import { connectMcpTools, deferredSiblingServers, resetMcpServices, } from "../../mcp/index.js";
 import { defaultPromptIO } from "../../approval/index.js";
+import { buildWorkspace, sessionWorkspace, } from "../../workspace/index.js";
+/**
+ * Parse one repeatable `--root` value into a {@link RootSpec} and append it. Form
+ * `name=path` (explicit name) or a bare `path` (basename-named by buildWorkspace).
+ * All existence/dir/overlap/name validation is delegated to buildWorkspace, which
+ * fails loud — this only splits the flag.
+ */
+function collectRoot(value, acc) {
+    const eq = value.indexOf("=");
+    const spec = eq === -1
+        ? { path: value }
+        : { name: value.slice(0, eq), path: value.slice(eq + 1) };
+    return [...acc, spec];
+}
 export function runCommand() {
     return new Command("run")
         .description("run a task once, or start an interactive session")
         .argument("[prompt...]", "the task for cruxy to perform (omit for interactive)")
         .option("--plan", "plan mode: propose a step-by-step plan for approval before executing")
         .option("--sandbox", "run shell + test commands inside an isolated container (fails loud if no runtime)")
+        .option("--root <spec>", "declare a workspace root (repeatable): name=path or path; the first is primary", collectRoot, [])
         .action(async (promptParts, opts) => {
         const prompt = promptParts.join(" ").trim();
         const t = themeForColor(shouldUseColor(process.stdout));
@@ -31,8 +46,40 @@ export function runCommand() {
         }
         const { config, sources } = loadConfig();
         let apiKey = resolveApiKey(config.model.provider);
+        // Declared workspace roots (C.26). This is the ONE place `run` reads the
+        // process working directory — the invocation directory is the base for
+        // resolving `--root` paths and the sole root when none are declared. Every
+        // subsystem below derives its cwd from the WORKSPACE (`primaryRoot`), never
+        // re-reads the invocation directory, so nothing can silently split-brain to
+        // a different dir than the roots the tools see (the guard test pins this).
+        const invocationCwd = process.cwd();
+        // No --root → a trivial single-root workspace (byte-identical to pre-C.26).
+        // --root builds a genuine multi-root Workspace and fails fast HERE — a
+        // missing / non-dir / overlapping root (CRUXY_E_ROOT_OVERLAP) throws before
+        // onboarding or the session starts, never a half-built session.
+        const workspace = opts.root.length
+            ? await buildWorkspace(opts.root, { cwd: invocationCwd })
+            : sessionWorkspace(invocationCwd);
+        const primaryRoot = workspace.primary().absPath;
         logger.info(t.muted(`model:   ${config.model.provider}/${config.model.model}`));
         logger.info(t.muted(`config:  ${sources.project ?? sources.global ?? "defaults"}`));
+        // Multi-root honesty (JC-6/C.26): reads fan every root. With per-root
+        // checkpoints active (C.26 step 3), writes fan every root too — each is
+        // checkpointed and rollback-able. With checkpoints DISABLED, a non-primary
+        // write is still refused (CRUXY_E_MULTIROOT_WRITE_DEFERRED) rather than left
+        // un-restorable. Hooks + MCP still scope to the primary this release. Named
+        // at start, never a silent primary-default.
+        if (workspace.isMultiRoot) {
+            const names = workspace
+                .roots()
+                .map((r) => r.name)
+                .join(", ");
+            const writes = config.checkpoint.enabled
+                ? "writes fan all roots (each checkpointed)"
+                : "writes scope to primary (checkpoints disabled)";
+            logger.info(t.muted(`roots:   ${workspace.roots().length} (${names}); primary ${workspace.primary().name} — ` +
+                `reads fan all roots; ${writes}; hooks fan per trusted root; MCP loads from primary only this release`));
+        }
         // 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.
@@ -40,7 +87,7 @@ export function runCommand() {
             const onboarding = maybeRunOnboarding(config, {
                 ttyInteractive: Boolean(process.stdin.isTTY),
                 offerFirstWin: interactive,
-                cwd: process.cwd(),
+                cwd: primaryRoot,
             });
             if (onboarding === null) {
                 // Not a first run (non-TTY, or onboarded then key removed) → fail loud.
@@ -62,11 +109,13 @@ export function runCommand() {
         // 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.
+        // Checkpoint-before-first-mutation (C.32/C.26): the gate owns one
+        // CheckpointService PER touched root (lazy) plus the run's CheckpointSet,
+        // and fires from the approval seam inside the session — so one instance
+        // covers the one-shot path, every REPL turn, plan-mode execution, and
+        // subagents (they share this gate, so their writes join the run's set).
         const checkpoints = config.checkpoint.enabled
-            ? new CheckpointService({ root: process.cwd(), config })
+            ? new CheckpointGate({ config, primaryRoot })
             : undefined;
         // Sandbox (C.16): opt-in via --sandbox or sandbox.enabled. Resolving the
         // service probes the runtime and THROWS CRUXY_E_SANDBOX_UNAVAILABLE if it
@@ -77,37 +126,71 @@ export function runCommand() {
         const sandbox = sandboxEnabled
             ? await SandboxService.create({
                 config,
-                cwd: process.cwd(),
+                cwd: primaryRoot,
+                // R5 (C.26): the command's root (primary — shell/test attribute to
+                // it this release) mounts read-write; every OTHER declared root
+                // mounts read-only. Cross-root write is only ever granted per-root
+                // via a named escalation, never blanket.
+                siblingRoots: workspace
+                    .roots()
+                    .filter((r) => !r.primary)
+                    .map((r) => r.absPath),
                 reporter: renderer,
             })
             : undefined;
         if (sandbox) {
             logger.info(t.muted(`sandbox: ${sandbox.runtimeName} (network ${config.sandbox.network})`));
         }
-        // Hooks + custom slash commands (C.19). Built once per run: loads the
-        // layered catalog and yields the lifecycle runner (threaded into the
-        // session) + the resolved custom slash commands (given to the REPL).
-        const hooksService = await buildHooksService({
-            cwd: process.cwd(),
-            config,
-            interactive: Boolean(process.stdin.isTTY),
-            logger,
-        });
+        // Hooks + custom slash commands (C.19). Single-root uses the unchanged
+        // service (byte-identical: one runner, lazy trust prompt). Multi-root
+        // (C.26 step 5) builds ONE runner per root behind a HookRouter — tool
+        // events fire the acting root's hooks, lifecycle events fan every trusted
+        // root. Untrusted roots are skipped and NAMED here (never a silent loss).
+        let hooksRunner;
+        let hookCommands;
+        if (workspace.isMultiRoot) {
+            const router = await buildHooksRouter({ workspace, config, logger });
+            hooksRunner = router.runner;
+            hookCommands = router.commands;
+            for (const u of router.untrustedHookRoots) {
+                logger.info(t.muted(`hooks:   root "${u.name}" has ${u.count} untrusted hook${u.count === 1 ? "" : "s"} — ` +
+                    `not firing (run \`cruxy hooks trust ${u.absPath}\`)`));
+            }
+        }
+        else {
+            const hooksService = await buildHooksService({
+                cwd: primaryRoot,
+                config,
+                interactive: Boolean(process.stdin.isTTY),
+                logger,
+            });
+            hooksRunner = hooksService.runner;
+            hookCommands = hooksService.commands;
+        }
         // MCP servers (C.27): connect + trust-gate BEFORE building the session so
         // the tool catalogue is complete when the model first runs. Off by
         // default (no servers connect). A non-interactive run with an untrusted
         // config THROWS CRUXY_E_MCP_UNTRUSTED here — before any server spawns.
         const mcp = await connectMcpTools({
-            cwd: process.cwd(),
+            cwd: primaryRoot,
             config,
             logger,
             interactive: Boolean(process.stdin.isTTY),
             io: defaultPromptIO(shouldUseColor()),
         });
-        const session = buildAgentSession(config, apiKey, process.cwd(), Boolean(process.stdin.isTTY), planMode, renderer, checkpoints, sandbox, hooksService.runner, mcp.tools);
+        // MCP is primary-root only this release (JC-D). Name each sibling-root
+        // server individually — never one generic line, never a silent drop —
+        // so a user who declared `github` in a sibling knows exactly why its
+        // tools aren't present (and that root-qualified names are a follow-up).
+        if (workspace.isMultiRoot) {
+            for (const d of deferredSiblingServers(workspace)) {
+                logger.info(t.muted(`mcp:     server "${d.server}" declared in ${d.root} not loaded (primary-root MCP only this release)`));
+            }
+        }
+        const session = buildAgentSession(config, apiKey, workspace, Boolean(process.stdin.isTTY), planMode, renderer, checkpoints, sandbox, hooksRunner, mcp.tools);
         if (interactive) {
             try {
-                await runInteractive(session, undefined, renderer, checkpoints, hooksService.commands);
+                await runInteractive(session, undefined, renderer, checkpoints, hookCommands);
             }
             finally {
                 // LSP (C.12) + MCP (C.27): gracefully shut down any external server

package/dist/cli/onboard.js

@@ -1,6 +1,7 @@
 import { resolveApiKey } from "../config/index.js";
 import { createDefaultDeps, defaultOnboardingIO, isFirstRun, runOnboarding, } from "../onboarding/index.js";
 import { createRenderer } from "../render/index.js";
+import { sessionWorkspace } from "../workspace/index.js";
 import { buildAgentSession } from "./session-factory.js";
 /**
  * CLI-layer glue between the entry points and the onboarding module (U.6). Keeps
@@ -24,7 +25,9 @@ export async function runFirstWinTask(config, cwd, prompt) {
     if (!apiKey)
         return; // defensive — the key was just persisted
     const renderer = createRenderer();
-    const session = buildAgentSession(config, apiKey, cwd, true, false, renderer);
+    // The onboarding first-win is inherently single-root (it runs before any
+    // `--root` is parsed), so it acts over a trivial workspace on its cwd.
+    const session = buildAgentSession(config, apiKey, sessionWorkspace(cwd), true, false, renderer);
     try {
         await session.send(prompt, renderer);
     }

package/dist/cli/repl.d.ts

@@ -1,6 +1,6 @@
 import type { Readable, Writable } from "node:stream";
 import type { Session } from "../agent/index.js";
-import type { CheckpointService } from "../checkpoint/index.js";
+import type { CheckpointGate } from "../checkpoint/index.js";
 import { type SlashCommandSpec } from "../hooks/index.js";
 import { type StreamRenderer } from "../render/index.js";
 /**
@@ -24,4 +24,4 @@ export interface ReplIO {
  * 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, renderer?: StreamRenderer, checkpoints?: CheckpointService, slashCommands?: readonly SlashCommandSpec[]): Promise<void>;
+export declare function runInteractive(session: Session, io?: ReplIO, renderer?: StreamRenderer, checkpoints?: CheckpointGate, slashCommands?: readonly SlashCommandSpec[]): Promise<void>;

package/dist/cli/repl.js

@@ -2,6 +2,7 @@ import readline from "node:readline";
 import { makeReplCompleter } from "../components/index.js";
 import { resolveSlash } from "../hooks/index.js";
 import { runGatedShell } from "../tools/shell/exec.js";
+import { addRootToWorkspace } from "../workspace/index.js";
 import { themeForColor } from "../theme/index.js";
 import { formatError, fromUnknown, isVerbose, shouldUseColor, } from "../errors/index.js";
 import { createRenderer } from "../render/index.js";
@@ -113,6 +114,40 @@ function printReplError(err) {
         color: shouldUseColor(process.stdout),
     }));
 }
+/**
+ * `/add-root <name> <path>` (C.26 step 5) — an explicit, human-only way to
+ * declare another workspace root. This is a REPL command, NOT a model tool: the
+ * model can only reach the tool registry, and nothing named `add_root` is
+ * registered there, so the allowlist argument is unchanged. It validates the
+ * addition (TTY-only; same existence/name/overlap refusal as `--root`) and, on
+ * success, tells the user to relaunch with `--root` to activate it — a
+ * mid-session hot-swap would leave the checkpoint gate + hook router (both wired
+ * from the session-start workspace) half-attributed, so activation is deferred
+ * to a clean relaunch. A newly declared root always starts untrusted.
+ */
+async function handleAddRoot(input, session) {
+    const parts = input
+        .slice("/add-root".length)
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean);
+    if (parts.length !== 2) {
+        logger.print(theme.muted("usage: /add-root <name> <path>"));
+        return;
+    }
+    const [name, rootPath] = parts;
+    const ctx = session.toolContext;
+    const current = ctx.workspace;
+    try {
+        const next = await addRootToWorkspace(current, { name, path: rootPath }, { cwd: ctx.cwd, tty: Boolean(process.stdin.isTTY) });
+        const abs = next.rootByName(name).absPath;
+        logger.print(theme.muted(`validated root "${name}" (${abs}). relaunch with \`--root ${name}=${rootPath}\` to activate it — ` +
+            `it starts untrusted (its hooks and project memory stay inert until you run \`cruxy hooks/memory trust\`).`));
+    }
+    catch (err) {
+        printReplError(err);
+    }
+}
 /**
  * Drive an interactive multi-turn session: prompt, read a line, dispatch slash
  * commands or run a turn, repeat. Assistant text and tool-call progress stream
@@ -182,6 +217,10 @@ async function replLoop(session, io, renderer, checkpoints, slashCommands = [])
             logger.print(HELP);
             continue;
         }
+        if (trimmed === "/add-root" || trimmed.startsWith("/add-root ")) {
+            await handleAddRoot(trimmed, session);
+            continue;
+        }
         // Custom slash commands (C.19) — consulted AFTER builtins, so a custom
         // command can never shadow /help, /exit, etc. A `prompt` command expands to
         // text fed to the agent (safe); a `shell` command runs through the SAME

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

@@ -1,10 +1,11 @@
 import type { CruxyConfig } from "../config/index.js";
 import type { ApprovalDecision } from "../approval/index.js";
-import type { CheckpointService } from "../checkpoint/index.js";
+import type { CheckpointGate } from "../checkpoint/index.js";
 import type { SandboxService } from "../sandbox/index.js";
 import type { StreamRenderer } from "../render/index.js";
-import { type ApproveAction, type Tool } from "../tools/index.js";
+import { ToolRegistry, type ApproveAction, type Tool } from "../tools/index.js";
 import { Session, type LifecycleHookRunner } from "../agent/index.js";
+import type { Workspace } from "../workspace/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
@@ -14,7 +15,29 @@ import { Session, type LifecycleHookRunner } from "../agent/index.js";
  * (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>;
+export declare function withCheckpointGate(requestApproval: (action: ApproveAction) => Promise<ApprovalDecision>, gate: CheckpointGate | undefined, ws: Workspace): (action: ApproveAction) => Promise<ApprovalDecision>;
+/**
+ * Register every CONDITIONALLY-enabled runtime tool onto `registry`, in the fixed
+ * order the model sees them: `remember` (memory), the four LSP tools, the two web
+ * tools, the trusted MCP tools, then `spawn_subagent`. Factored out of
+ * {@link buildAgentSession} for ONE reason beyond tidiness: it makes the *complete
+ * runtime* tool set enumerable by a test (JC-B). The default registry only covers
+ * the 14 always-on tools; the allowlist test that pins "no tool can add a workspace
+ * root" is only sound if it runs against the SAME set the session ships — so the
+ * session factory and that test both build the surface through this one seam. A new
+ * conditionally-registered tool added here fails the allowlist test until it is
+ * consciously listed and audited.
+ *
+ * Each family is opt-in and inert when its feature flag is off, exactly as before —
+ * this function is a pure move of the inline registration, same guards, same order.
+ * `spawnTool` is passed in (already depth-bound) because it needs the orchestrator;
+ * it registers only when nesting is allowed (`subagent.maxDepth > 0`).
+ */
+export declare function registerRuntimeTools(registry: ToolRegistry, config: CruxyConfig, opts?: {
+    mcpTools?: Tool[];
+    spawnTool?: Tool;
+    spawnManyTool?: Tool;
+}): void;
 /**
  * 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).
@@ -24,4 +47,4 @@ export declare function withCheckpointGate(requestApproval: (action: ApproveActi
  * 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, renderer?: StreamRenderer, checkpoints?: CheckpointService, sandbox?: SandboxService, hooks?: LifecycleHookRunner, mcpTools?: Tool[]): Session;
+export declare function buildAgentSession(config: CruxyConfig, apiKey: string, workspace: Workspace, ttyInteractive: boolean, planMode?: boolean, renderer?: StreamRenderer, checkpoints?: CheckpointGate, sandbox?: SandboxService, hooks?: LifecycleHookRunner, mcpTools?: Tool[]): Session;