@cruxy/cli 0.23.0 → 0.24.0

package/dist/agent/loop.d.ts

@@ -5,11 +5,19 @@ import type { StreamRenderer } from "../render/index.js";
 import { type Router, type TaskClass } from "../routing/index.js";
 import type { ToolContext } from "../tools/index.js";
 import { ToolRegistry } from "../tools/index.js";
+/** Optional per-fire context (C.26 step 5). For tool-scoped events the loop
+ * passes the raw tool-call `input` so a multi-root {@link HookRouter} can resolve
+ * the ONE acting root and fire only that root's hooks. Session lifecycle events
+ * (`before-run`/`after-run`) carry no hint — they have no acting root and fan
+ * every trusted root. Ignored by the single-root runner. */
+export interface HookFireHint {
+    input?: unknown;
+}
 /** The lifecycle-hook firing seam (C.19). Structural so the loop stays
  * decoupled from the concrete `HookRunner`. `fire` resolves when hooks pass (or
  * advisory ones fail) and throws `CRUXY_E_HOOK_FAILED` on a blocking failure. */
 export interface LifecycleHookRunner {
-    fire(event: HookEvent, ctx: ToolContext): Promise<void>;
+    fire(event: HookEvent, ctx: ToolContext, hint?: HookFireHint): Promise<void>;
 }
 export interface RunAgentArgs {
     /**
@@ -84,6 +92,17 @@ export interface RunAgentArgs {
         tier?: string;
         usage?: Usage;
     }) => void;
+    /**
+     * Cooperative cancellation (C.33). When the signal aborts, the loop stops at
+     * the NEXT turn boundary and returns `stop: "aborted"` with the coherent
+     * partial history — the in-flight turn (model call + its tool executions)
+     * always completes first, exactly like a tripped {@link budget}, so overshoot
+     * is bounded by one turn. Used by the parallel orchestrator to cancel sibling
+     * subagents on a fatal failure or Ctrl-C; omitted → no cancellation (unchanged).
+     * The same signal reaches tools via `ctx.signal`, so an in-flight shell child
+     * is kill-tree'd rather than orphaned.
+     */
+    signal?: AbortSignal;
 }
 /**
  * The budget seam for {@link runAgent}: implementations track their own caps
@@ -107,7 +126,7 @@ export interface AgentResult {
     /** Number of model turns consumed. */
     iterations: number;
     /** Why the loop ended. */
-    stop: "completed" | "max_iterations" | "budget";
+    stop: "completed" | "max_iterations" | "budget" | "aborted";
     /** Which cap tripped, when `stop === "budget"` (from {@link LoopBudget}). */
     stopReason?: string;
     /** Accumulated token usage (stashed for cost tracking in C.22). */

package/dist/agent/loop.js

