@cruxy/cli 0.22.1 → 0.24.0

package/dist/subagent/orchestrator.d.ts

@@ -5,6 +5,7 @@ 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 { Workspace } from "../workspace/index.js";
 import type { SubagentResult, SubagentSpec } from "./types.js";
 /**
  * Everything a spawn needs from the surrounding session, injected by the
@@ -24,6 +25,13 @@ export interface SubagentOrchestratorDeps {
     /** The parent's registry — the ceiling every child scope derives from. */
     parentRegistry: ToolRegistry;
     cwd: string;
+    /**
+     * The session's declared workspace (C.26). Threaded onto the child ctx so a
+     * subagent sees the SAME roots as the main loop — without it the child would
+     * fall back to a single-root workspace over `cwd` and its fan tools would go
+     * silently primary-only (a split-brain WITHIN one session).
+     */
+    workspace: Workspace;
     logger: ToolContext["logger"];
     git?: {
         branch: string;
@@ -45,6 +53,13 @@ export interface SubagentOrchestratorDeps {
      * one checkpoint, C.32).
      */
     makeChildApproval(): (action: ApproveAction) => Promise<ApprovalDecision>;
+    /**
+     * Whether per-root checkpointing is active for the run (C.26 step 3). Threaded
+     * onto the child ctx so a subagent's non-primary writes lift the JC-1 refusal on
+     * the SAME condition as the parent — and, because `makeChildApproval` wraps the
+     * same shared checkpoint gate, those writes join the run's one set (⚖︎JC-δ).
+     */
+    checkpointsActive?: boolean;
 }
 /**
  * Spawns subagents (C.14): the existing agent loop re-driven over isolated
@@ -61,7 +76,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
@@ -74,7 +101,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,20 @@ 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;
+        this.sem = 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 +50,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,31 +59,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,
+            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
@@ -85,7 +112,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,
@@ -93,6 +120,7 @@ export class SubagentOrchestrator {
                 budget,
                 router: deps.router,
                 taskClass: spec.taskClass ?? "subagent",
+                signal: opts.signal,
             });
         }
         catch (err) {
@@ -102,7 +130,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 {
@@ -115,13 +143,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,
@@ -132,9 +287,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).
@@ -143,7 +310,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,
@@ -156,6 +323,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() } : {};
@@ -210,12 +393,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}`);

package/dist/subagent/semaphore.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A counting semaphore (C.33): bounds how many subagent runs execute at once.
+ * FIFO — waiters are served in arrival order, so a fan-out's results stay
+ * dispatch-order-fair — and the permit is handed directly from a releaser to
+ * the next waiter, so the live count never transiently exceeds the cap.
+ *
+ * Used as the ONE shared bound on parallel fan-out. Parallel dispatch happens at
+ * depth 0 only (the `spawn_subagents` tool is never granted to a child), and a
+ * permit is held for a child's whole lifetime — including any *sequential*
+ * nested spawn beneath it, which is deliberately un-permitted. Because no permit
+ * holder ever blocks trying to acquire a second permit, the semaphore cannot be
+ * part of a wait cycle: it is deadlock-free by construction (see the C.33 design
+ * doc's deadlock argument).
+ */
+export declare class Semaphore {
+    private permits;
+    private readonly queue;
+    constructor(permits: number);
+    /** Run `fn` while holding one permit; the permit is released even if it throws. */
+    run<T>(fn: () => Promise<T>): Promise<T>;
+    /** Permits currently available (inspection/tests). */
+    get available(): number;
+    /** Callers currently blocked waiting for a permit (inspection/tests). */
+    get waiting(): number;
+    private acquire;
+    private release;
+}

package/dist/subagent/semaphore.js

