@cruxy/cli 0.23.0 → 0.24.0

package/dist/cli/session-factory.js

@@ -3,17 +3,17 @@ 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, classify, defaultPromptIO, } from "../approval/index.js";
+import { ApprovalMutex, ApprovalService, InteractivePolicy, SessionAllowlist, classify, defaultPromptIO, serializeGate, } 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 { routerForConfig } from "../routing/index.js";
-import { MemoryService, rememberTool } from "../memory/index.js";
+import { MemoryService, buildMultiRootRecallBlock, rememberTool, } from "../memory/index.js";
 import { findDefinitionTool, findReferencesTool, getDiagnosticsTool, hoverTool, } from "../lsp/index.js";
 import { createWebSearchTool, createWebFetchTool } from "../web/index.js";
 import { appendRun } from "../usage/index.js";
-import { SubagentOrchestrator, makeSpawnSubagentTool, } from "../subagent/index.js";
+import { SubagentOrchestrator, makeSpawnSubagentTool, makeSpawnSubagentsTool, } 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
@@ -146,6 +146,59 @@ function attributeFileTargets(action, ws) {
     }
     return byRoot;
 }
+/**
+ * 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 function registerRuntimeTools(registry, config, opts = {}) {
+    // Persistent memory write tool (C.29) — inert unless enabled.
+    if (config.memory.enabled)
+        registry.register(rememberTool);
+    // Per-language LSP introspection (C.12): four read-only tools that spawn
+    // EXTERNAL language servers, so opt-in; none registered when off.
+    if (config.lsp.enabled) {
+        registry.register(findDefinitionTool);
+        registry.register(findReferencesTool);
+        registry.register(getDiagnosticsTool);
+        registry.register(hoverTool);
+    }
+    // Web search + fetch (C.20): read-only, reach the PUBLIC internet and inject
+    // untrusted data, so opt-in; neither registered (nor a provider constructed)
+    // when off.
+    if (config.web.enabled) {
+        registry.register(createWebSearchTool());
+        registry.register(createWebFetchTool());
+    }
+    // MCP servers (C.27): already connected, trusted, and adapted to bounded,
+    // destructive-gated, `mcp__`-namespaced tools before we got here — a plain
+    // hand-off. Empty unless mcp is enabled with a trusted server.
+    for (const tool of opts.mcpTools ?? [])
+        registry.register(tool);
+    // Subagent spawn (C.14) + parallel fan-out (C.33): only when nesting depth
+    // allows (maxDepth 0 disables the feature structurally). Both are read-only to
+    // propose; the plan propose phase filters them out. The plural `spawn_subagents`
+    // is registered ONLY here (the main registry) — never on a child's scoped
+    // registry — so parallel fan-out stays a depth-0 capability.
+    if (config.subagent.maxDepth > 0) {
+        if (opts.spawnTool)
+            registry.register(opts.spawnTool);
+        if (opts.spawnManyTool)
+            registry.register(opts.spawnManyTool);
+    }
+}
 /**
  * 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).
@@ -191,51 +244,71 @@ export function buildAgentSession(config, apiKey, workspace, ttyInteractive, pla
     const execRegistry = buildDefaultRegistry();
     const git = getGitInfo(cwd);
     const projectInstructions = loadProjectInstructions(cwd);
-    // Persistent memory (C.29): register the write tool and build the recall block
-    // ONCE at session start. User memory is always eligible; project memory is
-    // recalled only when trusted (a cloned repo's notes never inject silently).
-    // Fully inert when disabled. Recall is best-effort — a load problem degrades to
-    // "no memory", never a hard failure at session start.
+    // Persistent memory (C.29): build the recall block ONCE at session start (the
+    // `remember` write tool is registered via registerRuntimeTools below). User
+    // memory is always eligible; project memory is recalled only when trusted (a
+    // cloned repo's notes never inject silently). Fully inert when disabled. Recall
+    // is best-effort — a load problem degrades to "no memory", never a hard failure.
     let recalledMemory = null;
     if (config.memory.enabled) {
-        execRegistry.register(rememberTool);
-        const recall = new MemoryService({ cwd, config: config.memory }).recall();
-        recalledMemory = recall.block;
-        if (recall.projectPresentButUntrusted) {
-            logger.info("project memory found but not trusted — run `cruxy memory trust .` to recall it");
+        if (workspace.isMultiRoot) {
+            // Recall project memory from EVERY trusted root, each under its own
+            // root-labeled block; user memory (global) once. Untrusted roots are not
+            // injected and are NAMED — a cloned repo's notes never inject silently,
+            // and a root whose notes you've never trusted is called out, not dropped.
+            const roots = [];
+            let userEntries = [];
+            for (const r of workspace.roots()) {
+                const svc = new MemoryService({
+                    cwd: r.absPath,
+                    config: config.memory,
+                });
+                const st = svc.status();
+                // The label is paired with the store HERE — structurally, a block can
+                // never carry a root the entries didn't come from.
+                if (r.primary) {
+                    userEntries = st.user;
+                    for (const e of st.errors) {
+                        logger.warn(`memory: excluded ${e.scope} entry ${e.id} — ${e.message}`);
+                    }
+                }
+                else {
+                    // Siblings share the same global user file — surface only their own
+                    // project-scope load errors (user errors already reported by primary).
+                    for (const e of st.errors.filter((e) => e.scope === "project")) {
+                        logger.warn(`memory: excluded ${e.scope} entry ${e.id} in ${r.name} — ${e.message}`);
+                    }
+                }
+                if (st.projectTrusted) {
+                    if (st.project.length > 0)
+                        roots.push({ name: r.name, entries: st.project });
+                }
+                else if (st.project.length > 0) {
+                    logger.info(`memory:  root "${r.name}" project memory not trusted — run \`cruxy memory trust ${r.absPath}\` to recall it`);
+                }
+            }
+            recalledMemory = buildMultiRootRecallBlock({
+                user: userEntries,
+                roots,
+                maxTokens: config.memory.maxRecallTokens,
+            });
         }
-        for (const e of recall.errors) {
-            logger.warn(`memory: excluded ${e.scope} entry ${e.id} — ${e.message}`);
+        else {
+            const recall = new MemoryService({ cwd, config: config.memory }).recall();
+            recalledMemory = recall.block;
+            if (recall.projectPresentButUntrusted) {
+                logger.info("project memory found but not trusted — run `cruxy memory trust .` to recall it");
+            }
+            for (const e of recall.errors) {
+                logger.warn(`memory: excluded ${e.scope} entry ${e.id} — ${e.message}`);
+            }
         }
     }
-    // Per-language LSP (C.12): register the four read-only introspection tools
-    // only when enabled. They spawn and manage EXTERNAL language-server processes,
-    // so — like the sandbox — the feature is opt-in; when off, none is registered
-    // and no server ever spawns. Read-only (no approval), so they bypass the U.3
-    // gate like search_codebase and are available to subagents and plan proposals.
-    if (config.lsp.enabled) {
-        execRegistry.register(findDefinitionTool);
-        execRegistry.register(findReferencesTool);
-        execRegistry.register(getDiagnosticsTool);
-        execRegistry.register(hoverTool);
-    }
-    // Web search + fetch (C.20): register the two read-only web tools only when
-    // enabled. They reach the PUBLIC internet and inject attacker-controllable data
-    // (results/pages are demarcated as untrusted and never persisted), so — like
-    // LSP and MCP — the feature is opt-in; when off, neither tool is registered and
-    // no search provider is ever constructed. Read-only (no approval), so they
-    // bypass the U.3 gate like search_codebase.
-    if (config.web.enabled) {
-        execRegistry.register(createWebSearchTool());
-        execRegistry.register(createWebFetchTool());
-    }
-    // MCP servers (C.27): the caller connected + trusted the servers and produced
-    // these tools through the single adapter seam BEFORE building the session, so
-    // registration here is a plain hand-off — every one is destructive-gated,
-    // demarcated, and bounded by construction. Empty unless `mcp.enabled` and at
-    // least one trusted server produced tools, so the default path is unchanged.
-    for (const tool of mcpTools)
-        execRegistry.register(tool);
+    // The conditionally-registered runtime tools (remember / LSP / web / MCP) are
+    // added below via registerRuntimeTools — the single seam the JC-B allowlist test
+    // also builds through, so the audited surface can never drift from the shipped
+    // one. spawn_subagent joins them there too (it needs the orchestrator built
+    // first). See registerRuntimeTools.
     // 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
@@ -247,7 +320,13 @@ export function buildAgentSession(config, apiKey, workspace, ttyInteractive, pla
     // wired, and it is set on the SAME ctx whose `requestApproval` IS that gate — so
     // lifting the non-primary-write refusal and capturing the write are one decision.
     const checkpointsActive = Boolean(checkpoints);
-    const gate = (approval) => withCheckpointGate(resumeLineAfterApproval((action) => approval.requestApproval(action), renderer), checkpoints, workspace);
+    // The C.33 spine: ONE approval mutex shared by the main loop and every subagent
+    // gate, so across concurrent siblings only one non-read action is in its gate at
+    // a time — one prompt on screen, one checkpoint snapshot/set-write in flight.
+    // Read-tier actions bypass it (see serializeGate), so a parallel read fan-out is
+    // never stalled behind an unrelated pending prompt.
+    const approvalMutex = new ApprovalMutex();
+    const gate = (approval) => serializeGate(withCheckpointGate(resumeLineAfterApproval((action) => approval.requestApproval(action), renderer), checkpoints, workspace), approvalMutex, 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
@@ -267,9 +346,20 @@ export function buildAgentSession(config, apiKey, workspace, ttyInteractive, pla
         checkpointsActive,
         makeChildApproval: () => gate(new ApprovalService({ cwd, interactive: ttyInteractive, io })),
     });
-    if (config.subagent.maxDepth > 0) {
-        execRegistry.register(makeSpawnSubagentTool(orchestrator, 0));
-    }
+    // Now that the orchestrator exists, register every conditionally-enabled tool
+    // (remember / LSP / web / MCP / spawn_subagent) through the one seam the JC-B
+    // allowlist test also uses — order preserved, behaviour byte-identical.
+    const spawnTool = config.subagent.maxDepth > 0
+        ? makeSpawnSubagentTool(orchestrator, 0)
+        : undefined;
+    const spawnManyTool = config.subagent.maxDepth > 0
+        ? makeSpawnSubagentsTool(orchestrator, 0)
+        : undefined;
+    registerRuntimeTools(execRegistry, config, {
+        mcpTools,
+        spawnTool,
+        spawnManyTool,
+    });
     if (planMode) {
         // 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.

package/dist/config/schema.d.ts

@@ -248,6 +248,15 @@ export declare const SubagentConfigSchema: z.ZodObject<{
      * 1 lets it spawn subagents that cannot themselves spawn (no fork bombs).
      */
     maxDepth: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Parallel fan-out breadth (C.33): the maximum number of subagents that run