@@ -62,6 +62,19 @@ async function driveLoop(args, renderer, routed) {
     });
     let iterations = 0;
     for (let i = 0; i < maxIterations; i++) {
+        // Cancellation check (C.33), before committing to another model turn: a
+        // signalled abort returns the history as it stands, at a clean turn boundary
+        // (the prior iteration fully resolved its tool calls). Checked ahead of the
+        // budget so a cancelled fan-out never spends one more turn's tokens.
+        if (args.signal?.aborted) {
+            return {
+                messages,
+                iterations,
+                stop: "aborted",
+                stopReason: "cancelled",
+                usage,
+            };
+        }
         // Budget check before committing to another model turn (C.14): a tripped
         // cap returns the history as it stands — always at a clean turn boundary,
         // because the previous iteration fully resolved its tool calls.
@@ -184,7 +197,10 @@ async function driveLoop(args, renderer, routed) {
             // fail-closed — the tool never runs; the model is told via an error
             // result. The hook command itself went through the U.3 gate + C.16 sandbox
             // (same path as run_command), so a hook is never an approval bypass.
-            const blocked = await fireBeforeTool(args.hooks, ctx, call.id);
+            // The raw input lets a multi-root HookRouter resolve the ONE acting root
+            // (same precedence the tool uses) and fire only that root's hooks.
+            const hint = { input: call.input };
+            const blocked = await fireBeforeTool(args.hooks, ctx, call.id, hint);
             if (blocked) {
                 renderer?.toolLifecycle({ event: "end", label, ok: false });
                 toolResults.push(blocked);
@@ -196,9 +212,9 @@ async function driveLoop(args, renderer, routed) {
             // after-tool + on-file-change (C.19): fire once the action is done.
             // Advisory by default (report, don't rewrite history); a hook explicitly
             // marked blocking here throws and aborts the run.
-            await args.hooks?.fire("after-tool", ctx);
+            await args.hooks?.fire("after-tool", ctx, hint);
             if (!result.is_error && FILE_MUTATING_TOOLS.has(call.name)) {
-                await args.hooks?.fire("on-file-change", ctx);
+                await args.hooks?.fire("on-file-change", ctx, hint);
             }
         }
         messages.push({ role: "user", content: toolResults });
@@ -250,11 +266,11 @@ function describeToolCall(call) {
  * the failure is greppable. A non-blocking (advisory) hook failure never reaches
  * here — the runner reports it and resolves normally.
  */
-async function fireBeforeTool(hooks, ctx, toolUseId) {
+async function fireBeforeTool(hooks, ctx, toolUseId, hint) {
     if (!hooks)
         return null;
     try {
-        await hooks.fire("before-tool", ctx);
+        await hooks.fire("before-tool", ctx, hint);
         return null;
     }
     catch (err) {

package/dist/approval/index.d.ts

@@ -3,3 +3,4 @@ export * from "./classify.js";
 export * from "./policy.js";
 export * from "./prompt.js";
 export * from "./service.js";
+export * from "./mutex.js";

package/dist/approval/index.js

@@ -3,3 +3,4 @@ export * from "./classify.js";
 export * from "./policy.js";
 export * from "./prompt.js";
 export * from "./service.js";
+export * from "./mutex.js";

package/dist/approval/mutex.d.ts

@@ -0,0 +1,45 @@
+import type { ApprovalDecision } from "./types.js";
+import type { ApproveAction } from "../tools/types.js";
+/**
+ * The approval mutex (C.33, JC-C) — the spine of the concurrent-subagent safety
+ * model. Node is single-threaded, so the only hazard between parallel subagents
+ * is interleaving at `await` boundaries; the one resource they genuinely contend
+ * for is the interactive terminal (one prompt at a time) and the run's shared
+ * checkpoint state (one snapshot/set-write at a time). Serializing every
+ * *gated write* through this one lock resolves BOTH with a single mechanism:
+ *
+ *   • **one prompt at a time** — a child blocked awaiting the user's keypress
+ *     holds the lock, so no sibling can paint a second prompt over it (the
+ *     keypress is always attributable to the one displayed prompt); and
+ *   • **serialized gated writes** — the checkpoint hook (snapshot + per-root set
+ *     member write) runs inside the same critical section, so two concurrent
+ *     writes to disjoint roots can never race on `ensureCheckpoint`'s latch or
+ *     the set manifest.
+ *
+ * It is a plain promise-chain serializer: `runExclusive(fn)` runs `fn` only
+ * after every previously-enqueued `fn` has settled. It is a LEAF lock — nothing
+ * is acquired while holding it except the terminal and the filesystem, neither
+ * of which waits on a subagent resource — so it cannot take part in a cycle
+ * (see the deadlock argument in the C.33 design doc).
+ */
+export declare class ApprovalMutex {
+    /** The settled-marker chain: always resolves (never rejects), so a rejecting
+     * critical section never wedges the queue for the next waiter. */
+    private tail;
+    /** Run `fn` in mutual exclusion with every other `runExclusive` on this mutex. */
+    runExclusive<T>(fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * Wrap a fully-built gate (`ApprovalService.requestApproval` behind the C.32
+ * checkpoint hook) so that every gated action serializes through `mutex`.
+ *
+ * Every action that actually reaches the gate is a *mutation* — read-only tools
+ * never call `requestApproval` at all (see the ToolContext contract), so a
+ * parallel READ fan-out is already free of the lock and never stalls behind a
+ * sibling's pending prompt. The `read`-tier short-circuit below is therefore
+ * defensive belt-and-suspenders (mirroring `ApprovalService`'s own read check):
+ * if a read-classified action ever did flow here, it would bypass the spine
+ * rather than needlessly hold it. What the mutex serializes in practice is the
+ * mutating set — exactly the prompt + checkpoint work that must be one-at-a-time.
+ */
+export declare function serializeGate(gate: (action: ApproveAction) => Promise<ApprovalDecision>, mutex: ApprovalMutex, cwd: string): (action: ApproveAction) => Promise<ApprovalDecision>;

package/dist/approval/mutex.js

@@ -0,0 +1,57 @@
+import { classify } from "./classify.js";
+/**
+ * The approval mutex (C.33, JC-C) — the spine of the concurrent-subagent safety
+ * model. Node is single-threaded, so the only hazard between parallel subagents
+ * is interleaving at `await` boundaries; the one resource they genuinely contend
+ * for is the interactive terminal (one prompt at a time) and the run's shared
+ * checkpoint state (one snapshot/set-write at a time). Serializing every
+ * *gated write* through this one lock resolves BOTH with a single mechanism:
+ *
+ *   • **one prompt at a time** — a child blocked awaiting the user's keypress
+ *     holds the lock, so no sibling can paint a second prompt over it (the
+ *     keypress is always attributable to the one displayed prompt); and
+ *   • **serialized gated writes** — the checkpoint hook (snapshot + per-root set
+ *     member write) runs inside the same critical section, so two concurrent
+ *     writes to disjoint roots can never race on `ensureCheckpoint`'s latch or
+ *     the set manifest.
+ *
+ * It is a plain promise-chain serializer: `runExclusive(fn)` runs `fn` only
+ * after every previously-enqueued `fn` has settled. It is a LEAF lock — nothing
+ * is acquired while holding it except the terminal and the filesystem, neither
+ * of which waits on a subagent resource — so it cannot take part in a cycle
+ * (see the deadlock argument in the C.33 design doc).
+ */
+export class ApprovalMutex {
+    /** The settled-marker chain: always resolves (never rejects), so a rejecting
+     * critical section never wedges the queue for the next waiter. */
+    tail = Promise.resolve();
+    /** Run `fn` in mutual exclusion with every other `runExclusive` on this mutex. */
+    runExclusive(fn) {
+        const result = this.tail.then(fn);
+        // Advance the chain on a branch that swallows the outcome, so the caller
+        // still observes `fn`'s rejection while the next waiter is not poisoned.
+        this.tail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+}
+/**
+ * Wrap a fully-built gate (`ApprovalService.requestApproval` behind the C.32
+ * checkpoint hook) so that every gated action serializes through `mutex`.
+ *
+ * Every action that actually reaches the gate is a *mutation* — read-only tools
+ * never call `requestApproval` at all (see the ToolContext contract), so a
+ * parallel READ fan-out is already free of the lock and never stalls behind a
+ * sibling's pending prompt. The `read`-tier short-circuit below is therefore
+ * defensive belt-and-suspenders (mirroring `ApprovalService`'s own read check):
+ * if a read-classified action ever did flow here, it would bypass the spine
+ * rather than needlessly hold it. What the mutex serializes in practice is the
+ * mutating set — exactly the prompt + checkpoint work that must be one-at-a-time.
+ */
+export function serializeGate(gate, mutex, cwd) {
+    return (action) => {
+        // Same classifier the gate uses; read tier contends for nothing → no lock.
+        if (classify(action, cwd).tier === "read")
+            return gate(action);
+        return mutex.runExclusive(() => gate(action));
+    };
+}

package/dist/checkpoint/service.d.ts

@@ -48,6 +48,14 @@ export declare class CheckpointService {
     private readonly pinnedStore?;
     private runSummary;
     private active;
+    /** In-flight `ensureCheckpoint` construction (C.33). PROMISE-latched, not
+     * value-latched: two concurrent gated writes to this root await the SAME
+     * snapshot instead of each taking one (the once-per-run latch `this.active`
+     * is only set AFTER several awaits, so a boolean/value latch would let a
+     * second caller slip through and double-snapshot). The approval mutex already
+     * serializes gated writes, so this is defense-in-depth — but it makes the
+     * service correct on its own, independent of the caller's discipline. */
+    private pending;
     constructor(opts: CheckpointServiceOptions);
     /** Start a new undo unit: reset the once-per-run latch and name the run. */
     beginRun(summary: string): void;
@@ -59,6 +67,7 @@ export declare class CheckpointService {
      * either substrate, the run must not mutate without its undo protection.
      */
     ensureCheckpoint(): Promise<Checkpoint | null>;
+    private buildCheckpoint;
     /** Attribute mutated paths to the current run (persisted for later rollback). */
     recordTouched(absPaths: string[]): Promise<void>;
     /** The run ran a shell command: per-path attribution is no longer possible. */

package/dist/checkpoint/service.js

@@ -36,6 +36,14 @@ export class CheckpointService {
     pinnedStore;
     runSummary = "agent run";
     active = null;
+    /** In-flight `ensureCheckpoint` construction (C.33). PROMISE-latched, not
+     * value-latched: two concurrent gated writes to this root await the SAME
+     * snapshot instead of each taking one (the once-per-run latch `this.active`
+     * is only set AFTER several awaits, so a boolean/value latch would let a
+     * second caller slip through and double-snapshot). The approval mutex already
+     * serializes gated writes, so this is defense-in-depth — but it makes the
+     * service correct on its own, independent of the caller's discipline. */
+    pending = null;
     constructor(opts) {
         this.root = path.resolve(opts.root);
         this.config = opts.config;
@@ -44,6 +52,7 @@ export class CheckpointService {
     /** Start a new undo unit: reset the once-per-run latch and name the run. */
     beginRun(summary) {
         this.active = null;
+        this.pending = null;
         const firstLine = summary.split("\n", 1)[0].trim();
         this.runSummary =
             firstLine.length > 80
@@ -62,6 +71,17 @@ export class CheckpointService {
             return null;
         if (this.active)
             return this.active;
+        // Coalesce concurrent first-use: a second caller awaits the first's snapshot
+        // rather than starting a second one. Cleared on settle so a FAILED attempt
+        // (which leaves `this.active` null) lets the next call retry.
+        if (this.pending)
+            return this.pending;
+        this.pending = this.buildCheckpoint().finally(() => {
+            this.pending = null;
+        });
+        return this.pending;
+    }
+    async buildCheckpoint() {
         const gitWorkTree = this.pinnedStore
             ? this.pinnedStore.kind === "git"
             : isGitWorkTree(this.root);

package/dist/cli/commands/run.js

@@ -7,14 +7,14 @@ import { themeForColor } from "../../theme/index.js";
 import { summarizeRuns, renderSummary, } from "../../usage/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, singleRootWorkspace, } from "../../workspace/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).
@@ -59,7 +59,7 @@ export function runCommand() {
         // onboarding or the session starts, never a half-built session.
         const workspace = opts.root.length
             ? await buildWorkspace(opts.root, { cwd: invocationCwd })
-            : singleRootWorkspace(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"}`));
@@ -78,7 +78,7 @@ export function runCommand() {
                 ? "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/MCP scope to primary this release`));
+                `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
@@ -127,21 +127,46 @@ export function runCommand() {
             ? await SandboxService.create({
                 config,
                 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: primaryRoot,
-            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
@@ -153,10 +178,19 @@ export function runCommand() {
             interactive: Boolean(process.stdin.isTTY),
             io: defaultPromptIO(shouldUseColor()),
         });
-        const session = buildAgentSession(config, apiKey, workspace, 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,7 +1,7 @@
 import { resolveApiKey } from "../config/index.js";
 import { createDefaultDeps, defaultOnboardingIO, isFirstRun, runOnboarding, } from "../onboarding/index.js";
 import { createRenderer } from "../render/index.js";
-import { singleRootWorkspace } from "../workspace/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
@@ -27,7 +27,7 @@ export async function runFirstWinTask(config, cwd, prompt) {
     const renderer = createRenderer();
     // 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, singleRootWorkspace(cwd), true, false, renderer);
+    const session = buildAgentSession(config, apiKey, sessionWorkspace(cwd), true, false, renderer);
     try {
         await session.send(prompt, renderer);
     }

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

@@ -3,7 +3,7 @@ import type { ApprovalDecision } from "../approval/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";
 /**
@@ -16,6 +16,28 @@ import type { Workspace } from "../workspace/index.js";
  * external-change detection.
  */
 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).