@@ -0,0 +1,56 @@
+/**
+ * A counting semaphore (C.33): bounds how many subagent runs execute at once.
+ * FIFO — waiters are served in arrival order, so a fan-out's results stay
+ * dispatch-order-fair — and the permit is handed directly from a releaser to
+ * the next waiter, so the live count never transiently exceeds the cap.
+ *
+ * Used as the ONE shared bound on parallel fan-out. Parallel dispatch happens at
+ * depth 0 only (the `spawn_subagents` tool is never granted to a child), and a
+ * permit is held for a child's whole lifetime — including any *sequential*
+ * nested spawn beneath it, which is deliberately un-permitted. Because no permit
+ * holder ever blocks trying to acquire a second permit, the semaphore cannot be
+ * part of a wait cycle: it is deadlock-free by construction (see the C.33 design
+ * doc's deadlock argument).
+ */
+export class Semaphore {
+    permits;
+    queue = [];
+    constructor(permits) {
+        // A non-positive cap would wedge every run; clamp to at least 1.
+        this.permits = Math.max(1, Math.floor(permits));
+    }
+    /** Run `fn` while holding one permit; the permit is released even if it throws. */
+    async run(fn) {
+        await this.acquire();
+        try {
+            return await fn();
+        }
+        finally {
+            this.release();
+        }
+    }
+    /** Permits currently available (inspection/tests). */
+    get available() {
+        return this.permits;
+    }
+    /** Callers currently blocked waiting for a permit (inspection/tests). */
+    get waiting() {
+        return this.queue.length;
+    }
+    acquire() {
+        if (this.permits > 0) {
+            this.permits--;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => this.queue.push(resolve));
+    }
+    release() {
+        const next = this.queue.shift();
+        // Hand the permit straight to the next waiter (never bump the count above
+        // the cap); only when nobody waits does the count grow back.
+        if (next)
+            next();
+        else
+            this.permits++;
+    }
+}

package/dist/subagent/spawn-tool.d.ts

@@ -26,4 +26,61 @@ declare const parameters: z.ZodObject<{
 }>;
 /** Build a `spawn_subagent` tool bound to `orchestrator` at `depth`. */
 export declare function makeSpawnSubagentTool(orchestrator: SubagentOrchestrator, depth: number): Tool<typeof parameters>;
+declare const batchParameters: z.ZodObject<{
+    tasks: z.ZodArray<z.ZodObject<{
+        task: z.ZodString;
+        tools: z.ZodOptional<z.ZodArray<z.ZodString, "atleastone">>;
+        root: z.ZodOptional<z.ZodString>;
+        maxIterations: z.ZodOptional<z.ZodNumber>;
+        maxTokens: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        task: string;
+        root?: string | undefined;
+        maxTokens?: number | undefined;
+        maxIterations?: number | undefined;
+        tools?: [string, ...string[]] | undefined;
+    }, {
+        task: string;
+        root?: string | undefined;
+        maxTokens?: number | undefined;
+        maxIterations?: number | undefined;
+        tools?: [string, ...string[]] | undefined;
+    }>, "atleastone">;
+}, "strip", z.ZodTypeAny, {
+    tasks: [{
+        task: string;
+        root?: string | undefined;
+        maxTokens?: number | undefined;
+        maxIterations?: number | undefined;
+        tools?: [string, ...string[]] | undefined;
+    }, ...{
+        task: string;
+        root?: string | undefined;
+        maxTokens?: number | undefined;
+        maxIterations?: number | undefined;
+        tools?: [string, ...string[]] | undefined;
+    }[]];
+}, {
+    tasks: [{
+        task: string;
+        root?: string | undefined;
+        maxTokens?: number | undefined;
+        maxIterations?: number | undefined;
+        tools?: [string, ...string[]] | undefined;
+    }, ...{
+        task: string;
+        root?: string | undefined;
+        maxTokens?: number | undefined;
+        maxIterations?: number | undefined;
+        tools?: [string, ...string[]] | undefined;
+    }[]];
+}>;
+/**
+ * Build the `spawn_subagents` tool (C.33) — the PARALLEL fan-out seam, bound to
+ * `depth`. One tool call dispatches N independent, internally-sequential children
+ * concurrently (JC-A) under the shared concurrency semaphore, and returns their
+ * results IN REQUEST ORDER. A DEPTH-0 capability: it is never granted to a child,
+ * so fan-out never nests (which keeps the semaphore deadlock-free).
+ */
+export declare function makeSpawnSubagentsTool(orchestrator: SubagentOrchestrator, depth: number): Tool<typeof batchParameters>;
 export {};