@cruxy/cli 0.22.1 → 0.24.0

package/dist/subagent/spawn-tool.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { CruxyError, ErrorCode } from "../errors/index.js";
-import { SPAWN_SUBAGENT_TOOL_NAME } from "./registry-scope.js";
+import { SPAWN_SUBAGENT_TOOL_NAME, SPAWN_SUBAGENTS_TOOL_NAME, } from "./registry-scope.js";
 /**
  * The `spawn_subagent` tool (C.14): the parent-facing seam for delegation. A
  * normal tool on the same loop as everything else — no hidden control flow.
@@ -34,9 +34,9 @@ const parameters = z.object({
         .optional()
         .describe("Cap on the subagent's total tokens (clamped to the configured ceiling)."),
 });
-/** The compact wire shape fed back to the parent model. */
-function renderResult(result) {
-    return JSON.stringify({
+/** The compact, transcript-free object fed back to the parent model. */
+function resultPayload(result) {
+    return {
         status: result.status,
         summary: result.summary,
         ...(result.artifacts ? { artifacts: result.artifacts } : {}),
@@ -46,7 +46,18 @@ function renderResult(result) {
             input: result.usage.input_tokens,
             output: result.usage.output_tokens,
         },
-    });
+    };
+}
+/** The compact wire shape fed back to the parent model. */
+function renderResult(result) {
+    return JSON.stringify(resultPayload(result));
+}
+/** A coded, actionable tool-error string for an error the MODEL should correct
+ * (scope overlap, depth exceeded, tool scoping) — never the raw stack. */
+function toolErrorMessage(err) {
+    return CruxyError.is(err)
+        ? `${err.code}: ${err.title}${err.cause ? ` — ${err.cause}` : ""}`
+        : err.message;
 }
 /** Build a `spawn_subagent` tool bound to `orchestrator` at `depth`. */
 export function makeSpawnSubagentTool(orchestrator, depth) {
@@ -79,10 +90,7 @@ export function makeSpawnSubagentTool(orchestrator, depth) {
                 }
                 // Depth-exceed and scope violations are the model's to correct: feed
                 // the coded, actionable message back as a tool error.
-                const message = CruxyError.is(err)
-                    ? `${err.code}: ${err.title}${err.cause ? ` — ${err.cause}` : ""}`
-                    : err.message;
-                return { ok: false, error: message };
+                return { ok: false, error: toolErrorMessage(err) };
             }
             // A failed child is an is_error result (strong signal), still structured;
             // budget-exceeded is informational — a partial result, not an error.
@@ -92,3 +100,90 @@ export function makeSpawnSubagentTool(orchestrator, depth) {
         },
     };
 }
+// ── parallel fan-out (C.33) ───────────────────────────────────────────────────
+/** One child's spec inside a `spawn_subagents` batch. Mirrors the singular
+ * tool's shape plus `root` — the C.33 disjoint-scope unit. */
+const batchChild = z.object({
+    task: z
+        .string()
+        .min(1)
+        .describe("The complete, self-contained subtask. The subagent starts with NO context " +
+        "beyond this text — include every path, constraint, and expected output."),
+    tools: z
+        .array(z.string().min(1))
+        .nonempty()
+        .optional()
+        .describe("Tool names to grant this child — a subset of your own. Omit for read-only. " +
+        "Two children that both hold write/shell tools MUST target different `root`s."),
+    root: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Workspace root name (from your Environment) to scope this child to: its " +
+        "writes are confined there. Required to make two writing children disjoint; " +
+        "omit for read-only children or a single-root workspace."),
+    maxIterations: z.number().int().positive().optional(),
+    maxTokens: z.number().int().positive().optional(),
+});
+const batchParameters = z.object({
+    tasks: z
+        .array(batchChild)
+        .nonempty()
+        .describe("The independent subtasks to run CONCURRENTLY. Results come back in this " +
+        "same order. Bounded by subagent.maxConcurrency; excess children queue."),
+});
+/** Map a validated batch child to a {@link SubagentSpec}. */
+function toSpec(child) {
+    const budget = {
+        ...(child.maxIterations !== undefined
+            ? { maxIterations: child.maxIterations }
+            : {}),
+        ...(child.maxTokens !== undefined ? { maxTokens: child.maxTokens } : {}),
+    };
+    return {
+        task: child.task,
+        ...(child.tools ? { tools: child.tools } : {}),
+        ...(child.root !== undefined ? { root: child.root } : {}),
+        budget,
+    };
+}
+/**
+ * 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 function makeSpawnSubagentsTool(orchestrator, depth) {
+    return {
+        name: SPAWN_SUBAGENTS_TOOL_NAME,
+        description: "Delegate SEVERAL independent subtasks to scoped subagents that run in PARALLEL, " +
+            "each with its own fresh context, restricted toolset, and hard budget. Returns a " +
+            "structured result per child, in the same order as `tasks` — transcripts discarded. " +
+            "Use when subtasks don't depend on each other (e.g. investigate N areas at once). " +
+            "For children that WRITE, give each a distinct `root`; overlapping write scope is " +
+            "refused. For a single subtask, use spawn_subagent instead.",
+        parameters: batchParameters,
+        async execute(input) {
+            let results;
+            try {
+                results = await orchestrator.spawnMany(input.tasks.map(toSpec), depth);
+            }
+            catch (err) {
+                // Non-interactive default-deny propagates to the boundary (U.3).
+                if (CruxyError.is(err) && err.code === ErrorCode.ApprovalRequired) {
+                    throw err;
+                }
+                // Scope overlap / depth-exceed are the model's to correct — coded error.
+                return { ok: false, error: toolErrorMessage(err) };
+            }
+            // Partial results are honest, not an error: the array carries each child's
+            // own status (done / failed / budget-exceeded / cancelled). The batch call
+            // succeeds as long as it was dispatched — the parent reasons over the mix.
+            return {
+                ok: true,
+                output: JSON.stringify(results.map(resultPayload)),
+            };
+        },
+    };
+}

package/dist/subagent/types.d.ts

@@ -7,8 +7,13 @@ import type { TaskClass } from "../routing/index.js";
  * result and discards its transcript. The parent reasons over the result only;
  * context isolation is the whole point.
  */
