@cruxy/cli 0.22.0 → 0.23.0

package/dist/tools/file/grep-files.js

@@ -2,7 +2,8 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { glob } from "tinyglobby";
 import { z } from "zod";
-import { resolveInRoot } from "./paths.js";
+import { confineToRoot } from "../../workspace/index.js";
+import { contextWorkspace, isEscapingPattern, labelPath, resolveToolPath, } from "./paths.js";
 /** Default cap on returned match lines; beyond it we report the overflow. */
 const DEFAULT_MAX_RESULTS = 100;
 /** Trim point for a single matched line so long lines don't flood the output. */
@@ -32,15 +33,31 @@ const parameters = z.object({
         .positive()
         .optional()
         .describe(`Maximum number of matching lines to return (default ${DEFAULT_MAX_RESULTS}).`),
+    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 (a relative `path` is applied under each) and label each match with its root."),
 });
+/** True when `p`'s first segment names a declared root (a `‹root›/rest` selector). */
+function firstSegmentIsRoot(ws, p) {
+    const seg = p.split(/[/\\]/, 1)[0];
+    return seg.length > 0 && seg !== p && ws.tryRootByName(seg) !== 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 const grepFilesTool = {
     name: "grep_files",
@@ -55,59 +72,117 @@ export const grepFilesTool = {
         catch (err) {
             return { ok: false, error: `invalid regex: ${err.message}` };
         }
-        const root = path.resolve(ctx.cwd);
-        let scope;
+        // The `glob` filter is not a resolvable path, so — like the glob tool — it is
+        // confined by rejecting a pattern that could walk outside the scope (G2).
+        if (input.glob && isEscapingPattern(input.glob)) {
+            return {
+                ok: false,
+                error: "glob must be relative to the search scope (no '..' or absolute paths)",
+            };
+        }
+        const ws = contextWorkspace(ctx);
+        let targets;
         try {
-            scope = input.path ? await resolveInRoot(ctx, input.path) : root;
+            if (input.root || !ws.isMultiRoot) {
+                // Explicit named root, or a single-root session: confine the path within
+                // that one root exactly as the pre-C.26 tool did (byte-identical output).
+                const { root, abs } = await resolveToolPath(ctx, {
+                    root: input.root,
+                    path: input.path ?? ".",
+                });
+                targets = [{ root, scope: abs }];
+            }
+            else if (input.path &&
+                (path.isAbsolute(input.path) || firstSegmentIsRoot(ws, input.path))) {
+                // A `path` that itself points into / names one root selects that root.
+                const { root, abs } = await resolveToolPath(ctx, { path: input.path });
+                targets = [{ root, scope: abs }];
+            }
+            else {
+                // Fan: apply the bare-relative `path` (or none) under EACH root (⚖︎JC-6).
+                targets = await Promise.all(ws.roots().map(async (root) => ({
+                    root,
+                    scope: input.path
+                        ? await confineToRoot(root.absPath, input.path)
+                        : root.absPath,
+                })));
+            }
         }
         catch (err) {
             return { ok: false, error: err.message };
         }
         const maxResults = input.maxResults ?? DEFAULT_MAX_RESULTS;
         try {
-            const files = await glob(input.glob ?? "**/*", {
-                cwd: scope,
-                ignore: DEFAULT_IGNORE,
-                onlyFiles: true,
-                dot: false,
-            });
-            files.sort();
-            const lines = [];
+            const rows = []; // shown (capped) lines
             let total = 0; // total matches found, including those past the cap
-            for (const rel of files) {
-                const abs = path.join(scope, rel);
-                const buf = await fs.readFile(abs);
-                if (buf.subarray(0, BINARY_SNIFF_BYTES).includes(0))
-                    continue; // binary
-                const display = path.relative(root, abs);
-                const fileLines = buf.toString("utf8").split("\n");
-                for (let i = 0; i < fileLines.length; i++) {
-                    if (!regex.test(fileLines[i]))
-                        continue;
-                    total++;
-                    if (lines.length < maxResults) {
-                        let text = fileLines[i].trim();
-                        if (text.length > MAX_LINE_LENGTH) {
-                            text = `${text.slice(0, MAX_LINE_LENGTH)}…`;
+            const totalByRoot = new Map();
+            for (const target of targets) {
+                const files = await glob(input.glob ?? "**/*", {
+                    cwd: target.scope,
+                    ignore: DEFAULT_IGNORE,
+                    onlyFiles: true,
+                    dot: false,
+                });
+                files.sort();
+                for (const rel of files) {
+                    const abs = path.join(target.scope, rel);
+                    const buf = await fs.readFile(abs);
+                    if (buf.subarray(0, BINARY_SNIFF_BYTES).includes(0))
+                        continue; // binary
+                    const display = labelPath(target.root, path.relative(target.root.absPath, abs), ws.isMultiRoot);
+                    const fileLines = buf.toString("utf8").split("\n");
+                    for (let i = 0; i < fileLines.length; i++) {
+                        if (!regex.test(fileLines[i]))
+                            continue;
+                        total++;
+                        totalByRoot.set(target.root.name, (totalByRoot.get(target.root.name) ?? 0) + 1);
+                        if (rows.length < maxResults) {
+                            let text = fileLines[i].trim();
+                            if (text.length > MAX_LINE_LENGTH) {
+                                text = `${text.slice(0, MAX_LINE_LENGTH)}…`;
+                            }
+                            rows.push({
+                                root: target.root.name,
+                                line: `${display}:${i + 1}: ${text}`,
+                            });
                         }
-                        lines.push(`${display}:${i + 1}: ${text}`);
                     }
                 }
             }
             if (total === 0) {
                 return { ok: true, output: "(no matches)" };
             }
-            const omitted = total - lines.length;
-            const body = lines.join("\n");
-            return {
-                ok: true,
-                output: omitted > 0
-                    ? `${body}\n\n[${omitted} more match${omitted === 1 ? "" : "es"} omitted]`
-                    : body,
-            };
+            const omitted = total - rows.length;
+            const body = rows.map((r) => r.line).join("\n");
+            if (omitted === 0) {
+                return { ok: true, output: body };
+            }
+            const footer = ws.isMultiRoot
+                ? grepTruncationFooter(omitted, rows, totalByRoot)
+                : `[${omitted} more match${omitted === 1 ? "" : "es"} omitted]`;
+            return { ok: true, output: `${body}\n\n${footer}` };
         }
         catch (err) {
             return { ok: false, error: err.message };
         }
     },
 };
+/**
+ * Truncation footer for a fanned grep: the overall overflow 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 matches.
+ */
+function grepTruncationFooter(omitted, shownRows, totalByRoot) {
+    const shownByRoot = new Map();
+    for (const r of shownRows) {
+        shownByRoot.set(r.root, (shownByRoot.get(r.root) ?? 0) + 1);
+    }
+    const lines = [`[${omitted} more match${omitted === 1 ? "" : "es"} omitted]`];
+    for (const [name, count] of totalByRoot) {
+        const dropped = count - (shownByRoot.get(name) ?? 0);
+        if (dropped > 0) {
+            lines.push(`— ${name}: ${dropped} more omitted`);
+        }
+    }
+    return lines.join("\n");
+}

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

@@ -1,26 +1,132 @@
-import { CruxyError } from "../../errors/index.js";
+import { PathEscapeError, type DeclaredRoot, type RootRef, type Workspace } from "../../workspace/index.js";
 import type { ToolContext } from "../types.js";
 /**
- * Thrown when a tool argument resolves to a path outside the project root —
- * whether via `../` traversal, an absolute path, or a symlink pointing outward.
- * A {@link CruxyError} (code CRUXY_E_PATH_ESCAPE) so it carries a code if it
- * reaches the boundary; tools still catch it and surface `{ ok:false }`.
+ * Path confinement for file tools (C.26). The confinement kernel itself lives in
+ * `src/workspace` ({@link confineToRoot}); this module is the tool-facing funnel
+ * that every path-taking tool calls instead of touching the filesystem directly.
+ * Keeping ONE resolver here is what makes Funnel A ("a path tool cannot reach fs
+ * outside the selected root") a structural property rather than a per-tool habit.
  */
-export declare class PathEscapeError extends CruxyError {
-    constructor(message: string);
-}
+export { PathEscapeError };
 /**
- * Resolve a tool-supplied path against the project root (`ctx.cwd`) and prove it
- * stays inside — the single security boundary every file tool funnels through.
+ * The workspace this context acts in. Runtime always sets `ctx.workspace`; the
+ * fallback to a trivial single-root workspace over `ctx.cwd` exists only for the
+ * many test contexts (and any not-yet-migrated caller) that don't set one. The
+ * fallback is byte-identical to the legacy single-root behaviour by construction:
+ * its one root's `absPath` is `path.resolve(ctx.cwd)`, the same root the old
+ * `resolveInRoot` confined to.
+ */
+export declare function contextWorkspace(ctx: ToolContext): Workspace;
+/**
+ * Resolve a tool-supplied path against the workspace and prove it stays inside the
+ * one root it selects — the single funnel for every path-taking file tool.
+ *
+ * Single-root sessions short-circuit straight to `confineToRoot(primary, path)`,
+ * which is exactly the legacy `resolveInRoot` behaviour (same result, same
+ * error type + message for every case: relative, absolute-inside, absolute-outside,
+ * outward symlink). Multi-root sessions run the two-step select-then-confine:
+ * {@link selectRoot} commits to exactly one declared root FIRST, then
+ * {@link confineToRoot} validates against only that root — so a `../otherRoot/x`
+ * that lands in a sibling is refused as an ordinary `PATH_ESCAPE` (R2), never
+ * rebound to the sibling.
  *
- * Two layers: (1) a lexical check that the resolved absolute path is within root
- * (rejects `../` and absolute-outside before touching the FS); (2) a symlink
- * check that the real target — or, for a new path, its nearest existing parent —
- * resolves inside the *real* root. The root is realpath'd too, so this is correct
- * even when the root itself sits under a symlink (e.g. macOS `/var → /private/var`).
+ * `deferNonPrimaryWrite` (set by the mutating file tools) refuses a write whose
+ * selected root is NOT the primary in a multi-root session, with
+ * `CRUXY_E_MULTIROOT_WRITE_DEFERRED` — UNLESS `ctx.checkpointsActive` is true.
+ * That flag is the C.26 step-3 coupling: it is set exactly when a per-root
+ * checkpoint gate is wired, which captures the write (snapshots its root) before
+ * it reaches disk — so the refusal lifts precisely when the write becomes
+ * rollback-able, never before (not step-wide, not lift-then-verify). With
+ * checkpoints disabled the flag is false, so a non-primary write is still refused
+ * rather than left un-restorable (⚖︎JC-γ: the opt-out covers the user's own cwd,
+ * not every declared sibling). It is a no-op in single-root (there is only the
+ * primary) and for reads (which never set it). The refusal is raised BEFORE any
+ * filesystem access.
+ *
+ * @throws {PathEscapeError} if the path escapes the selected root.
+ * @throws {CruxyError} CRUXY_E_ROOT_UNKNOWN / CRUXY_E_ROOT_AMBIGUOUS on bad selection,
+ *   or CRUXY_E_MULTIROOT_WRITE_DEFERRED on a non-primary write while deferred.
+ */
+export declare function resolveToolPath(ctx: ToolContext, ref: RootRef, opts?: {
+    requireExplicit?: boolean;
+    deferNonPrimaryWrite?: boolean;
+}): Promise<{
+    root: DeclaredRoot;
+    abs: string;
+}>;
+/**
+ * Legacy single-root entry point, retained as a thin shim over
+ * {@link resolveToolPath} so callers that pass only a bare path (e.g. the LSP
+ * tools) keep working and stay byte-identical. New path tools should call
+ * {@link resolveToolPath} so they can carry an explicit root selector.
  *
- * @returns the resolved absolute path (lexical, not realpath'd — so callers
- *   operate on the intended location).
+ * @returns the resolved absolute path (lexical, not realpath'd).
  * @throws {PathEscapeError} if the path escapes the root.
  */
 export declare function resolveInRoot(ctx: ToolContext, p: string): Promise<string>;
+/**
+ * True when a glob pattern could walk outside its root — an absolute pattern or one
+ * containing a `..` segment. The ONE implementation of "does this pattern escape",
+ * shared by `glob` and `grep_files` so the two walk-rooted tools cannot diverge
+ * (closing G1/G2). Path *arguments* go through {@link resolveToolPath}; glob
+ * *patterns* are not resolvable paths, so this predicate guards the walk instead.
+ */
+export declare function isEscapingPattern(pattern: string): boolean;
+/**
+ * The separator between a root's name and a path within it (`‹root› ▸ rel`) — one
+ * constant so every no-path tool that fans across roots renders the same label.
+ */
+export declare const ROOT_LABEL_SEP = " \u25B8 ";
+/**
+ * Prefix a root-relative path with its root name — but ONLY in a genuine
+ * multi-root session. In single-root the label is dropped so output stays
+ * byte-identical with the pre-C.26 tools. The `root`/`rel` pair always comes from
+ * the same fan iteration that produced the bytes, so a rendered label can never
+ * point at a different root than the one that was walked (the honesty pin).
+ */
+export declare function labelPath(root: DeclaredRoot, rel: string, isMultiRoot: boolean): string;
+/** As {@link labelPath} but from a bare root name (for hits that carry only a name). */
+export declare function labelName(rootName: string, rel: string): string;
+/**
+ * The Funnel-B selector for **no-path** tools (`glob`, `grep_files`, `list_files`,
+ * `git_status`, `search_codebase`) — the counterpart to {@link resolveToolPath}.
+ * A no-path tool has no path to confine; its boundary is *which root's `absPath`*
+ * it threads as the walk-start / index-key / spawn-cwd. This returns that root
+ * set, and the tool commits to exactly one root per read by iterating it:
+ *
+ *   - an explicit `root` name → that one declared root (fail-loud on unknown, R1);
+ *   - single-root session → the primary root (so output is byte-identical);
+ *   - multi-root, unscoped → **fan** every declared root.
+ *
+ * The fan is N independent single-root reads (one `root.absPath` each), never one
+ * walk over a union — so each read is Funnel-B-confined and the cross-root merge
+ * only ever happens on already-attributed *results*, never on the filesystem.
+ * Reads leave `requireExplicit` false (that gate is for mutations, ⚖︎#3).
+ *
+ * @throws {CruxyError} CRUXY_E_ROOT_UNKNOWN if a named root is not declared.
+ */
+export declare function resolveReadRoots(ctx: ToolContext, ref?: {
+    root?: string;
+}): readonly DeclaredRoot[];
+/**
+ * The Funnel-B selector for a **no-path, whole-root MUTATION** — today
+ * `create_pull_request` (and the future commit/branch/push tools). Unlike
+ * {@link resolveReadRoots} it commits to exactly ONE root and, in a multi-root
+ * session, refuses to default (⚖︎#11, JC-1 take B):
+ *
+ *   - an explicit `root` name → that one declared root (fail-loud on unknown, R1);
+ *   - single-root session → the primary root (byte-identical to pre-C.26 — a
+ *     single root is unambiguous, so no `root` is required);
+ *   - multi-root, unscoped → refuse `ROOT_AMBIGUOUS` (a defaulted PR is the
+ *     "opened the wrong repo" accident; ambiguity only exists when N > 1).
+ *
+ * `what` names the action in the refusal message (e.g. `"a pull request"`). This
+ * throws BEFORE the caller runs any git, so a no-root multi-root call performs
+ * zero git spawns.
+ *
+ * @throws {CruxyError} CRUXY_E_ROOT_UNKNOWN (unknown name) / CRUXY_E_ROOT_AMBIGUOUS
+ *   (multi-root, no root).
+ */
+export declare function resolveMutationRoot(ctx: ToolContext, ref: {
+    root?: string;
+}, what: string): DeclaredRoot;

package/dist/tools/file/paths.js

@@ -1,67 +1,175 @@
-import { promises as fs } from "node:fs";
 import path from "node:path";
-import { CruxyError, ErrorCode } from "../../errors/index.js";
+import { multirootWriteDeferred, rootAmbiguous } from "../../errors/index.js";
+import { confineToRoot, PathEscapeError, selectRoot, singleRootWorkspace, } from "../../workspace/index.js";
 /**
- * Thrown when a tool argument resolves to a path outside the project root —
- * whether via `../` traversal, an absolute path, or a symlink pointing outward.
- * A {@link CruxyError} (code CRUXY_E_PATH_ESCAPE) so it carries a code if it
- * reaches the boundary; tools still catch it and surface `{ ok:false }`.
+ * Path confinement for file tools (C.26). The confinement kernel itself lives in
+ * `src/workspace` ({@link confineToRoot}); this module is the tool-facing funnel
+ * that every path-taking tool calls instead of touching the filesystem directly.
+ * Keeping ONE resolver here is what makes Funnel A ("a path tool cannot reach fs
+ * outside the selected root") a structural property rather than a per-tool habit.
  */
-export class PathEscapeError extends CruxyError {
-    constructor(message) {
-        super({ code: ErrorCode.PathEscape, title: message });
-        this.name = "PathEscapeError";
+export { PathEscapeError };
+/**
+ * The workspace this context acts in. Runtime always sets `ctx.workspace`; the
+ * fallback to a trivial single-root workspace over `ctx.cwd` exists only for the
+ * many test contexts (and any not-yet-migrated caller) that don't set one. The
+ * fallback is byte-identical to the legacy single-root behaviour by construction:
+ * its one root's `absPath` is `path.resolve(ctx.cwd)`, the same root the old
+ * `resolveInRoot` confined to.
+ */
+export function contextWorkspace(ctx) {
+    return ctx.workspace ?? singleRootWorkspace(ctx.cwd);
+}
+/**
+ * Resolve a tool-supplied path against the workspace and prove it stays inside the
+ * one root it selects — the single funnel for every path-taking file tool.
+ *
+ * Single-root sessions short-circuit straight to `confineToRoot(primary, path)`,
+ * which is exactly the legacy `resolveInRoot` behaviour (same result, same
+ * error type + message for every case: relative, absolute-inside, absolute-outside,
+ * outward symlink). Multi-root sessions run the two-step select-then-confine:
+ * {@link selectRoot} commits to exactly one declared root FIRST, then
+ * {@link confineToRoot} validates against only that root — so a `../otherRoot/x`
+ * that lands in a sibling is refused as an ordinary `PATH_ESCAPE` (R2), never
+ * rebound to the sibling.
+ *
+ * `deferNonPrimaryWrite` (set by the mutating file tools) refuses a write whose
+ * selected root is NOT the primary in a multi-root session, with
+ * `CRUXY_E_MULTIROOT_WRITE_DEFERRED` — UNLESS `ctx.checkpointsActive` is true.
+ * That flag is the C.26 step-3 coupling: it is set exactly when a per-root
+ * checkpoint gate is wired, which captures the write (snapshots its root) before
+ * it reaches disk — so the refusal lifts precisely when the write becomes
+ * rollback-able, never before (not step-wide, not lift-then-verify). With
+ * checkpoints disabled the flag is false, so a non-primary write is still refused
+ * rather than left un-restorable (⚖︎JC-γ: the opt-out covers the user's own cwd,
+ * not every declared sibling). It is a no-op in single-root (there is only the
+ * primary) and for reads (which never set it). The refusal is raised BEFORE any
+ * filesystem access.
+ *
+ * @throws {PathEscapeError} if the path escapes the selected root.
+ * @throws {CruxyError} CRUXY_E_ROOT_UNKNOWN / CRUXY_E_ROOT_AMBIGUOUS on bad selection,
+ *   or CRUXY_E_MULTIROOT_WRITE_DEFERRED on a non-primary write while deferred.
+ */
+export async function resolveToolPath(ctx, ref, opts = {}) {
+    const ws = contextWorkspace(ctx);
+    // Single-root: byte-identical with the legacy single-root funnel. Skipping
+    // selectRoot here also means a bare path segment that happens to equal the sole
+    // root's name is never mis-stripped as a root prefix. (A single-root session has
+    // only the primary, so the non-primary-write guard can never fire here.)
+    if (!ws.isMultiRoot) {
+        const root = ws.primary();
+        return { root, abs: await confineToRoot(root.absPath, ref.path) };
     }
+    const selected = selectRoot(ws, ref, opts);
+    if (opts.deferNonPrimaryWrite &&
+        selected.root.name !== ws.primary().name &&
+        !ctx.checkpointsActive) {
+        // Refuse BEFORE confineToRoot touches the filesystem — no partial write. The
+        // lift is conditioned on the per-root checkpoint gate being wired
+        // (ctx.checkpointsActive): permitting the write and capturing it are the same
+        // decision, so a permitted non-primary write is always checkpointed.
+        throw multirootWriteDeferred(selected.root.name, ws.primary().name);
+    }
+    return {
+        root: selected.root,
+        abs: await confineToRoot(selected.root.absPath, selected.relPath),
+    };
+}
+/**
+ * Legacy single-root entry point, retained as a thin shim over
+ * {@link resolveToolPath} so callers that pass only a bare path (e.g. the LSP
+ * tools) keep working and stay byte-identical. New path tools should call
+ * {@link resolveToolPath} so they can carry an explicit root selector.
+ *
+ * @returns the resolved absolute path (lexical, not realpath'd).
+ * @throws {PathEscapeError} if the path escapes the root.
+ */
+export async function resolveInRoot(ctx, p) {
+    return (await resolveToolPath(ctx, { path: p })).abs;
 }
-/** Is `target` the root itself or a descendant of it? */
-function isInside(root, target) {
-    return target === root || target.startsWith(root + path.sep);
+/**
+ * True when a glob pattern could walk outside its root — an absolute pattern or one
+ * containing a `..` segment. The ONE implementation of "does this pattern escape",
+ * shared by `glob` and `grep_files` so the two walk-rooted tools cannot diverge
+ * (closing G1/G2). Path *arguments* go through {@link resolveToolPath}; glob
+ * *patterns* are not resolvable paths, so this predicate guards the walk instead.
+ */
+export function isEscapingPattern(pattern) {
+    return path.isAbsolute(pattern) || pattern.split(/[/\\]/).includes("..");
 }
 /**
- * realpath `p`, or — if it doesn't exist yet — the realpath of its nearest
- * existing ancestor directory. Lets us validate a not-yet-created path by the
- * directory it would be created in (catching outward symlinked parents).
+ * The separator between a root's name and a path within it (`‹root› ▸ rel`) — one
+ * constant so every no-path tool that fans across roots renders the same label.
+ */
+export const ROOT_LABEL_SEP = " ▸ ";
+/**
+ * Prefix a root-relative path with its root name — but ONLY in a genuine
+ * multi-root session. In single-root the label is dropped so output stays
+ * byte-identical with the pre-C.26 tools. The `root`/`rel` pair always comes from
+ * the same fan iteration that produced the bytes, so a rendered label can never
+ * point at a different root than the one that was walked (the honesty pin).
  */
-async function realpathOfNearestExisting(p) {
-    let cur = p;
-    for (;;) {
-        try {
-            return await fs.realpath(cur);
-        }
-        catch (err) {
-            if (err.code !== "ENOENT")
-                throw err;
-            const parent = path.dirname(cur);
-            if (parent === cur)
-                return cur; // reached the filesystem root
-            cur = parent;
-        }
+export function labelPath(root, rel, isMultiRoot) {
+    return isMultiRoot ? labelName(root.name, rel) : rel;
+}
+/** As {@link labelPath} but from a bare root name (for hits that carry only a name). */
+export function labelName(rootName, rel) {
+    return `${rootName}${ROOT_LABEL_SEP}${rel}`;
+}
+/**
+ * The Funnel-B selector for **no-path** tools (`glob`, `grep_files`, `list_files`,
+ * `git_status`, `search_codebase`) — the counterpart to {@link resolveToolPath}.
+ * A no-path tool has no path to confine; its boundary is *which root's `absPath`*
+ * it threads as the walk-start / index-key / spawn-cwd. This returns that root
+ * set, and the tool commits to exactly one root per read by iterating it:
+ *
+ *   - an explicit `root` name → that one declared root (fail-loud on unknown, R1);
+ *   - single-root session → the primary root (so output is byte-identical);
+ *   - multi-root, unscoped → **fan** every declared root.
+ *
+ * The fan is N independent single-root reads (one `root.absPath` each), never one
+ * walk over a union — so each read is Funnel-B-confined and the cross-root merge
+ * only ever happens on already-attributed *results*, never on the filesystem.
+ * Reads leave `requireExplicit` false (that gate is for mutations, ⚖︎#3).
+ *
+ * @throws {CruxyError} CRUXY_E_ROOT_UNKNOWN if a named root is not declared.
+ */
+export function resolveReadRoots(ctx, ref = {}) {
+    const ws = contextWorkspace(ctx);
+    if (ref.root !== undefined) {
+        return [ws.rootByName(ref.root)];
+    }
+    if (!ws.isMultiRoot) {
+        return [ws.primary()];
     }
+    return ws.roots();
 }
 /**
- * Resolve a tool-supplied path against the project root (`ctx.cwd`) and prove it
- * stays inside — the single security boundary every file tool funnels through.
+ * The Funnel-B selector for a **no-path, whole-root MUTATION** — today
+ * `create_pull_request` (and the future commit/branch/push tools). Unlike
+ * {@link resolveReadRoots} it commits to exactly ONE root and, in a multi-root
+ * session, refuses to default (⚖︎#11, JC-1 take B):
  *
- * Two layers: (1) a lexical check that the resolved absolute path is within root
- * (rejects `../` and absolute-outside before touching the FS); (2) a symlink
- * check that the real target — or, for a new path, its nearest existing parent —
- * resolves inside the *real* root. The root is realpath'd too, so this is correct
- * even when the root itself sits under a symlink (e.g. macOS `/var → /private/var`).
+ *   - an explicit `root` name → that one declared root (fail-loud on unknown, R1);
+ *   - single-root session → the primary root (byte-identical to pre-C.26 — a
+ *     single root is unambiguous, so no `root` is required);
+ *   - multi-root, unscoped → refuse `ROOT_AMBIGUOUS` (a defaulted PR is the
+ *     "opened the wrong repo" accident; ambiguity only exists when N > 1).
  *
- * @returns the resolved absolute path (lexical, not realpath'd — so callers
- *   operate on the intended location).
- * @throws {PathEscapeError} if the path escapes the root.
+ * `what` names the action in the refusal message (e.g. `"a pull request"`). This
+ * throws BEFORE the caller runs any git, so a no-root multi-root call performs
+ * zero git spawns.
+ *
+ * @throws {CruxyError} CRUXY_E_ROOT_UNKNOWN (unknown name) / CRUXY_E_ROOT_AMBIGUOUS
+ *   (multi-root, no root).
  */
-export async function resolveInRoot(ctx, p) {
-    const root = path.resolve(ctx.cwd);
-    const resolved = path.resolve(root, p);
-    if (!isInside(root, resolved)) {
-        throw new PathEscapeError(`path "${p}" resolves outside the project root`);
+export function resolveMutationRoot(ctx, ref, what) {
+    const ws = contextWorkspace(ctx);
+    if (ref.root !== undefined) {
+        return ws.rootByName(ref.root);
     }
-    const realRoot = await fs.realpath(root);
-    const realTarget = await realpathOfNearestExisting(resolved);
-    if (!isInside(realRoot, realTarget)) {
-        throw new PathEscapeError(`path "${p}" resolves outside the project root (via a symlink)`);
+    if (!ws.isMultiRoot) {
+        return ws.primary();
     }
-    return resolved;
+    throw rootAmbiguous(what, ws.roots().map((r) => r.name));
 }

package/dist/tools/file/read-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";
 /** Files larger than this are truncated rather than dumped in full. */
 const MAX_BYTES = 256 * 1024;
 /**
@@ -16,7 +16,7 @@ export const readFileTool = {
     }),
     async execute(input, ctx) {
         try {
-            const abs = await resolveInRoot(ctx, input.path);
+            const { abs } = await resolveToolPath(ctx, { path: input.path });
             const stat = await fs.stat(abs);
             if (stat.isDirectory()) {
                 return {

package/dist/tools/file/write-file.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";
 /** How many leading lines of new content the approval preview shows. */
 const PREVIEW_LINES = 20;
 /**
@@ -20,7 +20,7 @@ export const writeFileTool = {
     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/git-status.d.ts

@@ -4,5 +4,12 @@ import type { Tool } from "./types.js";
  * Report the current git branch and working-tree status (`git status
  * --porcelain`) for the project root. Read-only — no approval, like read_file
  * and glob.
+ *
+ * Multi-repo (C.26, Funnel B): with more than one declared root, it fans every
+ * root — each `getGitStatus(root.absPath)` spawns git with that root as its cwd,
+ * so a section reports exactly the working tree its label names. A non-git root
+ * is NAMED (not fatal), and a `root` argument scopes to one root.
  */
-export declare const gitStatusTool: Tool<z.ZodObject<Record<string, never>>>;
+export declare const gitStatusTool: Tool<z.ZodObject<{
+    root: z.ZodOptional<z.ZodString>;
+}>>;