@cruxy/cli 0.21.0 → 0.22.1

package/dist/config/schema.js

@@ -38,7 +38,6 @@ export const ToolsConfigSchema = z
     .object({
     fileEdit: z.boolean().default(true),
     shell: z.boolean().default(true),
-    webSearch: z.boolean().default(false), // C.17
 })
     .strict();
 export const GitConfigSchema = z
@@ -424,6 +423,50 @@ export const McpConfigSchema = z
     maxSchemaBytes: z.number().int().positive().default(8192),
 })
     .strict();
+/**
+ * Web-search + web-fetch subtool (C.20). OFF by default. When enabled, the agent
+ * gets a bounded `web_search` (query → ranked title/url/snippet) and a `web_fetch`
+ * (read one URL as text). Both surface EXTERNAL, attacker-controllable data:
+ * results and fetched pages are wrapped as untrusted data (do-not-follow-instructions
+ * envelope, fence-forgery neutralized) with upstream model names scrubbed, and
+ * are NEVER persisted to memory/index/checkpoint. `web_fetch` refuses non-http(s)
+ * schemes and any host that resolves into a private/loopback/link-local range
+ * (SSRF guard) — the request is never dispatched. No provider is constructed and
+ * no tool is registered while this is off. Search runs through a swappable
+ * `SearchProvider` seam; the direct provider's API key comes from the environment
+ * (`apiKeyEnv`), never from config-in-repo and never logged.
+ */
+export const WebConfigSchema = z
+    .object({
+    /** Master switch. When false, neither tool is registered and no provider is
+     * constructed (the feature stays fully inert). */
+    enabled: z.boolean().default(false),
+    /** Which search backend to use behind the `SearchProvider` seam. A gateway
+     * provider slots in here first-class if the backend ever proxies search. */
+    provider: z.enum(["tavily"]).default("tavily"),
+    /** Environment variable holding the direct provider's API key. The key is
+     * read at call time, sent only in the provider's auth field, and never
+     * logged or written to the repo. */
+    apiKeyEnv: z.string().min(1).default("TAVILY_API_KEY"),
+    /** Max search results returned to the model (top-N; the rest are dropped). */
+    maxResults: z.number().int().positive().max(20).default(5),
+    /** Max characters kept from a single result's snippet; the rest is truncated
+     * with a visible marker. */
+    snippetMaxChars: z.number().int().positive().default(500),
+    /** Max bytes read from a single `web_fetch` page; the rest is truncated with
+     * a visible marker (a hostile/huge page can't blow the context budget). */
+    fetchMaxBytes: z.number().int().positive().default(524288),
+    /** Per-request timeout (search and fetch) — a slow host errors, never hangs. */
+    timeoutMs: z.number().int().positive().default(15000),
+    /** Max HTTP redirects `web_fetch` follows; each hop is re-checked by the SSRF
+     * guard so a 3xx can't bounce the request into a private range. */
+    maxRedirects: z.number().int().min(0).default(3),
+    /** Escape hatch: allow `web_fetch` to reach private/loopback/link-local hosts.
+     * OFF by default (SSRF-safe); only set true for a deliberate internal-network
+     * use case. */
+    allowPrivateHosts: z.boolean().default(false),
+})
+    .strict();
 export const CruxyConfigSchema = z
     .object({
     model: ModelConfigSchema.default({}),
@@ -445,6 +488,7 @@ export const CruxyConfigSchema = z
     memory: MemoryConfigSchema.default({}),
     usage: UsageConfigSchema.default({}),
     mcp: McpConfigSchema.default({}),
+    web: WebConfigSchema.default({}),
     logLevel: z.enum(LOG_LEVELS).default("info"),
 })
     .strict();

package/dist/errors/constructors.d.ts

@@ -119,6 +119,43 @@ export declare function checkpointNotFound(id?: string): CruxyError;
  * Restoring is destructive and deliberate — there is no auto-rollback path, ever.
  */
 export declare function rollbackApprovalRequired(): CruxyError;