-/** Why a subagent run ended. Every path returns a result — never a hang. */
-export type SubagentStatus = "done" | "budget-exceeded" | "failed";
+/**
+ * Why a subagent run ended. Every path returns a result — never a hang.
+ * `cancelled` (C.33) is a parallel-fan-out outcome: a fatal sibling failure or
+ * Ctrl-C aborted this child before it finished — recorded honestly, never
+ * dressed up as `done`.
+ */
+export type SubagentStatus = "done" | "budget-exceeded" | "failed" | "cancelled";
 /**
  * Hard caps a subagent runs under. `maxIterations` and `maxTokens` are always
  * finite — a subagent is bounded by construction; `timeoutMs` is an optional
@@ -41,6 +46,16 @@ export interface SubagentSpec {
      * declaration at the spawn call site — not something the router guesses.
      */
     taskClass?: TaskClass;
+    /**
+     * The workspace root (by exact name, C.26) this child is scoped to (C.33).
+     * When set, the child's cwd and confinement narrow to that ONE root, so its
+     * writes land there and nowhere else — the unit of the parallel fan-out's
+     * disjoint-scope guarantee: two writing children must name distinct roots or
+     * the batch is refused pre-dispatch. Omitted → the child inherits the full
+     * session workspace (read-only fan-out, or a single-root session), unchanged
+     * from C.14.
+     */
+    root?: string;
 }
 /**
  * What the parent gets back — compact structured data, never the transcript.

package/dist/testing/run-tests-tool.js

@@ -97,6 +97,9 @@ export function makeRunTestsTool(deps = {}) {
             const decision = await ctx.requestApproval({
                 kind: "test",
                 command: resolved.command,
+                // C.26 attribution seam (JC-β): primary root name for Steps 4/5. Tests are
+                // primary-only this release; the gate hard-attributes to the primary.
+                root: ctx.workspace.primary().name,
             });
             if (!decision.allow) {
                 return {

package/dist/tools/create-pull-request.d.ts

@@ -8,14 +8,17 @@ import type { Tool } from "./types.js";
  * never prompted for or stored.
  */
 declare const parameters: z.ZodObject<{
+    root: z.ZodOptional<z.ZodString>;
     title: z.ZodOptional<z.ZodString>;
     body: z.ZodOptional<z.ZodString>;
     base: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
+    root?: string | undefined;
     body?: string | undefined;
     base?: string | undefined;
     title?: string | undefined;
 }, {
+    root?: string | undefined;
     body?: string | undefined;
     base?: string | undefined;
     title?: string | undefined;

package/dist/tools/create-pull-request.js

@@ -1,6 +1,8 @@
+import path from "node:path";
 import { z } from "zod";
-import { CruxyError, ErrorCode } from "../errors/index.js";
-import { createForgeProvider, createPrService, fillContent, loadCommitGuidance, resolveForgeToken, } from "../vcs/index.js";
+import { CruxyError, ErrorCode, vcsCrossRoot } from "../errors/index.js";
+import { createForgeProvider, createPrService, fillContent, gitToplevel, loadCommitGuidance, resolveForgeToken, } from "../vcs/index.js";
+import { contextWorkspace, resolveMutationRoot } from "./file/paths.js";
 /**
  * Open a pull request from the agent's work (C.15): branch → conventional commit
  * → push → open PR, all behind the one U.3 approval. The model authors `title`
@@ -9,6 +11,12 @@ import { createForgeProvider, createPrService, fillContent, loadCommitGuidance,
  * never prompted for or stored.
  */
 const parameters = z.object({
+    root: z
+        .string()
+        .optional()
+        .describe("Workspace root to open the pull request for, by its declared name. Required " +
+        "when the session declares more than one root (a PR targets exactly one " +
+        "repository, so it must not be guessed); optional in a single-root session."),
     title: z
         .string()
         .optional()
@@ -31,11 +39,18 @@ export const createPullRequestTool = {
     parameters,
     async execute(input, ctx) {
         try {
+            // ⚖︎#11 / JC-1: commit to exactly one root first. Multi-root with no `root`
+            // refuses (ROOT_AMBIGUOUS) BEFORE any git runs; single-root defaults to the
+            // primary (byte-identical to pre-C.26). A cross-root PR (a sibling root in the
+            // same repo) is refused too — a PR is a single-repo artifact (JC-3).
+            const selected = resolveMutationRoot(ctx, { root: input.root }, "a pull request");
+            assertSingleRepoRoot(contextWorkspace(ctx), selected);
             const token = resolveForgeToken();
             const forge = createForgeProvider(token);
-            const guidance = await loadCommitGuidance(ctx.cwd);
+            const guidance = await loadCommitGuidance(selected.absPath);
             const service = createPrService({
-                cwd: ctx.cwd,
+                cwd: selected.absPath,
+                rootName: selected.name,
                 config: ctx.config,
                 forge,
                 requestApproval: ctx.requestApproval,
@@ -75,6 +90,37 @@ export const createPullRequestTool = {
         }
     },
 };
+/**
+ * Refuse a PR whose selected root shares one git working tree with a SIBLING
+ * declared root (JC-3). Filesystem-overlap refusal (ROOT_OVERLAP) only catches
+ * nesting; two non-overlapping roots — `packages/a` and `packages/b` under one
+ * `.git` — pass that check yet still share a repo. Committing in one would
+ * `git add -A` the other's changes, so the PR would span both. We detect it by
+ * comparing git top-levels: same top-level ⇒ same repo ⇒ refuse (naming both).
+ *
+ * If the selected root is not in a git repo, there is nothing to compare — the PR
+ * flow fails loudly later at `getRepoInfo`/`currentBranch`. Read-only `rev-parse`
+ * only; this runs after selection, so a no-root multi-root call still spawns zero
+ * git before its ROOT_AMBIGUOUS refusal.
+ */
+function assertSingleRepoRoot(ws, selected) {
+    if (!ws.isMultiRoot)
+        return;
+    const topSelected = gitToplevel(selected.absPath);
+    if (topSelected === null)
+        return;
+    const canonical = path.resolve(topSelected);
+    for (const sibling of ws.roots()) {
+        if (sibling.name === selected.name)
+            continue;
+        const topSibling = gitToplevel(sibling.absPath);
+        if (topSibling === null)
+            continue;
+        if (path.resolve(topSibling) === canonical) {
+            throw vcsCrossRoot(selected.name, sibling.name, canonical);
+        }
+    }
+}
 /** One-line, model-readable rendering of a coded error + its next steps. */
 function formatCoded(err) {
     const head = err.cause ? `${err.title} — ${err.cause}` : err.title;

package/dist/tools/file/apply-patch.js

@@ -1,7 +1,7 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { z } from "zod";
-import { resolveInRoot } from "./paths.js";
+import { resolveToolPath } from "./paths.js";
 import { countOccurrences } from "./edit-file.js";
 /** How many leading lines of a created file the approval preview shows. */
 const PREVIEW_LINES = 20;
@@ -62,7 +62,7 @@ export const applyPatchTool = {
             const op = input.operations[i];
             let abs;
             try {
-                abs = await resolveInRoot(ctx, op.path);
+                ({ abs } = await resolveToolPath(ctx, { path: op.path }, { deferNonPrimaryWrite: true }));
             }
             catch (err) {
                 return { ok: false, error: opError(i, op, err.message) };

package/dist/tools/file/edit-file.js

@@ -1,6 +1,6 @@
 import { promises as fs } from "node:fs";
 import { z } from "zod";
-import { resolveInRoot } from "./paths.js";
+import { resolveToolPath } from "./paths.js";
 /** Count non-overlapping exact occurrences of `needle` in `haystack`. */
 export function countOccurrences(haystack, needle) {
     let count = 0;
@@ -32,7 +32,7 @@ export const editFileTool = {
     async execute(input, ctx) {
         let abs;
         try {
-            abs = await resolveInRoot(ctx, input.path);
+            ({ abs } = await resolveToolPath(ctx, { path: input.path }, { deferNonPrimaryWrite: true }));
         }
         catch (err) {
             return { ok: false, error: err.message };

package/dist/tools/file/glob.d.ts

@@ -1,10 +1,17 @@
 import { z } from "zod";
 import type { Tool } from "../types.js";
 /**
- * Find files by glob pattern within the project root. Read-only — no approval.
- * The pattern is constrained to the root (no absolute or `..` patterns) so glob
+ * Find files by glob pattern within the workspace. Read-only — no approval.
+ * The pattern is constrained to a root (no absolute or `..` patterns) so glob
  * can't reach outside, consistent with the other file tools.
+ *
+ * Multi-repo (C.26, Funnel B): with more than one declared root, glob fans every
+ * root — an independent walk rooted at each root's own `absPath` — and labels each
+ * match `‹root› ▸ path`. There is no path to confine here; the boundary is which
+ * root's `absPath` each walk starts from, so a match can only ever come from the
+ * root its label names. A `root` argument scopes the walk to that one root.
  */
 export declare const globTool: Tool<z.ZodObject<{
     pattern: z.ZodString;
+    root: z.ZodOptional<z.ZodString>;
 }>>;

package/dist/tools/file/glob.js

@@ -1,13 +1,19 @@
-import path from "node:path";
 import { glob } from "tinyglobby";
 import { z } from "zod";
+import { contextWorkspace, isEscapingPattern, labelPath, resolveReadRoots, } from "./paths.js";
 /** Cap on returned paths — beyond this we truncate with a notice. */
 const MAX_RESULTS = 200;
 const DEFAULT_IGNORE = ["**/node_modules/**", "**/.git/**"];
 /**
- * Find files by glob pattern within the project root. Read-only — no approval.
- * The pattern is constrained to the root (no absolute or `..` patterns) so glob
+ * Find files by glob pattern within the workspace. Read-only — no approval.
+ * The pattern is constrained to a root (no absolute or `..` patterns) so glob
  * can't reach outside, consistent with the other file tools.
+ *
+ * Multi-repo (C.26, Funnel B): with more than one declared root, glob fans every
+ * root — an independent walk rooted at each root's own `absPath` — and labels each
+ * match `‹root› ▸ path`. There is no path to confine here; the boundary is which
+ * root's `absPath` each walk starts from, so a match can only ever come from the
+ * root its label names. A `root` argument scopes the walk to that one root.
  */
 export const globTool = {
     name: "glob",
@@ -16,37 +22,85 @@ export const globTool = {
         pattern: z
             .string()
             .describe("Glob pattern, relative to the project root (e.g. 'src/**/*.ts')."),
+        root: z
+            .string()
+            .optional()
+            .describe("In a multi-repo session, restrict the search to a single declared root by name. Omit to search every root and label each match with its root."),
     }),
     async execute(input, ctx) {
         const pattern = input.pattern;
-        if (path.isAbsolute(pattern) || pattern.split(/[/\\]/).includes("..")) {
+        // Walk-rooted tool: the pattern is not a resolvable path, so confinement is
+        // (a) rejecting a pattern that could escape (shared with grep_files) and
+        // (b) rooting each walk at a declared root's absPath, never a bare ctx.cwd.
+        if (isEscapingPattern(pattern)) {
             return {
                 ok: false,
                 error: "pattern must be relative to the project root (no '..' or absolute paths)",
             };
         }
+        const ws = contextWorkspace(ctx);
+        let roots;
+        try {
+            roots = resolveReadRoots(ctx, { root: input.root });
+        }
+        catch (err) {
+            return { ok: false, error: err.message };
+        }
         try {
-            const matches = await glob(pattern, {
-                cwd: path.resolve(ctx.cwd),
-                ignore: DEFAULT_IGNORE,
-                onlyFiles: true,
-                dot: false,
-            });
-            matches.sort();
-            if (matches.length === 0) {
+            // Fan: one independent walk per root; each match is attributed to (and, in
+            // multi-root, labelled with) the root whose absPath produced it.
+            const rows = [];
+            const totalByRoot = new Map();
+            for (const root of roots) {
+                const matches = await glob(pattern, {
+                    cwd: root.absPath,
+                    ignore: DEFAULT_IGNORE,
+                    onlyFiles: true,
+                    dot: false,
+                });
+                matches.sort();
+                totalByRoot.set(root.name, matches.length);
+                for (const m of matches) {
+                    rows.push({
+                        root: root.name,
+                        line: labelPath(root, m, ws.isMultiRoot),
+                    });
+                }
+            }
+            if (rows.length === 0) {
                 return { ok: true, output: "(no matches)" };
             }
-            if (matches.length > MAX_RESULTS) {
-                const shown = matches.slice(0, MAX_RESULTS).join("\n");
-                return {
-                    ok: true,
-                    output: `${shown}\n\n[truncated: showing ${MAX_RESULTS} of ${matches.length} matches]`,
-                };
+            if (rows.length > MAX_RESULTS) {
+                const shownRows = rows.slice(0, MAX_RESULTS);
+                const shown = shownRows.map((r) => r.line).join("\n");
+                const footer = ws.isMultiRoot
+                    ? truncationFooter(rows.length, shownRows, totalByRoot)
+                    : `[truncated: showing ${MAX_RESULTS} of ${rows.length} matches]`;
+                return { ok: true, output: `${shown}\n\n${footer}` };
             }
-            return { ok: true, output: matches.join("\n") };
+            return { ok: true, output: rows.map((r) => r.line).join("\n") };
         }
         catch (err) {
             return { ok: false, error: err.message };
         }
     },
 };
+/**
+ * Truncation footer for a fanned walk: the overall count plus a per-root note for
+ * every root whose matches the cap dropped — so a root cut off by the cap is
+ * named, never silently read as having no files.
+ */
+function truncationFooter(total, shownRows, totalByRoot) {
+    const shownByRoot = new Map();
+    for (const r of shownRows) {
+        shownByRoot.set(r.root, (shownByRoot.get(r.root) ?? 0) + 1);
+    }
+    const lines = [`[truncated: showing ${MAX_RESULTS} of ${total} matches]`];
+    for (const [name, count] of totalByRoot) {
+        const dropped = count - (shownByRoot.get(name) ?? 0);
+        if (dropped > 0) {
+            lines.push(`— ${name}: ${dropped} more not shown`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/tools/file/grep-files.d.ts

@@ -6,27 +6,37 @@ declare const parameters: z.ZodObject<{
     glob: z.ZodOptional<z.ZodString>;
     ignoreCase: z.ZodOptional<z.ZodBoolean>;
     maxResults: z.ZodOptional<z.ZodNumber>;
+    root: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     pattern: string;
     path?: string | undefined;
+    root?: string | undefined;
     maxResults?: number | undefined;
     glob?: string | undefined;
     ignoreCase?: boolean | undefined;
 }, {
     pattern: string;
     path?: string | undefined;
+    root?: string | undefined;
     maxResults?: number | undefined;
     glob?: string | undefined;
     ignoreCase?: boolean | undefined;
 }>;
 /**
- * Search file *contents* for a regex within the project root. Read-only — no
+ * Search file *contents* for a regex within the workspace. Read-only — no
  * approval — so the model should prefer this over shelling out to grep/rg via
  * run_command (which is platform-dependent and routes through the approval gate).
  *
  * Files are enumerated with the same glob mechanism as the `glob` tool (so
  * node_modules and .git are always ignored), binary files are skipped, and the
- * search is bounded by the project-root path boundary shared by every file tool.
+ * search is bounded by the same root boundary as every file tool.
+ *
+ * Multi-repo (C.26, Funnel B): with more than one declared root and no root-
+ * selecting argument, the search FANS every root — a bare relative `path` is
+ * applied under each root (⚖︎JC-6) — and labels each match `‹root› ▸ path`. A
+ * `root` argument, or an absolute / `‹root›/…`-prefixed `path`, scopes it to that
+ * one root. Each walk starts at exactly one confined root directory, so a match
+ * can only come from the root its label names.
  */
 export declare const grepFilesTool: Tool<typeof parameters>;
 export {};