@cruxy/cli 0.23.0 → 0.25.0

package/dist/memory/remember-tool.js

@@ -23,6 +23,10 @@ const RememberSchema = z.object({
         .enum(["user", "project"])
         .optional()
         .describe("'user' (default) saves to your cross-project memory; 'project' saves to this repo's memory (shared with the repo)."),
+    root: z
+        .string()
+        .optional()
+        .describe("Which declared workspace root a 'project' note belongs to, by name. Defaults to the primary root; ignored for 'user' scope. In a single-root session, omit."),
 });
 export const rememberTool = {
     name: "remember",
@@ -30,8 +34,14 @@ export const rememberTool = {
     parameters: RememberSchema,
     async execute(input, ctx) {
         try {
+            // A named `root` targets that root's project memory (default: primary). A
+            // bad name throws CRUXY_E_ROOT_UNKNOWN, surfaced to the model below. User
+            // memory is global, so `root` never changes where it lands.
+            const cwd = input.root && ctx.workspace
+                ? ctx.workspace.rootByName(input.root).absPath
+                : ctx.cwd;
             const service = new MemoryService({
-                cwd: ctx.cwd,
+                cwd,
                 config: ctx.config.memory,
             });
             const entry = service.remember({

package/dist/sandbox/policy.js

@@ -30,11 +30,20 @@ export function buildPolicy(cfg, cwd, opts = {}) {
     const siblingRoots = (opts.siblingRoots ?? [])
         .map((r) => resolvePath(r))
         .filter((r) => r !== resolvePath(cwd)) // the workdir is never a sibling
-        .map((source) => ({
-        source,
-        target: source, // identical path, like the workdir, for path coherence
-        readonly: !writable.has(source), // RO unless explicitly escalated (R5)
-    }));
+        .map((source) => {
+        // A declared root is user input too — hold it to the SAME escape-hatch
+        // refusal as `sandbox.mounts` (JC-G): never mount the docker socket, the
+        // cruxy credential home, or `$HOME`/`/` even if declared as a root.
+        const forbidden = forbiddenMountSource(source);
+        if (forbidden) {
+            throw configInvalid(`refusing to mount workspace root ${forbidden}: "${source}"`);
+        }
+        return {
+            source,
+            target: source, // identical path, like the workdir, for path coherence
+            readonly: !writable.has(source), // RO unless explicitly escalated (R5)
+        };
+    });
     return {
         image: cfg.image,
         network: cfg.network,

package/dist/sandbox/service.d.ts

@@ -10,8 +10,15 @@ export interface SandboxReporter {
 }
 export interface SandboxServiceDeps {
     config: CruxyConfig;
-    /** The run's working directory — mounted read-write as the workdir. */
+    /** The command's own workspace root — mounted read-write as the workdir. */
     cwd: string;
+    /** The OTHER declared roots in a multi-repo session (C.26, R5). Each is
+     * mounted READ-ONLY so cross-repo reads work but a command can't silently
+     * write a sibling. Empty/absent in a single-root session. */
+    siblingRoots?: readonly string[];
+    /** Sibling roots granted an approved cross-root-write escalation (R5): each
+     * named one flips to read-write, and ONLY that one — never blanket. */
+    writableRoots?: readonly string[];
     /** Execution runtime seam (defaults to Docker). */
     runtime?: SandboxRuntime;
     /** Capability probe seam (defaults to real docker detection). */

package/dist/sandbox/service.js

@@ -34,7 +34,10 @@ export class SandboxService {
         if (!capability.available) {
             throw sandboxUnavailable(capability.runtime, capability.detail);
         }
-        const policy = buildPolicy(deps.config.sandbox, deps.cwd);
+        const policy = buildPolicy(deps.config.sandbox, deps.cwd, {
+            siblingRoots: deps.siblingRoots,
+            writableRoots: deps.writableRoots,
+        });
         return new SandboxService(runtime, policy, deps.reporter);
     }
     /** The runtime backing this service (e.g. "docker") — for logging. */

package/dist/subagent/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./types.js";
 export * from "./budget.js";
+export * from "./semaphore.js";
 export * from "./registry-scope.js";
 export * from "./orchestrator.js";
 export * from "./spawn-tool.js";

package/dist/subagent/index.js

@@ -1,5 +1,6 @@
 export * from "./types.js";
 export * from "./budget.js";
+export * from "./semaphore.js";
 export * from "./registry-scope.js";
 export * from "./orchestrator.js";
 export * from "./spawn-tool.js";

package/dist/subagent/orchestrator.d.ts

@@ -5,7 +5,8 @@ import type { StreamRenderer } from "../render/index.js";
 import type { Router } from "../routing/index.js";
 import type { ApproveAction, ToolContext, ToolRegistry } from "../tools/index.js";
 import type { SandboxService } from "../sandbox/index.js";
-import type { Workspace } from "../workspace/index.js";
+import { Workspace } from "../workspace/index.js";
+import { Semaphore } from "./semaphore.js";
 import type { SubagentResult, SubagentSpec } from "./types.js";
 /**
  * Everything a spawn needs from the surrounding session, injected by the
@@ -60,6 +61,14 @@ export interface SubagentOrchestratorDeps {
      * same shared checkpoint gate, those writes join the run's one set (⚖︎JC-δ).
      */
     checkpointsActive?: boolean;
+    /**
+     * The ONE shared execution semaphore (C.28). When set, parallel fan-out draws
+     * permits from THIS instance — the same one background jobs use — so the
+     * `subagent.maxConcurrency` cap bounds subagents AND jobs COMBINED, never one
+     * cap each. Omitted → the orchestrator constructs its own (C.33 behaviour,
+     * used by tests that exercise the orchestrator in isolation).
+     */
+    executionSemaphore?: Semaphore;
 }
 /**
  * Spawns subagents (C.14): the existing agent loop re-driven over isolated
@@ -76,7 +85,19 @@ export interface SubagentOrchestratorDeps {
  */
 export declare class SubagentOrchestrator {
     private readonly deps;
+    /**
+     * The ONE shared bound on parallel fan-out (C.33, JC-D). Constructed once per
+     * session and reused by every {@link spawnMany} call (nested spawns reuse this
+     * same orchestrator instance), so `subagent.maxConcurrency` caps the number of
+     * concurrently-executing subagents across the WHOLE session — not per parent.
+     */
+    private readonly sem;
     constructor(deps: SubagentOrchestratorDeps);
+    /** Live/queued fan-out slots (inspection/tests): proves the global cap holds. */
+    get concurrency(): {
+        available: number;
+        waiting: number;
+    };
     /**
      * Run one subagent to completion. `parentDepth` is the spawner's depth (the
      * main agent is 0); spawning past `subagent.maxDepth` throws
@@ -89,7 +110,60 @@ export declare class SubagentOrchestrator {
      * (non-interactive default-deny must reach the boundary, U.3 — a subagent is
      * not a way to swallow it).
      */
-    spawn(spec: SubagentSpec, parentDepth: number): Promise<SubagentResult>;
+    spawn(spec: SubagentSpec, parentDepth: number, opts?: SpawnOptions): Promise<SubagentResult>;
+    /**
+     * Parallel fan-out (C.33): run N children concurrently under the shared
+     * concurrency semaphore and fold their outcomes into a result array whose
+     * order MATCHES `specs` (position i is spec i's result — never completion
+     * order). A DEPTH-0 capability only (the plural tool is never granted to a
+     * child), so no permit holder ever nests a second fan-out — the semaphore
+     * stays deadlock-free.
+     *
+     * Safety before dispatch: overlapping write scope is REFUSED
+     * (`CRUXY_E_SUBAGENT_SCOPE_OVERLAP`) so two writers can never race on one root.
+     *
+     * Cancellation: children share one {@link AbortController}. A child returning a
+     * `failed`/`budget-exceeded` result is a normal PARTIAL outcome — siblings run
+     * on. But a *fatal* throw from any child (non-interactive default-deny) or an
+     * abort on `opts.signal` (Ctrl-C) aborts the controller: every sibling stops at
+     * its next turn boundary and its in-flight shell child is kill-tree'd, so the
+     * fan-out leaves no orphan. All children are awaited to settle before a fatal
+     * throw propagates — never a detached, still-running sibling.
+     */
+    spawnMany(specs: readonly SubagentSpec[], parentDepth: number, opts?: {
+        signal?: AbortSignal;
+    }): Promise<SubagentResult[]>;
+    /**
+     * Resolve a child's scope from an optional root name. With a name: a
+     * single-root workspace over that root (writes confined to it) + that root's
+     * cwd. Without: the full session workspace + primary cwd (C.14 behaviour).
+     */
+    private childScope;
+    /**
+     * Refuse a fan-out where two WRITING children (any mutating tool granted)
+     * target the same root — the disjoint-scope guarantee (C.33). A writer with no
+     * declared root defaults to the session PRIMARY, so in a single-root session at
+     * most one child may write per batch (the rest must be read-only). Read-only
+     * children never conflict.
+     *
+     * Collects EVERY colliding root (not just the first) so the refusal names all
+     * conflicting task pairs at once — the model can fix them in one correction.
+     * The check is on DECLARED scope (tools + root), an honest over-approximation
+     * the error message is explicit about.
+     */
+    private assertDisjointWriteScopes;
     /** Map the child's AgentResult to the structured, transcript-free shape. */
     private toResult;
 }
+/** Per-spawn options: cancellation + a per-child render tag for a fan-out. */
+interface SpawnOptions {
+    /** Cooperative cancellation; threaded into `runAgent` and `ctx.signal`. */
+    signal?: AbortSignal;
+    /**
+     * A short per-child label for a parallel fan-out (JC-F), e.g. `"2/3"`, so
+     * interleaved trail notes are attributable to the child that emitted them.
+     * Undefined for a single sequential spawn — chrome is byte-identical to C.14.
+     */
+    slot?: string;
+}
+export {};

package/dist/subagent/orchestrator.js

@@ -1,8 +1,10 @@
 import path from "node:path";
 import { runAgent } from "../agent/loop.js";
-import { CruxyError, ErrorCode, messageOf, subagentDepthExceeded, } from "../errors/index.js";
+import { CruxyError, ErrorCode, messageOf, subagentDepthExceeded, subagentScopeOverlap, } from "../errors/index.js";
+import { Workspace } from "../workspace/index.js";
 import { Budget, resolveBudget } from "./budget.js";
-import { scopeRegistry } from "./registry-scope.js";
+import { scopeRegistry, SUBAGENT_WRITE_TOOLS } from "./registry-scope.js";
+import { Semaphore } from "./semaphore.js";
 import { makeSpawnSubagentTool } from "./spawn-tool.js";
 /** Longest task excerpt shown in render chrome — display, not record. */
 const LABEL_MAX = 60;
@@ -21,8 +23,25 @@ const LABEL_MAX = 60;
  */
 export class SubagentOrchestrator {
     deps;
+    /**
+     * The ONE shared bound on parallel fan-out (C.33, JC-D). Constructed once per
+     * session and reused by every {@link spawnMany} call (nested spawns reuse this
+     * same orchestrator instance), so `subagent.maxConcurrency` caps the number of
+     * concurrently-executing subagents across the WHOLE session — not per parent.
+     */
+    sem;
     constructor(deps) {
         this.deps = deps;
+        // Share the session's ONE execution semaphore when injected (C.28) so
+        // subagents and background jobs contend for the same permits; fall back to a
+        // private one at the same cap when running the orchestrator in isolation.
+        this.sem =
+            deps.executionSemaphore ??
+                new Semaphore(deps.config.subagent.maxConcurrency);
+    }
+    /** Live/queued fan-out slots (inspection/tests): proves the global cap holds. */
+    get concurrency() {
+        return { available: this.sem.available, waiting: this.sem.waiting };
     }
     /**
      * Run one subagent to completion. `parentDepth` is the spawner's depth (the
@@ -36,7 +55,7 @@ export class SubagentOrchestrator {
      * (non-interactive default-deny must reach the boundary, U.3 — a subagent is
      * not a way to swallow it).
      */
-    async spawn(spec, parentDepth) {
+    async spawn(spec, parentDepth, opts = {}) {
         const { deps } = this;
         const { maxDepth, defaultBudget } = deps.config.subagent;
         if (parentDepth >= maxDepth) {
@@ -45,33 +64,44 @@ export class SubagentOrchestrator {
         const childDepth = parentDepth + 1;
         // Scoped-down registry (throws on a tool the parent lacks — the spawn tool
         // surfaces that to the model), plus a depth-bound spawn tool only while
-        // nesting is still allowed.
+        // nesting is still allowed. (Only the SEQUENTIAL spawn is re-added; parallel
+        // fan-out stays a depth-0 capability, so a child cannot nest a fan-out.)
         const registry = scopeRegistry(deps.parentRegistry, spec.tools);
         if (childDepth < maxDepth) {
             registry.register(makeSpawnSubagentTool(this, childDepth));
         }
         const budget = new Budget(resolveBudget(defaultBudget, spec.budget));
+        // Root scoping (C.33): a `spec.root` narrows the child's cwd + confinement to
+        // that ONE root (its writes land there and nowhere else). Omitted → the full
+        // session workspace, unchanged from C.14. An unknown name fails loud here
+        // (CRUXY_E_ROOT_UNKNOWN), which the spawn tool surfaces to the model.
+        const scope = this.childScope(spec.root);
         // Fresh gate per child (own allowlist), recording what it approves so the
-        // result can name the artifacts without ever shipping the transcript.
+        // result can name the artifacts without ever shipping the transcript. The
+        // gate itself is serialized by the shared approval mutex (wired at the
+        // session factory), so concurrent siblings never prompt or checkpoint at once.
         const approve = deps.makeChildApproval();
         const artifacts = new Set();
         const ctx = {
-            cwd: deps.cwd,
-            workspace: deps.workspace,
+            cwd: scope.cwd,
+            workspace: scope.workspace,
             config: deps.config,
             logger: deps.logger,
             requestApproval: async (action) => {
                 const decision = await approve(action);
                 if (decision.allow)
-                    recordArtifacts(action, artifacts, deps.cwd);
+                    recordArtifacts(action, artifacts, scope.cwd);
                 return decision;
             },
             checkpointsActive: deps.checkpointsActive,
             sandbox: deps.sandbox,
+            signal: opts.signal,
         };
         const label = taskLabel(spec.task);
+        const tag = opts.slot; // per-child render label for a fan-out (JC-F)
+        const noun = tag ? `subagent[${tag}]` : "subagent";
         if (deps.renderer) {
-            deps.renderer.note(`${deps.renderer.theme.glyph.play} subagent: ${label}`);
+            deps.renderer.note(`${deps.renderer.theme.glyph.play} ${noun}: ${label}`);
         }
         deps.renderer?.setPhase({ kind: "subagent", label });
         // The isolation seam: a brand-new history seeded with ONLY the task. The
@@ -87,7 +117,7 @@ export class SubagentOrchestrator {
                 config: deps.config,
                 ctx,
                 renderer: deps.renderer
-                    ? new SubagentRenderer(deps.renderer, label)
+                    ? new SubagentRenderer(deps.renderer, label, tag)
                     : undefined,
                 git: deps.git,
                 projectInstructions: deps.projectInstructions,
@@ -95,6 +125,7 @@ export class SubagentOrchestrator {
                 budget,
                 router: deps.router,
                 taskClass: spec.taskClass ?? "subagent",
+                signal: opts.signal,
             });
         }
         catch (err) {
@@ -104,7 +135,7 @@ export class SubagentOrchestrator {
                 throw err;
             }
             if (deps.renderer) {
-                deps.renderer.note(`${deps.renderer.theme.glyph.failure} subagent failed: ${label}`);
+                deps.renderer.note(`${deps.renderer.theme.glyph.failure} ${noun} failed: ${label}`);
             }
             deps.renderer?.setPhase(null);
             return {
@@ -117,13 +148,140 @@ export class SubagentOrchestrator {
             };
         }
         deps.renderer?.setPhase(null);
-        const result = this.toResult(run, artifacts, label);
-        deps.logger.debug(`subagent ${result.status}: ${result.iterations} turn(s), tokens in/out ` +
+        const result = this.toResult(run, artifacts, label, noun);
+        deps.logger.debug(`${noun} ${result.status}: ${result.iterations} turn(s), tokens in/out ` +
             `${result.usage.input_tokens}/${result.usage.output_tokens} — ${label}`);
         return result;
     }
+    /**
+     * Parallel fan-out (C.33): run N children concurrently under the shared
+     * concurrency semaphore and fold their outcomes into a result array whose
+     * order MATCHES `specs` (position i is spec i's result — never completion
+     * order). A DEPTH-0 capability only (the plural tool is never granted to a
+     * child), so no permit holder ever nests a second fan-out — the semaphore
+     * stays deadlock-free.
+     *
+     * Safety before dispatch: overlapping write scope is REFUSED
+     * (`CRUXY_E_SUBAGENT_SCOPE_OVERLAP`) so two writers can never race on one root.
+     *
+     * Cancellation: children share one {@link AbortController}. A child returning a
+     * `failed`/`budget-exceeded` result is a normal PARTIAL outcome — siblings run
+     * on. But a *fatal* throw from any child (non-interactive default-deny) or an
+     * abort on `opts.signal` (Ctrl-C) aborts the controller: every sibling stops at
+     * its next turn boundary and its in-flight shell child is kill-tree'd, so the
+     * fan-out leaves no orphan. All children are awaited to settle before a fatal
+     * throw propagates — never a detached, still-running sibling.
+     */
+    async spawnMany(specs, parentDepth, opts = {}) {
+        const { maxDepth } = this.deps.config.subagent;
+        if (parentDepth >= maxDepth) {
+            throw subagentDepthExceeded(parentDepth, maxDepth);
+        }
+        if (specs.length === 0)
+            return [];
+        // Refuse overlapping write scope BEFORE any child is dispatched.
+        this.assertDisjointWriteScopes(specs);
+        const controller = new AbortController();
+        const onExternalAbort = () => controller.abort();
+        if (opts.signal) {
+            if (opts.signal.aborted)
+                controller.abort();
+            else
+                opts.signal.addEventListener("abort", onExternalAbort, { once: true });
+        }
+        const results = new Array(specs.length);
+        const total = specs.length;
+        try {
+            const settled = await Promise.allSettled(specs.map((spec, i) => this.sem.run(async () => {
+                // Already cancelled (a fatal sibling or Ctrl-C fired first): record an
+                // honest cancelled result instead of starting a doomed run.
+                if (controller.signal.aborted) {
+                    results[i] = cancelledResult();
+                    return;
+                }
+                try {
+                    results[i] = await this.spawn(spec, parentDepth, {
+                        signal: controller.signal,
+                        slot: `${i + 1}/${total}`,
+                    });
+                }
+                catch (err) {
+                    // A fatal throw (non-interactive default-deny) cancels the whole
+                    // fan-out — no sibling is left running — then propagates.
+                    controller.abort();
+                    throw err;
+                }
+            })));
+            // Any child that was aborted mid-flight (returned stop:"aborted") is folded
+            // as cancelled by toResult; a fatal throw surfaces here after all settled.
+            const fatal = settled.find((s) => s.status === "rejected");
+            if (fatal && fatal.status === "rejected")
+                throw fatal.reason;
+            // Backfill any slot a cancelled-before-dispatch child left (defensive: the
+            // sem callback always assigns, but never ship a hole as success).
+            for (let i = 0; i < results.length; i++) {
+                if (results[i] === undefined)
+                    results[i] = cancelledResult();
+            }
+            return results;
+        }
+        finally {
+            opts.signal?.removeEventListener("abort", onExternalAbort);
+        }
+    }
+    /**
+     * Resolve a child's scope from an optional root name. With a name: a
+     * single-root workspace over that root (writes confined to it) + that root's
+     * cwd. Without: the full session workspace + primary cwd (C.14 behaviour).
+     */
+    childScope(rootName) {
+        if (rootName === undefined) {
+            return { cwd: this.deps.cwd, workspace: this.deps.workspace };
+        }
+        const root = this.deps.workspace.rootByName(rootName); // fail-loud on unknown
+        return {
+            cwd: root.absPath,
+            workspace: new Workspace([
+                { name: root.name, absPath: root.absPath, primary: true },
+            ]),
+        };
+    }
+    /**
+     * Refuse a fan-out where two WRITING children (any mutating tool granted)
+     * target the same root — the disjoint-scope guarantee (C.33). A writer with no
+     * declared root defaults to the session PRIMARY, so in a single-root session at
+     * most one child may write per batch (the rest must be read-only). Read-only
+     * children never conflict.
+     *
+     * Collects EVERY colliding root (not just the first) so the refusal names all
+     * conflicting task pairs at once — the model can fix them in one correction.
+     * The check is on DECLARED scope (tools + root), an honest over-approximation
+     * the error message is explicit about.
+     */
+    assertDisjointWriteScopes(specs) {
+        const primaryName = this.deps.workspace.primary().name;
+        const byRoot = new Map(); // root → writing-child labels
+        for (const spec of specs) {
+            if (!isWriter(spec))
+                continue;
+            // Validate the named root exists (fail-loud, same as spawn) before claiming.
+            const rootName = spec.root === undefined
+                ? primaryName
+                : this.deps.workspace.rootByName(spec.root).name;
+            const claimants = byRoot.get(rootName);
+            if (claimants)
+                claimants.push(taskLabel(spec.task));
+            else
+                byRoot.set(rootName, [taskLabel(spec.task)]);
+        }
+        const conflicts = [...byRoot.entries()]
+            .filter(([, tasks]) => tasks.length > 1)
+            .map(([root, tasks]) => ({ root, tasks }));
+        if (conflicts.length > 0)
+            throw subagentScopeOverlap(conflicts);
+    }
     /** Map the child's AgentResult to the structured, transcript-free shape. */
-    toResult(run, artifacts, label) {
+    toResult(run, artifacts, label, noun) {
         const summary = lastAssistantText(run.messages);
         const base = {
             summary,
@@ -134,9 +292,21 @@ export class SubagentOrchestrator {
         if (run.stop === "completed") {
             const r = this.deps.renderer;
             if (r)
-                r.note(`${r.theme.glyph.success} subagent done: ${label}`);
+                r.note(`${r.theme.glyph.success} ${noun} done: ${label}`);
             return { status: "done", ...base };
         }
+        // Cancellation (C.33): a fatal sibling failure or Ctrl-C stopped this child
+        // at a turn boundary. An honest partial result — never a fabricated success.
+        if (run.stop === "aborted") {
+            const r = this.deps.renderer;
+            if (r)
+                r.note(`${r.theme.glyph.failure} ${noun} cancelled: ${label}`);
+            return {
+                status: "cancelled",
+                ...base,
+                error: `${ErrorCode.SubagentCancelled}: cancelled before completion`,
+            };
+        }
         // Both cap paths are the same outcome for the parent: a truncated, partial
         // result with the reason — informational, never fatal (the parent decides
         // what to do with it).
@@ -145,7 +315,7 @@ export class SubagentOrchestrator {
             : `agent.maxIterations ceiling reached (${this.deps.config.agent.maxIterations})`;
         const r = this.deps.renderer;
         if (r)
-            r.note(`${r.theme.glyph.failure} subagent stopped (budget): ${label}`);
+            r.note(`${r.theme.glyph.failure} ${noun} stopped (budget): ${label}`);
         return {
             status: "budget-exceeded",
             ...base,
@@ -158,6 +328,22 @@ function taskLabel(task) {
     const flat = task.replace(/\s+/g, " ").trim();
     return flat.length > LABEL_MAX ? flat.slice(0, LABEL_MAX - 1) + "…" : flat;
 }
+/** A child that holds any mutating tool — the disjoint-scope check's unit. A
+ * spec with no `tools` gets the default READ-ONLY set, so it is never a writer. */
+function isWriter(spec) {
+    return (spec.tools ?? []).some((t) => SUBAGENT_WRITE_TOOLS.has(t));
+}
+/** The honest result for a child cancelled before it could produce anything —
+ * used when a fatal sibling / Ctrl-C fired before this slot even dispatched. */
+function cancelledResult() {
+    return {
+        status: "cancelled",
+        summary: "",
+        error: `${ErrorCode.SubagentCancelled}: cancelled before dispatch`,
+        iterations: 0,
+        usage: { input_tokens: 0, output_tokens: 0 },
+    };
+}
 /** `artifacts` only when non-empty — absent beats `[]` in the parent's context. */
 function artifactsField(artifacts) {
     return artifacts.size > 0 ? { artifacts: [...artifacts].sort() } : {};
@@ -212,12 +398,16 @@ class SubagentRenderer {
     inner;
     label;
     prefix;
-    constructor(inner, label) {
+    constructor(inner, label, tag) {
         this.inner = inner;
         this.label = label;
         this.caps = inner.caps;
         this.theme = inner.theme;
-        this.prefix = `subagent ${inner.theme.glyph.sep} `;
+        // A fan-out child carries its slot in the prefix (`subagent[2/3] · …`) so
+        // interleaved trail notes stay attributable per-subagent (JC-F); a lone
+        // sequential spawn keeps the byte-identical C.14 `subagent · …` prefix.
+        const noun = tag ? `subagent[${tag}]` : "subagent";
+        this.prefix = `${noun} ${inner.theme.glyph.sep} `;
     }
     /** Turn framing belongs to the parent's turn — the child's is dropped. */
     beginTurn() { }

package/dist/subagent/registry-scope.d.ts

@@ -8,6 +8,19 @@ import { ToolRegistry } from "../tools/index.js";
 /** The spawn tool's registered name (excluded from every scoped child set —
  * the orchestrator re-adds a depth-bound instance only while depth allows). */
 export declare const SPAWN_SUBAGENT_TOOL_NAME = "spawn_subagent";
+/** The parallel fan-out tool's name (C.33). Stripped from every child scope:
+ * parallel fan-out is a depth-0 capability only, so a child can never obtain it
+ * (which is also what keeps the concurrency semaphore deadlock-free — no permit
+ * holder ever nests a second fan-out). A child may still spawn ONE sequential
+ * subagent via {@link SPAWN_SUBAGENT_TOOL_NAME} when depth allows. */
+export declare const SPAWN_SUBAGENTS_TOOL_NAME = "spawn_subagents";
+/**
+ * Mutating tools (C.33): a child holding ANY of these is a "writer" for the
+ * disjoint-scope check. Two writers in one parallel batch must target distinct
+ * roots, or the batch is refused pre-dispatch. Kept in sync with the gated,
+ * side-effecting tool set (file writes, shell/test, VCS).
+ */
+export declare const SUBAGENT_WRITE_TOOLS: ReadonlySet<string>;
 /**
  * The default child toolset: read-only investigation plus skills. Mirrors the
  * C.31 propose-phase set — no writes, no shell, no VCS unless the parent

package/dist/subagent/registry-scope.js

@@ -8,6 +8,28 @@ import { ToolRegistry } from "../tools/index.js";
 /** The spawn tool's registered name (excluded from every scoped child set —
  * the orchestrator re-adds a depth-bound instance only while depth allows). */
 export const SPAWN_SUBAGENT_TOOL_NAME = "spawn_subagent";
+/** The parallel fan-out tool's name (C.33). Stripped from every child scope:
+ * parallel fan-out is a depth-0 capability only, so a child can never obtain it
+ * (which is also what keeps the concurrency semaphore deadlock-free — no permit
+ * holder ever nests a second fan-out). A child may still spawn ONE sequential
+ * subagent via {@link SPAWN_SUBAGENT_TOOL_NAME} when depth allows. */
+export const SPAWN_SUBAGENTS_TOOL_NAME = "spawn_subagents";
+/**
+ * Mutating tools (C.33): a child holding ANY of these is a "writer" for the
+ * disjoint-scope check. Two writers in one parallel batch must target distinct
+ * roots, or the batch is refused pre-dispatch. Kept in sync with the gated,
+ * side-effecting tool set (file writes, shell/test, VCS).
+ */
+export const SUBAGENT_WRITE_TOOLS = new Set([
+    "write_file",
+    "edit_file",
+    "apply_patch",
+    "run_command",
+    "run_tests",
+    "git_commit",
+    "git_branch",
+    "open_pr",
+]);
 /**
  * The default child toolset: read-only investigation plus skills. Mirrors the
  * C.31 propose-phase set — no writes, no shell, no VCS unless the parent
@@ -45,14 +67,18 @@ export function scopeRegistry(parent, requested) {
         return child;
     }
     for (const name of new Set(requested)) {
-        if (name === SPAWN_SUBAGENT_TOOL_NAME)
+        // Neither spawn tool is grantable to a child: nesting (sequential) is the
+        // orchestrator's depth-capped decision, and parallel fan-out is depth-0 only.
+        if (name === SPAWN_SUBAGENT_TOOL_NAME ||
+            name === SPAWN_SUBAGENTS_TOOL_NAME) {
             continue;
+        }
         const tool = parent.get(name);
         if (!tool) {
             const available = parent
                 .list()
                 .map((t) => t.name)
-                .filter((n) => n !== SPAWN_SUBAGENT_TOOL_NAME)
+                .filter((n) => n !== SPAWN_SUBAGENT_TOOL_NAME && n !== SPAWN_SUBAGENTS_TOOL_NAME)
                 .join(", ");
             throw new Error(`tool "${name}" is not available to grant a subagent (a subagent's tools ` +
                 `must be a subset of yours). Available: ${available}`);