+/**
+ * A path/selector names a workspace root that is not in the declared set — an
+ * unknown root name, or an absolute path that lands in no declared root. Fail-loud
+ * by design and NEVER fuzzy-matched to a nearby root (R1): a silent near-match is
+ * a cross-root misfire. Refused before any FS access.
+ */
+export declare function rootUnknown(ref: string, known: readonly string[]): CruxyError;
+/**
+ * A path is ambiguous across the declared root set: an absolute path inside ≥2
+ * declared roots, or a mutating tool given no root when there is no unambiguous
+ * choice. Writes fail closed rather than guess which repo to touch.
+ */
+export declare function rootAmbiguous(ref: string, candidates: string[]): CruxyError;
+/**
+ * Declaration-time: a declared root nests inside / overlaps another. Refused at
+ * session start — overlap makes "which root owns this path" ambiguous and lets two
+ * checkpoints/grants fight over the same bytes.
+ */
+export declare function rootOverlap(a: string, b: string): CruxyError;
+/**
+ * An interactive add-root was refused: no TTY to confirm, or the user declined the
+ * confirm/trust prompt. The root set only ever grows by an explicit human act —
+ * never the model, never a repo-local config.
+ */
+export declare function rootAddRefused(reason: string): CruxyError;
+/**
+ * A multi-root rollback set references a member checkpoint that is missing or
+ * corrupt, or a touched root has no member. Loud — a partial rollback must never
+ * masquerade as success.
+ */
+export declare function checkpointSetIncomplete(runId: string, reason: string): CruxyError;
+/**
+ * A multi-root rollback failed mid-apply (R3): it restored some roots and not
+ * others, and it STOPPED rather than continue best-effort. Carries the exact
+ * restored-vs-not split; re-running rollback is idempotent and safe.
+ */
+export declare function checkpointSetPartial(runId: string, restored: string[], notRestored: string[], underlying?: unknown): CruxyError;
 /**
  * A subagent spawn was attempted past the configured nesting cap (C.14). The
  * spawn tool is structurally withheld at the cap, so reaching this means the
@@ -197,6 +234,35 @@ export declare function mcpUntrusted(root: string, servers: string[]): CruxyErro
  * gag-scrubbed (U.8) before it reaches the user-facing cause.
  */
 export declare function mcpConnect(server: string, underlying?: unknown): CruxyError;