+     * concurrently across the whole session, enforced by one shared semaphore.
+     * Parallel fan-out happens at depth 0 only and everything beneath it is
+     * sequential, so this composes with {@link maxDepth} into a LINEAR global
+     * ceiling (≤ maxConcurrency × maxDepth live agents) — never an exponential
+     * depth×breadth fork bomb. Default 3.
+     */
+    maxConcurrency: 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. */
@@ -267,6 +276,7 @@ export declare const SubagentConfigSchema: z.ZodObject<{
     }>>;
 }, "strict", z.ZodTypeAny, {
     maxDepth: number;
+    maxConcurrency: number;
     defaultBudget: {
         maxTokens: number;
         maxIterations: number;
@@ -274,6 +284,7 @@ export declare const SubagentConfigSchema: z.ZodObject<{
     };
 }, {
     maxDepth?: number | undefined;
+    maxConcurrency?: number | undefined;
     defaultBudget?: {
         timeoutMs?: number | undefined;
         maxTokens?: number | undefined;
@@ -1027,6 +1038,15 @@ export declare const CruxyConfigSchema: z.ZodObject<{
          * 1 lets it spawn subagents that cannot themselves spawn (no fork bombs).
          */
         maxDepth: z.ZodDefault<z.ZodNumber>;
+        /**
+         * Parallel fan-out breadth (C.33): the maximum number of subagents that run
+         * concurrently across the whole session, enforced by one shared semaphore.
+         * Parallel fan-out happens at depth 0 only and everything beneath it is
+         * sequential, so this composes with {@link maxDepth} into a LINEAR global
+         * ceiling (≤ maxConcurrency × maxDepth live agents) — never an exponential
+         * depth×breadth fork bomb. Default 3.
+         */
+        maxConcurrency: 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. */
@@ -1046,6 +1066,7 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         }>>;
     }, "strict", z.ZodTypeAny, {
         maxDepth: number;
+        maxConcurrency: number;
         defaultBudget: {
             maxTokens: number;
             maxIterations: number;
@@ -1053,6 +1074,7 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         };
     }, {
         maxDepth?: number | undefined;
+        maxConcurrency?: number | undefined;
         defaultBudget?: {
             timeoutMs?: number | undefined;
             maxTokens?: number | undefined;
@@ -1450,6 +1472,7 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     };
     subagent: {
         maxDepth: number;
+        maxConcurrency: number;
         defaultBudget: {
             maxTokens: number;
             maxIterations: number;
@@ -1594,6 +1617,7 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     } | undefined;
     subagent?: {
         maxDepth?: number | undefined;
+        maxConcurrency?: number | undefined;
         defaultBudget?: {
             timeoutMs?: number | undefined;
             maxTokens?: number | undefined;

package/dist/config/schema.js

@@ -181,6 +181,15 @@ export const SubagentConfigSchema = z
      * 1 lets it spawn subagents that cannot themselves spawn (no fork bombs).
      */
     maxDepth: z.number().int().nonnegative().default(1),
+    /**
+     * Parallel fan-out breadth (C.33): the maximum number of subagents that run
+     * concurrently across the whole session, enforced by one shared semaphore.
+     * Parallel fan-out happens at depth 0 only and everything beneath it is
+     * sequential, so this composes with {@link maxDepth} into a LINEAR global
+     * ceiling (≤ maxConcurrency × maxDepth live agents) — never an exponential
+     * depth×breadth fork bomb. Default 3.
+     */
+    maxConcurrency: z.number().int().positive().default(3),
     /** Per-subagent budget ceilings; spawn-time overrides are clamped to these. */
     defaultBudget: z
         .object({

package/dist/errors/constructors.d.ts

@@ -190,6 +190,29 @@ export declare function checkpointSetPartial(runId: string, restored: string[],
  * orchestrator seam was driven directly — fail loud, never spawn.
  */
 export declare function subagentDepthExceeded(depth: number, maxDepth: number): CruxyError;
+/** One workspace root claimed by two-or-more WRITING children of a single
+ * `spawn_subagents` call — the unit of a disjoint-scope violation (C.33). */
+export interface ScopeConflict {
+    /** The root name both children declared write scope on. */
+    root: string;
+    /** The task labels of every writing child that claimed `root` (always ≥2). */
+    tasks: string[];
+}
+/**
+ * A parallel fan-out (C.33) declared children with overlapping write scope — two
+ * or more target the SAME workspace root while both hold mutating tools. The
+ * ENTIRE batch is refused BEFORE any child is dispatched, so concurrent siblings
+ * can never race on one root's files or checkpoint. Every colliding group is
+ * named (the conflicting task pairs, per root) so the model can fix all of them
+ * at once. Surfaced as a tool error to correct (assign distinct roots, or drop
+ * write tools on all but one child per root).
+ *
+ * THE HONEST LIMIT, stated in the message: the check is on DECLARED scope — the
+ * tools + root each child was granted — NOT the files actually written. Two
+ * children could still touch disjoint paths under one root; cruxy refuses anyway
+ * rather than let two potential writers race on that root's single checkpoint.
+ */
+export declare function subagentScopeOverlap(conflicts: readonly ScopeConflict[]): CruxyError;
 /**
  * A subagent run failed outright (provider error, tool crash) before producing
  * a result. Normally folded into the structured `SubagentResult` the parent

package/dist/errors/constructors.js

@@ -737,6 +737,44 @@ export function subagentDepthExceeded(depth, maxDepth) {
         meta: { depth, maxDepth },
     });
 }
+/**
+ * A parallel fan-out (C.33) declared children with overlapping write scope — two
+ * or more target the SAME workspace root while both hold mutating tools. The
+ * ENTIRE batch is refused BEFORE any child is dispatched, so concurrent siblings
+ * can never race on one root's files or checkpoint. Every colliding group is
+ * named (the conflicting task pairs, per root) so the model can fix all of them
+ * at once. Surfaced as a tool error to correct (assign distinct roots, or drop
+ * write tools on all but one child per root).
+ *
+ * THE HONEST LIMIT, stated in the message: the check is on DECLARED scope — the
+ * tools + root each child was granted — NOT the files actually written. Two
+ * children could still touch disjoint paths under one root; cruxy refuses anyway
+ * rather than let two potential writers race on that root's single checkpoint.
+ */
+export function subagentScopeOverlap(conflicts) {
+    const list = conflicts
+        .map((c) => `root "${c.root}" ← ${c.tasks.map((t) => `“${t}”`).join(", ")}`)
+        .join("; ");
+    return new CruxyError({
+        code: ErrorCode.SubagentScopeOverlap,
+        title: conflicts.length === 1
+            ? `parallel subagents overlap on root "${conflicts[0].root}"`
+            : `parallel subagents overlap on ${conflicts.length} roots`,
+        cause: `these children of one spawn_subagents call declared write scope on the ` +
+            `same root — ${list}. The check is on DECLARED scope (the tools and root ` +
+            `each child was granted), NOT the files actually written — two children ` +
+            `could still touch disjoint paths — but cruxy refuses the whole batch ` +
+            `rather than let two writers race on one root's checkpoint.`,
+        nextSteps: [
+            "give each writing child a distinct `root` (parallel writes require disjoint roots)",
+            "or grant write/shell tools to only one child per root and keep the rest read-only",
+            "or run the conflicting subtasks sequentially with spawn_subagent",
+        ],
+        meta: {
+            conflicts: conflicts.map((c) => ({ root: c.root, tasks: [...c.tasks] })),
+        },
+    });
+}
 /**
  * A subagent run failed outright (provider error, tool crash) before producing
  * a result. Normally folded into the structured `SubagentResult` the parent

package/dist/errors/types.d.ts

@@ -52,6 +52,14 @@ export declare const ErrorCode: {
     /** Carried inside a SubagentResult (informational) — never fatal by itself. */
     readonly SubagentBudget: "CRUXY_E_SUBAGENT_BUDGET";
     readonly SubagentFailed: "CRUXY_E_SUBAGENT_FAILED";
+    /** Two children of one parallel fan-out (C.33) declare overlapping write scope
+     * (same root). Refused pre-dispatch so concurrent siblings can never race on a
+     * root — the model corrects it (distinct roots, or read-only). */
+    readonly SubagentScopeOverlap: "CRUXY_E_SUBAGENT_SCOPE_OVERLAP";
+    /** Carried inside a SubagentResult (informational): the run was cancelled — a
+     * fatal sibling failure or Ctrl-C aborted the whole fan-out (C.33). Never a
+     * fabricated success; the parent sees exactly which children did not finish. */
+    readonly SubagentCancelled: "CRUXY_E_SUBAGENT_CANCELLED";
     readonly TestCommandNotFound: "CRUXY_E_TEST_COMMAND_NOT_FOUND";
     /** Carried inside a run_tests result (informational) — never fatal by itself. */
     readonly TestIterationLimit: "CRUXY_E_TEST_ITERATION_LIMIT";

package/dist/errors/types.js

@@ -63,6 +63,14 @@ export const ErrorCode = {
     /** Carried inside a SubagentResult (informational) — never fatal by itself. */
     SubagentBudget: "CRUXY_E_SUBAGENT_BUDGET",
     SubagentFailed: "CRUXY_E_SUBAGENT_FAILED",
+    /** Two children of one parallel fan-out (C.33) declare overlapping write scope
+     * (same root). Refused pre-dispatch so concurrent siblings can never race on a
+     * root — the model corrects it (distinct roots, or read-only). */
+    SubagentScopeOverlap: "CRUXY_E_SUBAGENT_SCOPE_OVERLAP",
+    /** Carried inside a SubagentResult (informational): the run was cancelled — a
+     * fatal sibling failure or Ctrl-C aborted the whole fan-out (C.33). Never a
+     * fabricated success; the parent sees exactly which children did not finish. */
+    SubagentCancelled: "CRUXY_E_SUBAGENT_CANCELLED",
     // testing (exit 2 / 11)
     TestCommandNotFound: "CRUXY_E_TEST_COMMAND_NOT_FOUND",
     /** Carried inside a run_tests result (informational) — never fatal by itself. */
@@ -230,6 +238,10 @@ const EXIT_CODES = {
     [ErrorCode.SubagentDepthExceeded]: 2,
     [ErrorCode.SubagentBudget]: 11,
     [ErrorCode.SubagentFailed]: 11,
+    // Overlapping fan-out scope is a spawn misuse (usage, model-correctable);
+    // cancellation surfaces inside a SubagentResult and is never fatal by itself.
+    [ErrorCode.SubagentScopeOverlap]: 2,
+    [ErrorCode.SubagentCancelled]: 11,
     // No test command is a configuration gap (usage); the iteration limit
     // surfaces inside a run_tests result and is never fatal by itself.
     [ErrorCode.TestCommandNotFound]: 2,

package/dist/hooks/index.d.ts

@@ -4,3 +4,4 @@ export { fileTrustStore, fingerprintHooks, isTrusted, memoryTrustStore, trustPat
 export { HookRunner, type HookRunnerDeps, type TrustPromptInfo, } from "./runner.js";
 export { BUILTIN_SLASH_COMMANDS, expandTemplate, isBuiltinSlash, resolveSlash, type SlashResolution, } from "./slash.js";
 export { buildHooksService, type BuildHooksServiceOptions, type HooksService, } from "./service.js";
+export { buildHooksRouter, type BuildHooksRouterOptions, type HooksRouterResult, type UntrustedHookRoot, } from "./router.js";

package/dist/hooks/index.js

@@ -4,3 +4,4 @@ export { fileTrustStore, fingerprintHooks, isTrusted, memoryTrustStore, trustPat
 export { HookRunner, } from "./runner.js";
 export { BUILTIN_SLASH_COMMANDS, expandTemplate, isBuiltinSlash, resolveSlash, } from "./slash.js";
 export { buildHooksService, } from "./service.js";
+export { buildHooksRouter, } from "./router.js";

package/dist/hooks/router.d.ts

@@ -0,0 +1,58 @@
+import type { CruxyConfig } from "../config/index.js";
+import type { LifecycleHookRunner } from "../agent/loop.js";
+import type { logger as Logger } from "../utils/logger.js";
+import type { DeclaredRoot, Workspace } from "../workspace/index.js";
+import { type TrustStore } from "./trust.js";
+import type { HookCatalog, SlashCommandSpec } from "./types.js";
+/**
+ * Per-root hook dispatch for a multi-root session (C.26 step 5).
+ *
+ * The isolation here is a PROPERTY OF CONSTRUCTION, not a guard: each root gets
+ * its OWN {@link HookRunner} (own project-hook catalog, own trust key), so there
+ * is no code path from root A's runner to a root-B action. The router only
+ * decides WHICH runner to invoke:
+ *
+ *   - Tool-scoped events (`before-tool` / `after-tool` / `on-file-change`) fire
+ *     exactly the ONE acting root's runner — the same root the tool resolved via
+ *     {@link selectRoot}. A's project hooks structurally cannot fire for a
+ *     B-scoped call (⚖︎10, pinned by test).
+ *   - Session lifecycle events (`before-run` / `after-run`) have NO acting root,
+ *     so they fan EVERY trusted root sequentially, in declaration order,
+ *     root-labeled; a blocking failure in any root aborts the run naming that
+ *     root (JC-1). Untrusted roots are skipped and named in the startup banner —
+ *     never silent (a user's pre-run guard in an untrusted root must not vanish
+ *     without a word).
+ *
+ * User-scope hooks (`~/.cruxy`) are session-global — authored by you, shared by
+ * every root — so they fire EXACTLY ONCE per event through a single shared
+ * runner, never once per root.
+ */
+/** A root whose project hooks exist but are not trusted → named in the banner. */
+export interface UntrustedHookRoot {
+    name: string;
+    absPath: string;
+    count: number;
+}
+export interface HooksRouterResult {
+    /** The lifecycle firing seam (a {@link LifecycleHookRunner}). */
+    runner: LifecycleHookRunner;
+    /** Custom slash commands (primary root only this release). */
+    commands: SlashCommandSpec[];
+    /** Roots with untrusted project hooks — named in the banner, never silent. */
+    untrustedHookRoots: UntrustedHookRoot[];
+}
+export interface BuildHooksRouterOptions {
+    workspace: Workspace;
+    config: CruxyConfig;
+    logger: typeof Logger;
+    trust?: TrustStore;
+    /** Per-root catalog loader; defaults to the layered on-disk loader. */
+    loadCatalog?: (root: DeclaredRoot) => Promise<HookCatalog>;
+    now?: () => string;
+}
+/**
+ * Build the multi-root hook router. One project-hook runner per declared root
+ * (trust-gated against that root's key) plus one shared user-hook runner. Load
+ * errors are surfaced through the logger exactly as the single-root path does.
+ */
+export declare function buildHooksRouter(opts: BuildHooksRouterOptions): Promise<HooksRouterResult>;

package/dist/hooks/router.js

@@ -0,0 +1,136 @@
+import { selectRoot } from "../workspace/index.js";
+import { defaultHookSources, loadHookCatalog } from "./config.js";
+import { HookRunner } from "./runner.js";
+import { fileTrustStore } from "./trust.js";
+const LIFECYCLE_EVENTS = new Set(["before-run", "after-run"]);
+/**
+ * Resolve the ONE acting root for a tool-scoped event from the raw tool-call
+ * input, reusing the exact {@link selectRoot} precedence the tool itself uses so
+ * the hook's root always matches the tool's root. Bare/ambiguous/unknown → the
+ * primary (a hook never crosses into a root the call didn't address).
+ */
+function resolveActingRoot(ws, input) {
+    if (input && typeof input === "object") {
+        const rec = input;
+        const root = typeof rec.root === "string" ? rec.root : undefined;
+        const p = typeof rec.path === "string" ? rec.path : undefined;
+        if (root !== undefined || p !== undefined) {
+            try {
+                return selectRoot(ws, { root, path: p ?? "." }).root;
+            }
+            catch {
+                // Unknown root name / not-contained absolute path → fall to primary.
+            }
+        }
+    }
+    return ws.primary();
+}
+class HookRouter {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async fire(event, ctx, hint) {
+        if (!this.deps.enabled)
+            return;
+        if (LIFECYCLE_EVENTS.has(event)) {
+            // Session lifecycle: user hooks once, then every TRUSTED root in order.
+            await this.deps.userRunner.fire(event, ctx);
+            for (const root of this.deps.workspace.roots()) {
+                const runner = this.deps.perRoot.get(root.absPath);
+                if (!runner || !runner.projectTrusted)
+                    continue; // skipped; banner-named
+                // A blocking failure throws `hookFailed("<root> ▸ <hook>", …)` — the run
+                // aborts naming which root refused (the runner carries `label`).
+                await runner.fire(event, rootCtx(ctx, root));
+            }
+            return;
+        }
+        // Tool-scoped: exactly the ONE acting root (+ the shared user hooks).
+        const acting = resolveActingRoot(this.deps.workspace, hint?.input);
+        const actingCtx = rootCtx(ctx, acting);
+        await this.deps.userRunner.fire(event, actingCtx);
+        const runner = this.deps.perRoot.get(acting.absPath);
+        if (runner && runner.projectTrusted) {
+            await runner.fire(event, actingCtx);
+        }
+    }
+}
+/** A per-root view of the tool context: the hook command runs in THAT root's
+ * directory (`runGatedShell` uses `ctx.cwd`), so a root's hook always executes
+ * against its own tree — never the primary's. */
+function rootCtx(ctx, root) {
+    return { ...ctx, cwd: root.absPath };
+}
+/**
+ * Build the multi-root hook router. One project-hook runner per declared root
+ * (trust-gated against that root's key) plus one shared user-hook runner. Load
+ * errors are surfaced through the logger exactly as the single-root path does.
+ */
+export async function buildHooksRouter(opts) {
+    const trust = opts.trust ?? fileTrustStore();
+    const enabled = opts.config.hooks.enabled;
+    const perRoot = new Map();
+    const untrustedHookRoots = [];
+    let userHooks = [];
+    let primaryCommands = [];
+    const loadCatalog = opts.loadCatalog ??
+        ((root) => loadHookCatalog(defaultHookSources(root.absPath)));
+    for (const root of opts.workspace.roots()) {
+        const catalog = await loadCatalog(root);
+        for (const err of catalog.errors) {
+            opts.logger.warn(`ignoring malformed ${err.source} hook/command "${err.name}" in ${root.name}: ${err.message}`);
+        }
+        // Each root's runner owns ONLY its project hooks. User hooks are global —
+        // loaded once (from the primary, whose `sources.user` is identical for every
+        // root) and fired through the shared runner, never per-root.
+        const projectHooks = catalog.hooks.filter((h) => h.source === "project");
+        if (root.primary) {
+            userHooks = catalog.hooks.filter((h) => h.source === "user");
+            primaryCommands = catalog.commands;
+        }
+        const runner = new HookRunner({
+            hooks: projectHooks,
+            trust,
+            enabled,
+            // Multi-root never lazy-prompts (a barrage of per-sibling prompts mid-run
+            // is worse than a named skip). Untrusted roots are skipped + banner-named;
+            // `cruxy hooks trust <path>` is the deliberate opt-in.
+            trustPrompt: false,
+            interactive: false,
+            cwd: root.absPath,
+            label: root.name,
+            announce: (m) => opts.logger.info(`[${root.name}] ${m}`),
+            reportFailure: (m) => opts.logger.warn(`[${root.name}] ${m}`),
+            now: opts.now,
+        });
+        perRoot.set(root.absPath, runner);
+        if (!runner.projectTrusted) {
+            untrustedHookRoots.push({
+                name: root.name,
+                absPath: root.absPath,
+                count: runner.projectHookCount,
+            });
+        }
+    }
+    // Shared user-hook runner: user hooks carry no project source, so its trust
+    // gate never triggers (you authored them) — it just fires them once.
+    const userRunner = new HookRunner({
+        hooks: userHooks,
+        trust,
+        enabled,
+        trustPrompt: false,
+        interactive: false,
+        cwd: opts.workspace.primary().absPath,
+        announce: (m) => opts.logger.info(m),
+        reportFailure: (m) => opts.logger.warn(m),
+        now: opts.now,
+    });
+    const runner = new HookRouter({
+        workspace: opts.workspace,
+        perRoot,
+        userRunner,
+        enabled,
+    });
+    return { runner, commands: primaryCommands, untrustedHookRoots };
+}