+/**
+ * `web.enabled` is on but no usable search provider is configured — the API-key
+ * environment variable is unset (or the provider is unknown). THE HONESTY RULE:
+ * this is a coded, actionable failure, never an empty result — "no provider"
+ * must not read as "the web had no results". `apiKeyEnv` names the variable to set.
+ */
+export declare function webUnavailable(provider: string, apiKeyEnv: string): CruxyError;
+/**
+ * A web search did not complete — the provider returned an HTTP error, the network
+ * failed, or the request timed out. Distinct from a search that ran and found
+ * nothing (that stays an ordinary `ok:true` empty result). External provider text
+ * is gag-scrubbed (U.8) before it reaches the user-facing cause.
+ */
+export declare function webSearchFailed(underlying?: unknown): CruxyError;
+/**
+ * A `web_fetch` failed to retrieve a page: network error, timeout, an oversize or
+ * non-text body, or too many redirects. Distinct from a page that was fetched but
+ * held no readable text (an ordinary `ok:true` empty result). External response
+ * text is gag-scrubbed (U.8) before it reaches the user-facing cause.
+ */
+export declare function webFetchFailed(url: string, underlying?: unknown): CruxyError;
+/**
+ * A `web_fetch` was REFUSED before any request went out (SSRF guard): a non-http(s)
+ * scheme, or a host that resolves into a private/loopback/link-local range
+ * (127.0.0.1, 169.254.169.254 cloud metadata, 10.x, internal DNS, …). A security
+ * stop kept distinct from an ordinary fetch failure — the request is never
+ * dispatched. `web.allowPrivateHosts` is the deliberate escape hatch.
+ */
+export declare function webBlockedHost(url: string, reason: string): CruxyError;
 export declare function internal(underlying?: unknown): CruxyError;
 /**
  * Map a known provider/transport error (from `@cruxy/sdk`) to a typed

package/dist/errors/constructors.js

@@ -551,6 +551,115 @@ export function rollbackApprovalRequired() {
         ],
     });
 }
+// ── multi-repo / workspace (exit 18) — C.26 ───────────────────────────────────
+/**
+ * A path/selector names a workspace root that is not in the declared set — an
+ * unknown root name, or an absolute path that lands in no declared root. Fail-loud
+ * by design and NEVER fuzzy-matched to a nearby root (R1): a silent near-match is
+ * a cross-root misfire. Refused before any FS access.
+ */
+export function rootUnknown(ref, known) {
+    return new CruxyError({
+        code: ErrorCode.RootUnknown,
+        title: `no workspace root named "${ref}"`,
+        cause: "the root set is fixed at session start and matched exactly — never by prefix or nearest-name",
+        nextSteps: [
+            known.length
+                ? `declared roots: ${known.join(", ")}`
+                : "no additional roots are declared this session",
+            "pass --root <name>=<path> at startup, or add one interactively",
+        ],
+        meta: { ref, known: [...known] },
+    });
+}
+/**
+ * A path is ambiguous across the declared root set: an absolute path inside ≥2
+ * declared roots, or a mutating tool given no root when there is no unambiguous
+ * choice. Writes fail closed rather than guess which repo to touch.
+ */
+export function rootAmbiguous(ref, candidates) {
+    return new CruxyError({
+        code: ErrorCode.RootAmbiguous,
+        title: `"${ref}" is ambiguous across the declared roots`,
+        cause: candidates.length > 1
+            ? `it resolves inside more than one declared root: ${candidates.join(", ")}`
+            : "a mutating action must name exactly one root",
+        nextSteps: [
+            "name the root explicitly with the `root` argument",
+            "declare either the monorepo root OR its packages, never both (overlap is refused)",
+        ],
+        meta: { ref, candidates },
+    });
+}
+/**
+ * Declaration-time: a declared root nests inside / overlaps another. Refused at
+ * session start — overlap makes "which root owns this path" ambiguous and lets two
+ * checkpoints/grants fight over the same bytes.
+ */
+export function rootOverlap(a, b) {
+    return new CruxyError({
+        code: ErrorCode.RootOverlap,
+        title: "declared workspace roots overlap",
+        cause: `"${a}" nests inside or equals "${b}"`,
+        nextSteps: [
+            "declare the monorepo root OR specific package roots, never both",
+            "remove one of the overlapping --root entries",
+        ],
+        meta: { a, b },
+    });
+}
+/**
+ * An interactive add-root was refused: no TTY to confirm, or the user declined the
+ * confirm/trust prompt. The root set only ever grows by an explicit human act —
+ * never the model, never a repo-local config.
+ */
+export function rootAddRefused(reason) {
+    return new CruxyError({
+        code: ErrorCode.RootAddRefused,
+        title: "adding a workspace root was refused",
+        cause: reason,
+        nextSteps: [
+            "declare roots up front with --root at startup",
+            "add a root only from an interactive terminal, where it can be confirmed and trusted",
+        ],
+        meta: { reason },
+    });
+}
+/**
+ * A multi-root rollback set references a member checkpoint that is missing or
+ * corrupt, or a touched root has no member. Loud — a partial rollback must never
+ * masquerade as success.
+ */
+export function checkpointSetIncomplete(runId, reason) {
+    return new CruxyError({
+        code: ErrorCode.CheckpointSetIncomplete,
+        title: `rollback set "${runId}" is incomplete`,
+        cause: reason,
+        nextSteps: [
+            "run `cruxy checkpoint list` to inspect each root's checkpoints",
+            "roll back an individual root's checkpoint with `cruxy rollback <id>` if needed",
+        ],
+        meta: { runId, reason },
+    });
+}
+/**
+ * A multi-root rollback failed mid-apply (R3): it restored some roots and not
+ * others, and it STOPPED rather than continue best-effort. Carries the exact
+ * restored-vs-not split; re-running rollback is idempotent and safe.
+ */
+export function checkpointSetPartial(runId, restored, notRestored, underlying) {
+    return new CruxyError({
+        code: ErrorCode.CheckpointSetPartial,
+        title: `rollback of set "${runId}" stopped partway`,
+        cause: `restored: ${restored.join(", ") || "none"}; not restored: ${notRestored.join(", ") || "none"}`,
+        nextSteps: [
+            "re-run `cruxy rollback` — it recomputes each root from disk and is safe to retry",
+            "the not-restored roots are unchanged; no root is left half-applied silently",
+        ],
+        underlying,
+        meta: { runId, restored, notRestored },
+    });
+}
 // ── subagent (exit 2 / 11) ────────────────────────────────────────────────────
 /**
  * A subagent spawn was attempted past the configured nesting cap (C.14). The
@@ -779,6 +888,83 @@ export function mcpConnect(server, underlying) {
         underlying,
     });
 }
+// ── web search + fetch (exit 17) — C.20 ───────────────────────────────────────
+/**
+ * `web.enabled` is on but no usable search provider is configured — the API-key
+ * environment variable is unset (or the provider is unknown). THE HONESTY RULE:
+ * this is a coded, actionable failure, never an empty result — "no provider"
+ * must not read as "the web had no results". `apiKeyEnv` names the variable to set.
+ */
+export function webUnavailable(provider, apiKeyEnv) {
+    return new CruxyError({
+        code: ErrorCode.WebUnavailable,
+        title: `web search is enabled but the "${provider}" provider has no API key`,
+        cause: `the \`${apiKeyEnv}\` environment variable is not set`,
+        nextSteps: [
+            `export ${apiKeyEnv}=<your ${provider} api key> and re-run`,
+            "or set `web.enabled = false` to disable web tools for this project",
+        ],
+        meta: { provider, apiKeyEnv },
+    });
+}
+/**
+ * A web search did not complete — the provider returned an HTTP error, the network
+ * failed, or the request timed out. Distinct from a search that ran and found
+ * nothing (that stays an ordinary `ok:true` empty result). External provider text
+ * is gag-scrubbed (U.8) before it reaches the user-facing cause.
+ */
+export function webSearchFailed(underlying) {
+    return new CruxyError({
+        code: ErrorCode.WebSearch,
+        title: "web search failed",
+        cause: scrubbedMessageOf(underlying) ??
+            "the search provider errored, was unreachable, or timed out",
+        nextSteps: [
+            "re-run with --verbose to see the provider's error",
+            "check the provider status and your network, then retry",
+        ],
+        underlying,
+    });
+}
+/**
+ * A `web_fetch` failed to retrieve a page: network error, timeout, an oversize or
+ * non-text body, or too many redirects. Distinct from a page that was fetched but
+ * held no readable text (an ordinary `ok:true` empty result). External response
+ * text is gag-scrubbed (U.8) before it reaches the user-facing cause.
+ */
+export function webFetchFailed(url, underlying) {
+    return new CruxyError({
+        code: ErrorCode.WebFetch,
+        title: `could not fetch ${url}`,
+        cause: scrubbedMessageOf(underlying) ??
+            "the request errored, timed out, or returned a non-text/oversize body",
+        nextSteps: [
+            "verify the URL is reachable and serves text (html/plain/json)",
+            "re-run with --verbose to see the underlying error",
+        ],
+        meta: { url },
+        underlying,
+    });
+}
+/**
+ * A `web_fetch` was REFUSED before any request went out (SSRF guard): a non-http(s)
+ * scheme, or a host that resolves into a private/loopback/link-local range
+ * (127.0.0.1, 169.254.169.254 cloud metadata, 10.x, internal DNS, …). A security
+ * stop kept distinct from an ordinary fetch failure — the request is never
+ * dispatched. `web.allowPrivateHosts` is the deliberate escape hatch.
+ */
+export function webBlockedHost(url, reason) {
+    return new CruxyError({
+        code: ErrorCode.WebBlockedHost,
+        title: `refused to fetch ${url}`,
+        cause: reason,
+        nextSteps: [
+            "fetch a public http(s) URL instead",
+            "if you intentionally target an internal host, set `web.allowPrivateHosts = true`",
+        ],
+        meta: { url },
+    });
+}
 // ── internal (exit 1) ─────────────────────────────────────────────────────────
 export function internal(underlying) {
     return new CruxyError({

package/dist/errors/types.d.ts

@@ -102,6 +102,49 @@ export declare const ErrorCode: {
      * or list its tools. Surfaced (that server contributes no tools) rather than
      * silently swallowed; never fatal to the run. */
     readonly McpConnect: "CRUXY_E_MCP_CONNECT";
+    /** `web.enabled` is on but no usable search provider is configured — the API
+     * key env var is unset or the provider is unknown. Actionable, NEVER a silent
+     * empty result: "no provider" must not read as "no search results". */
+    readonly WebUnavailable: "CRUXY_E_WEB_UNAVAILABLE";
+    /** A web search failed (provider HTTP error, network failure, or timeout). The
+     * search did NOT run to completion — distinct from a search that ran and found
+     * nothing (that is an ordinary `ok:true` empty result). */
+    readonly WebSearch: "CRUXY_E_WEB_SEARCH";
+    /** A `web_fetch` failed: network error, timeout, oversize/non-text body, or too
+     * many redirects. Distinct from a page fetched successfully that had no readable
+     * text (an ordinary `ok:true` empty result). */
+    readonly WebFetch: "CRUXY_E_WEB_FETCH";
+    /** A `web_fetch` was REFUSED before any request was dispatched: a non-http(s)
+     * scheme, or a host that resolves into a private/loopback/link-local range
+     * (SSRF guard — e.g. 127.0.0.1, 169.254.169.254, 10.x, internal DNS). A
+     * security stop, kept distinct from an ordinary fetch failure for grep-ability. */
+    readonly WebBlockedHost: "CRUXY_E_WEB_BLOCKED_HOST";
+    /** A path/selector names a workspace root that is not in the declared set (or an
+     * absolute path that lands in no declared root). Fail-loud and NEVER fuzzy- or
+     * prefix-matched to a nearby root — a silent near-match is a cross-root misfire.
+     * Refused before any FS access; never falls through to the host filesystem. */
+    readonly RootUnknown: "CRUXY_E_ROOT_UNKNOWN";
+    /** A path is ambiguous across the declared root set: an absolute path that falls
+     * inside ≥2 declared roots, or a mutating tool given no root when there's no
+     * unambiguous choice. Writes fail closed rather than guess a root. */
+    readonly RootAmbiguous: "CRUXY_E_ROOT_AMBIGUOUS";
+    /** Declaration-time: a declared root nests inside / overlaps another. Refused at
+     * session start — overlap makes "which root owns this path" ambiguous and lets
+     * two checkpoints/grants fight over the same bytes. Declare the monorepo root OR
+     * its packages, never both. */
+    readonly RootOverlap: "CRUXY_E_ROOT_OVERLAP";
+    /** An interactive add-root was refused: no TTY to confirm, or the user declined
+     * the confirm/trust prompt. The root set only ever grows by an explicit human
+     * act — never by the model or a repo-local config. */
+    readonly RootAddRefused: "CRUXY_E_ROOT_ADD_REFUSED";
+    /** A multi-root rollback set references a member checkpoint that is missing or
+     * corrupt, or a touched root has no member. Loud — a partial rollback must never
+     * masquerade as success. */
+    readonly CheckpointSetIncomplete: "CRUXY_E_CHECKPOINT_SET_INCOMPLETE";
+    /** A multi-root rollback failed mid-apply (R3): carries which roots were restored
+     * and which were not. The set is left recoverable by an idempotent re-run and is
+     * NEVER reported as success. */
+    readonly CheckpointSetPartial: "CRUXY_E_CHECKPOINT_SET_PARTIAL";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 /** The process exit code for an error code (defaults to 1 for safety). */

package/dist/errors/types.js

@@ -120,6 +120,51 @@ export const ErrorCode = {
      * or list its tools. Surfaced (that server contributes no tools) rather than
      * silently swallowed; never fatal to the run. */
     McpConnect: "CRUXY_E_MCP_CONNECT",
+    // web search + fetch (exit 17) — C.20
+    /** `web.enabled` is on but no usable search provider is configured — the API
+     * key env var is unset or the provider is unknown. Actionable, NEVER a silent
+     * empty result: "no provider" must not read as "no search results". */
+    WebUnavailable: "CRUXY_E_WEB_UNAVAILABLE",
+    /** A web search failed (provider HTTP error, network failure, or timeout). The
+     * search did NOT run to completion — distinct from a search that ran and found
+     * nothing (that is an ordinary `ok:true` empty result). */
+    WebSearch: "CRUXY_E_WEB_SEARCH",
+    /** A `web_fetch` failed: network error, timeout, oversize/non-text body, or too
+     * many redirects. Distinct from a page fetched successfully that had no readable
+     * text (an ordinary `ok:true` empty result). */
+    WebFetch: "CRUXY_E_WEB_FETCH",
+    /** A `web_fetch` was REFUSED before any request was dispatched: a non-http(s)
+     * scheme, or a host that resolves into a private/loopback/link-local range
+     * (SSRF guard — e.g. 127.0.0.1, 169.254.169.254, 10.x, internal DNS). A
+     * security stop, kept distinct from an ordinary fetch failure for grep-ability. */
+    WebBlockedHost: "CRUXY_E_WEB_BLOCKED_HOST",
+    // multi-repo / workspace (exit 18) — C.26
+    /** A path/selector names a workspace root that is not in the declared set (or an
+     * absolute path that lands in no declared root). Fail-loud and NEVER fuzzy- or
+     * prefix-matched to a nearby root — a silent near-match is a cross-root misfire.
+     * Refused before any FS access; never falls through to the host filesystem. */
+    RootUnknown: "CRUXY_E_ROOT_UNKNOWN",
+    /** A path is ambiguous across the declared root set: an absolute path that falls
+     * inside ≥2 declared roots, or a mutating tool given no root when there's no
+     * unambiguous choice. Writes fail closed rather than guess a root. */
+    RootAmbiguous: "CRUXY_E_ROOT_AMBIGUOUS",
+    /** Declaration-time: a declared root nests inside / overlaps another. Refused at
+     * session start — overlap makes "which root owns this path" ambiguous and lets
+     * two checkpoints/grants fight over the same bytes. Declare the monorepo root OR
+     * its packages, never both. */
+    RootOverlap: "CRUXY_E_ROOT_OVERLAP",
+    /** An interactive add-root was refused: no TTY to confirm, or the user declined
+     * the confirm/trust prompt. The root set only ever grows by an explicit human
+     * act — never by the model or a repo-local config. */
+    RootAddRefused: "CRUXY_E_ROOT_ADD_REFUSED",
+    /** A multi-root rollback set references a member checkpoint that is missing or
+     * corrupt, or a touched root has no member. Loud — a partial rollback must never
+     * masquerade as success. */
+    CheckpointSetIncomplete: "CRUXY_E_CHECKPOINT_SET_INCOMPLETE",
+    /** A multi-root rollback failed mid-apply (R3): carries which roots were restored
+     * and which were not. The set is left recoverable by an idempotent re-run and is
+     * NEVER reported as success. */
+    CheckpointSetPartial: "CRUXY_E_CHECKPOINT_SET_PARTIAL",
 };
 /**
  * Category exit codes. Distinct per category so a caller (CI, a script) can
@@ -202,6 +247,25 @@ const EXIT_CODES = {
     // never fatal on its own. Grouped for a greppable exit code.
     [ErrorCode.McpUntrusted]: 16,
     [ErrorCode.McpConnect]: 16,
+    // Web search + fetch (C.20). A missing provider, a search/fetch failure, and an
+    // SSRF-blocked host all surface inside a tool result (the agent reads and
+    // adapts) and only exit the process if thrown directly. Grouped for a greppable
+    // exit code.
+    [ErrorCode.WebUnavailable]: 17,
+    [ErrorCode.WebSearch]: 17,
+    [ErrorCode.WebFetch]: 17,
+    [ErrorCode.WebBlockedHost]: 17,
+    // Multi-repo / workspace (C.26). Declaration-time root-set problems
+    // (unknown/ambiguous/overlap/add-refused) and multi-root rollback failures
+    // (incomplete/partial) share a greppable exit code. A cross-root *path* is NOT
+    // here — it reuses CRUXY_E_PATH_ESCAPE (a cross-root path is an escape from the
+    // acting root; a distinct code would wrongly imply "less bad").
+    [ErrorCode.RootUnknown]: 18,
+    [ErrorCode.RootAmbiguous]: 18,
+    [ErrorCode.RootOverlap]: 18,
+    [ErrorCode.RootAddRefused]: 18,
+    [ErrorCode.CheckpointSetIncomplete]: 18,
+    [ErrorCode.CheckpointSetPartial]: 18,
 };
 /** The process exit code for an error code (defaults to 1 for safety). */
 export function exitCodeFor(code) {

package/dist/sandbox/docker-runtime.js

@@ -151,7 +151,10 @@ export function buildRunArgs(policy, container, command) {
         "--tmpfs",
         `${policy.tmpfs}:rw,nosuid,nodev,size=64m`, // … except an in-memory tmp
         "-v",
-        mountSpec(policy.workdir), // ONLY the workdir, read-write
+        mountSpec(policy.workdir), // the command's own root, read-write
+        // Other declared roots (C.26, R5): read-only unless a per-command escalation
+        // flipped one to rw. Ambient cross-root write is never the default.
+        ...(policy.siblingRoots ?? []).flatMap((m) => ["-v", mountSpec(m)]),
         ...policy.mounts.flatMap((m) => ["-v", mountSpec(m)]),
         "-w",
         policy.workdir.target,

package/dist/sandbox/policy.d.ts

@@ -5,8 +5,12 @@ import type { IsolationPolicy } from "./types.js";
  * {@link IsolationPolicy}. This is where the security posture is decided, and
  * every default here is deny/minimal:
  *
- * - the ONLY read-write mount is the project workdir (at its identical absolute
- *   path, so paths stay coherent with the host and the C.32 checkpoint);
+ * - the DEFAULT read-write mount is the command's own project workdir (at its
+ *   identical absolute path, so paths stay coherent with the host and the C.32
+ *   checkpoint);
+ * - other declared roots in a multi-repo session (C.26, R5) are mounted READ-ONLY
+ *   — readable for legit cross-repo builds, never writable unless an explicit
+ *   per-command escalation names that root in `writableRoots`;
  * - extra mounts come solely from `sandbox.mounts` (explicit by construction),
  *   and a mount of the docker socket, the cruxy home, or the user's home root
  *   is rejected — those are the escape hatches we refuse to open;
@@ -14,4 +18,9 @@ import type { IsolationPolicy } from "./types.js";
  *   writable and never left root-owned;
  * - network defaults to `none`; any widening can only come from explicit config.
  */
-export declare function buildPolicy(cfg: SandboxConfig, cwd: string): IsolationPolicy;
+export declare function buildPolicy(cfg: SandboxConfig, cwd: string, opts?: {
+    /** Absolute paths of the OTHER declared roots (this command's siblings). */
+    siblingRoots?: readonly string[];
+    /** Sibling roots that got an approved cross-root-write escalation (R5). */
+    writableRoots?: readonly string[];
+}): IsolationPolicy;

package/dist/sandbox/policy.js

@@ -7,8 +7,12 @@ import { globalDir } from "../config/paths.js";
  * {@link IsolationPolicy}. This is where the security posture is decided, and
  * every default here is deny/minimal:
  *
- * - the ONLY read-write mount is the project workdir (at its identical absolute
- *   path, so paths stay coherent with the host and the C.32 checkpoint);
+ * - the DEFAULT read-write mount is the command's own project workdir (at its
+ *   identical absolute path, so paths stay coherent with the host and the C.32
+ *   checkpoint);
+ * - other declared roots in a multi-repo session (C.26, R5) are mounted READ-ONLY
+ *   — readable for legit cross-repo builds, never writable unless an explicit
+ *   per-command escalation names that root in `writableRoots`;
  * - extra mounts come solely from `sandbox.mounts` (explicit by construction),
  *   and a mount of the docker socket, the cruxy home, or the user's home root
  *   is rejected — those are the escape hatches we refuse to open;
@@ -16,12 +20,21 @@ import { globalDir } from "../config/paths.js";
  *   writable and never left root-owned;
  * - network defaults to `none`; any widening can only come from explicit config.
  */
-export function buildPolicy(cfg, cwd) {
+export function buildPolicy(cfg, cwd, opts = {}) {
     const workdir = {
         source: cwd,
         target: cwd,
         readonly: false,
     };
+    const writable = new Set((opts.writableRoots ?? []).map((r) => resolvePath(r)));
+    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)
+    }));
     return {
         image: cfg.image,
         network: cfg.network,
@@ -30,6 +43,7 @@ export function buildPolicy(cfg, cwd) {
         pids: cfg.pids,
         cpus: cfg.cpus,
         workdir,
+        siblingRoots,
         mounts: cfg.mounts.map((spec) => parseMount(spec, cwd)),
         tmpfs: "/tmp",
     };

package/dist/sandbox/types.d.ts

@@ -43,8 +43,17 @@ export interface IsolationPolicy {
     readonly pids: number;
     /** CPU cap (`--cpus`, fractional allowed). */
     readonly cpus: number;
-    /** The project workdir, mounted read-write at the identical absolute path. */
+    /** The command's OWN workspace root, mounted read-write at its absolute path. */
     readonly workdir: BindMount;
+    /**
+     * The OTHER declared workspace roots in a multi-repo session (C.26, R5). Each
+     * is mounted **read-only** so a legit build can *read* a sibling (e.g. generated
+     * client types) — but never write it. A sibling flips to read-write ONLY when an
+     * explicit per-command cross-root-write escalation was approved for that exact
+     * root; ambient cross-root write authority is never the default. Empty in a
+     * single-root session (identical to the pre-C.26 posture).
+     */
+    readonly siblingRoots?: readonly BindMount[];
     /** Extra explicit mounts beyond the workdir (from `sandbox.mounts`). */
     readonly mounts: readonly BindMount[];
     /** Writable in-memory tmp mount point; the rest of the root fs is read-only. */

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

@@ -1,26 +1,19 @@
-import { CruxyError } from "../../errors/index.js";
+import { PathEscapeError } 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. The confinement kernel now lives in
+ * `src/workspace` so multi-root (C.26) and single-root callers share ONE
+ * implementation. This module keeps the single-root `resolveInRoot` entry point
+ * (and re-exports {@link PathEscapeError}) so existing call sites are unchanged:
+ * they confine to `ctx.cwd`, which is the workspace's primary root.
  */
-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.
+ * stays inside — the single-root funnel. Delegates to {@link confineToRoot}; see
+ * there for the 2-layer (lexical + symlink) confinement logic.
  *
- * 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`).
- *
- * @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>;