@cruxy/cli 0.12.0 → 0.13.0

package/dist/sandbox/docker-runtime.js

@@ -0,0 +1,263 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { sandboxExec, sandboxImage } from "../errors/index.js";
+/**
+ * The shipped {@link SandboxRuntime}: shells out to the `docker` CLI (no SDK —
+ * matches the no-vendor-client ethos). {@link buildRunArgs} is a pure function
+ * so the entire isolation posture can be asserted from the argv without a live
+ * daemon; `exec` spawns docker, captures bias-capped output, enforces the
+ * wall-clock timeout by force-killing the container, and maps the result.
+ *
+ * The exit code from `docker run` is the command's own — EXCEPT `125`, which
+ * docker reserves for "the run itself failed" (bad flags, daemon error): that,
+ * and a spawn failure, are the only container-start failures, surfaced as a
+ * coded {@link sandboxExec} error. An ordinary non-zero command exit is a
+ * normal result (exit code is truth), never a thrown error and never a host run.
+ */
+export class DockerRuntime {
+    bin;
+    name = "docker";
+    constructor(bin = "docker") {
+        this.bin = bin;
+    }
+    async ensureImage(image, onPull) {
+        // Present locally already? `docker image inspect` exits 0 when it is.
+        const inspect = await this.simpleRun(["image", "inspect", image]);
+        if (inspect.code === 0)
+            return;
+        // Not present — pull it (surface once), and fail loud if the pull fails.
+        onPull?.();
+        const pull = await this.simpleRun(["pull", image]);
+        if (pull.code !== 0) {
+            throw sandboxImage(image, pull.stderr.trim() || pull.stdout.trim());
+        }
+    }
+    /** Run a non-container docker subcommand to completion, capturing output. */
+    simpleRun(args) {
+        return new Promise((resolve) => {
+            let child;
+            try {
+                child = spawn(this.bin, args);
+            }
+            catch (err) {
+                resolve({ code: null, stdout: "", stderr: err.message });
+                return;
+            }
+            let out = "";
+            let errText = "";
+            child.stdout?.on("data", (b) => (out += b.toString("utf8")));
+            child.stderr?.on("data", (b) => (errText += b.toString("utf8")));
+            child.on("error", (err) => resolve({ code: null, stdout: out, stderr: err.message }));
+            child.on("close", (code) => resolve({ code, stdout: out, stderr: errText }));
+        });
+    }
+    exec(command, policy, opts) {
+        const container = `cruxy-sbx-${randomUUID()}`;
+        const argv = buildRunArgs(policy, container, command);
+        return this.run(argv, container, opts);
+    }
+    run(argv, container, opts) {
+        const startedAt = Date.now();
+        return new Promise((resolve, reject) => {
+            const capture = new OutputCapture(opts.maxOutputBytes, opts.capture);
+            let child;
+            try {
+                // `detached` groups the docker client so a timeout kills the whole tree.
+                child = spawn(this.bin, argv, { detached: true });
+            }
+            catch (err) {
+                reject(sandboxExec(err));
+                return;
+            }
+            child.stdout?.on("data", (b) => capture.push(b));
+            child.stderr?.on("data", (b) => capture.push(b));
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                killTree(child.pid);
+                // Killing the client may orphan the container — force-remove it too.
+                this.forceRemove(container);
+                const { output, truncated } = capture.result();
+                resolve({
+                    exitCode: null,
+                    output,
+                    outputTruncated: truncated,
+                    durationMs: Date.now() - startedAt,
+                    timedOut: true,
+                });
+            }, opts.timeoutMs);
+            child.on("error", (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                reject(sandboxExec(err));
+            });
+            child.on("close", (code) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                // 125 = `docker run` itself failed (not the inner command) → the
+                // container never really started. Fail loud, never fabricate a result.
+                if (code === 125) {
+                    const { output } = capture.result();
+                    reject(sandboxExec(output.trim() || "docker run exited 125"));
+                    return;
+                }
+                const { output, truncated } = capture.result();
+                resolve({
+                    exitCode: code,
+                    output,
+                    outputTruncated: truncated,
+                    durationMs: Date.now() - startedAt,
+                    timedOut: false,
+                });
+            });
+        });
+    }
+    /** Best-effort container teardown after a timeout kill. */
+    forceRemove(container) {
+        try {
+            const rm = spawn(this.bin, ["rm", "-f", container], {
+                stdio: "ignore",
+                detached: true,
+            });
+            rm.on("error", () => { });
+            rm.unref();
+        }
+        catch {
+            // Nothing more we can do; the container may already be gone.
+        }
+    }
+}
+/**
+ * Build the `docker run` argv from a resolved policy. Pure and total — the
+ * single source of truth for the isolation boundary, asserted directly in
+ * tests. Order is stable for readability; docker is order-insensitive for flags.
+ */
+export function buildRunArgs(policy, container, command) {
+    return [
+        "run",
+        "--rm", // auto-remove the container when it exits
+        "--name",
+        container, // so a timeout can force-remove it
+        ...networkArgs(policy.network),
+        "--user",
+        policy.user, // non-root
+        "--read-only", // root filesystem is read-only …
+        "--tmpfs",
+        `${policy.tmpfs}:rw,nosuid,nodev,size=64m`, // … except an in-memory tmp
+        "-v",
+        mountSpec(policy.workdir), // ONLY the workdir, read-write
+        ...policy.mounts.flatMap((m) => ["-v", mountSpec(m)]),
+        "-w",
+        policy.workdir.target,
+        "--memory",
+        policy.memory,
+        "--memory-swap",
+        policy.memory, // == memory disables swap (no swap-escape of the cap)
+        "--pids-limit",
+        String(policy.pids),
+        "--cpus",
+        String(policy.cpus),
+        "--security-opt",
+        "no-new-privileges", // no setuid privilege escalation
+        "--cap-drop",
+        "ALL", // drop every Linux capability
+        policy.image,
+        "sh",
+        "-c",
+        command,
+    ];
+}
+/**
+ * Egress flags. `none` denies all network (the default). Widening is a
+ * deliberate act: `full` uses the default bridge; `host-loopback` adds a
+ * host-gateway alias (best-effort — strict loopback-only firewalling is left
+ * for a later build). Anything but `none` can only come from explicit config.
+ */
+function networkArgs(network) {
+    switch (network) {
+        case "none":
+            return ["--network", "none"];
+        case "host-loopback":
+            return [
+                "--network",
+                "bridge",
+                "--add-host",
+                "host.docker.internal:host-gateway",
+            ];
+        case "full":
+            return ["--network", "bridge"];
+    }
+}
+function mountSpec(m) {
+    return `${m.source}:${m.target}:${m.readonly ? "ro" : "rw"}`;
+}
+/**
+ * Bias-capped output capture: `head` keeps the START and stops once the cap is
+ * hit (matches `run_command`); `tail` keeps the END, where failures live
+ * (matches `run_tests`). Bounded memory either way.
+ */
+class OutputCapture {
+    cap;
+    bias;
+    chunks = [];
+    bytes = 0;
+    truncated = false;
+    constructor(cap, bias) {
+        this.cap = cap;
+        this.bias = bias;
+    }
+    push(buf) {
+        if (this.bias === "head") {
+            if (this.truncated)
+                return;
+            const room = this.cap - this.bytes;
+            if (buf.length <= room) {
+                this.chunks.push(buf);
+                this.bytes += buf.length;
+            }
+            else {
+                if (room > 0) {
+                    this.chunks.push(buf.subarray(0, room));
+                    this.bytes += room;
+                }
+                this.truncated = true;
+            }
+            return;
+        }
+        // tail: append, dropping whole head chunks while the remainder still meets
+        // the cap; a final exact trim happens in result().
+        this.chunks.push(buf);
+        this.bytes += buf.length;
+        while (this.chunks.length > 1 &&
+            this.bytes - this.chunks[0].length >= this.cap) {
+            this.bytes -= this.chunks[0].length;
+            this.chunks.shift();
+            this.truncated = true;
+        }
+    }
+    result() {
+        let all = Buffer.concat(this.chunks);
+        if (this.bias === "tail" && all.length > this.cap) {
+            all = all.subarray(all.length - this.cap);
+            this.truncated = true;
+        }
+        return { output: all.toString("utf8"), truncated: this.truncated };
+    }
+}
+/** Kill the docker client's process group (POSIX; matches run_command). */
+function killTree(pid) {
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch {
+        // Already exited, or no group — nothing to kill.
+    }
+}

package/dist/sandbox/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./types.js";
+export { detectDocker, resetDetectionCache } from "./detect.js";
+export type { RuntimeProbe } from "./detect.js";
+export { DockerRuntime, buildRunArgs } from "./docker-runtime.js";
+export { buildPolicy } from "./policy.js";
+export { SandboxService } from "./service.js";
+export type { SandboxReporter, SandboxServiceDeps } from "./service.js";

package/dist/sandbox/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export { detectDocker, resetDetectionCache } from "./detect.js";
+export { DockerRuntime, buildRunArgs } from "./docker-runtime.js";
+export { buildPolicy } from "./policy.js";
+export { SandboxService } from "./service.js";

package/dist/sandbox/policy.d.ts

@@ -0,0 +1,17 @@
+import type { SandboxConfig } from "../config/index.js";
+import type { IsolationPolicy } from "./types.js";
+/**
+ * Turn a validated {@link SandboxConfig} + the run's cwd into a fully-resolved
+ * {@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);
+ * - 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;
+ * - the container runs as the host's non-root uid:gid so mounted edits are
+ *   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;

package/dist/sandbox/policy.js

@@ -0,0 +1,90 @@
+import { homedir } from "node:os";
+import { isAbsolute, resolve as resolvePath } from "node:path";
+import { configInvalid } from "../errors/index.js";
+import { globalDir } from "../config/paths.js";
+/**
+ * Turn a validated {@link SandboxConfig} + the run's cwd into a fully-resolved
+ * {@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);
+ * - 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;
+ * - the container runs as the host's non-root uid:gid so mounted edits are
+ *   writable and never left root-owned;
+ * - network defaults to `none`; any widening can only come from explicit config.
+ */
+export function buildPolicy(cfg, cwd) {
+    const workdir = {
+        source: cwd,
+        target: cwd,
+        readonly: false,
+    };
+    return {
+        image: cfg.image,
+        network: cfg.network,
+        user: resolveUser(),
+        memory: cfg.memory,
+        pids: cfg.pids,
+        cpus: cfg.cpus,
+        workdir,
+        mounts: cfg.mounts.map((spec) => parseMount(spec, cwd)),
+        tmpfs: "/tmp",
+    };
+}
+/** Host `uid:gid` — non-root (the human isn't uid 0) and keeps mounted files
+ * writable without leaving them root-owned. Falls back to a conventional
+ * non-root id where `getuid` is unavailable (non-POSIX). */
+function resolveUser() {
+    const getuid = process.getuid?.bind(process);
+    const getgid = process.getgid?.bind(process);
+    if (getuid && getgid)
+        return `${getuid()}:${getgid()}`;
+    return "1000:1000";
+}
+/** Sources we refuse to bind-mount into the box — the whole point is that the
+ * container cannot reach the docker socket, the cruxy credential store, or the
+ * user's home. Matched by resolved absolute path. */
+function forbiddenMountSource(source) {
+    const resolved = resolvePath(source);
+    const home = homedir();
+    if (resolved === "/var/run/docker.sock" || resolved.endsWith("docker.sock")) {
+        return "the docker socket (would grant full host control)";
+    }
+    if (resolved === globalDir() || resolved.startsWith(globalDir() + "/")) {
+        return "the cruxy home (holds credentials)";
+    }
+    if (resolved === home)
+        return "the home directory root";
+    if (resolved === "/")
+        return "the filesystem root";
+    return undefined;
+}
+/** Parse one `src:dst[:ro|:rw]` mount spec into a validated {@link BindMount}.
+ * Relative sources resolve against the run's cwd; a forbidden source throws a
+ * config error (never silently dropped). */
+function parseMount(spec, cwd) {
+    // Split on ":" but keep it simple — sources/targets are absolute POSIX-ish
+    // paths; a Windows drive letter is out of scope for this build.
+    const parts = spec.split(":");
+    if (parts.length < 2 || parts.length > 3) {
+        throw configInvalid(`sandbox.mounts entry "${spec}" must be "src:dst" or "src:dst:ro|rw"`);
+    }
+    const [rawSource, target, mode] = parts;
+    if (!target || !isAbsolute(target)) {
+        throw configInvalid(`sandbox.mounts entry "${spec}" needs an absolute container path (dst)`);
+    }
+    if (mode !== undefined && mode !== "ro" && mode !== "rw") {
+        throw configInvalid(`sandbox.mounts entry "${spec}" mode must be "ro" or "rw"`);
+    }
+    const source = isAbsolute(rawSource)
+        ? rawSource
+        : resolvePath(cwd, rawSource);
+    const forbidden = forbiddenMountSource(source);
+    if (forbidden) {
+        throw configInvalid(`sandbox.mounts refuses to mount ${forbidden}: "${spec}"`);
+    }
+    return { source, target, readonly: mode === "ro" };
+}

package/dist/sandbox/service.d.ts

@@ -0,0 +1,57 @@
+import type { CruxyConfig } from "../config/index.js";
+import type { ExecOptions, ExecResult, IsolationPolicy, SandboxCapability, SandboxRuntime } from "./types.js";
+/**
+ * The minimal surface the sandbox needs to report a first-run image pull
+ * through the U.4 state layer. `StreamRenderer` satisfies it structurally, so
+ * callers pass the renderer directly and the sandbox stays render-decoupled.
+ */
+export interface SandboxReporter {
+    status(text: string | null): void;
+}
+export interface SandboxServiceDeps {
+    config: CruxyConfig;
+    /** The run's working directory — mounted read-write as the workdir. */
+    cwd: string;
+    /** Execution runtime seam (defaults to Docker). */
+    runtime?: SandboxRuntime;
+    /** Capability probe seam (defaults to real docker detection). */
+    detect?: () => Promise<SandboxCapability>;
+    /** U.4 sink for the "pulling sandbox image…" line (optional). */
+    reporter?: SandboxReporter;
+}
+/**
+ * The sandbox execution service (C.16) — what `ToolContext.sandbox` points at.
+ * It is only ever constructed when the sandbox is enabled, and constructing it
+ * is where the fail-loud guarantee lives: {@link SandboxService.create} probes
+ * the runtime and throws {@link sandboxUnavailable} if it isn't available, so a
+ * user who asked for the box either gets the box or a loud, coded error — never
+ * a silent drop back to host execution. `exec` then contains an approved
+ * command inside the isolation policy, ensuring the image on first use.
+ */
+export declare class SandboxService {
+    private readonly runtime;
+    private readonly policy;
+    private readonly reporter?;
+    private imageReady?;
+    private constructor();
+    /**
+     * Resolve the runtime and build the policy. THROWS {@link sandboxUnavailable}
+     * when the runtime is missing/unreachable — the caller (session wiring) lets
+     * it propagate so the run stops before any command executes. There is no code
+     * path from here to host execution.
+     */
+    static create(deps: SandboxServiceDeps): Promise<SandboxService>;
+    /** The runtime backing this service (e.g. "docker") — for logging. */
+    get runtimeName(): string;
+    /** The resolved isolation policy — exposed for logging/inspection. */
+    get isolationPolicy(): IsolationPolicy;
+    /**
+     * Execute an already-approved command inside the box. Ensures the image once
+     * (surfacing the pull via U.4), then delegates to the runtime. A container
+     * that fails to start throws a coded error; an ordinary non-zero command exit
+     * comes back as a normal {@link ExecResult} — exit code is truth.
+     */
+    exec(command: string, opts: ExecOptions): Promise<ExecResult>;
+    /** Ensure the image is present, at most once per service (memoized). */
+    private ensureImage;
+}

package/dist/sandbox/service.js

@@ -0,0 +1,64 @@
+import { sandboxUnavailable } from "../errors/index.js";
+import { detectDocker } from "./detect.js";
+import { DockerRuntime } from "./docker-runtime.js";
+import { buildPolicy } from "./policy.js";
+/**
+ * The sandbox execution service (C.16) — what `ToolContext.sandbox` points at.
+ * It is only ever constructed when the sandbox is enabled, and constructing it
+ * is where the fail-loud guarantee lives: {@link SandboxService.create} probes
+ * the runtime and throws {@link sandboxUnavailable} if it isn't available, so a
+ * user who asked for the box either gets the box or a loud, coded error — never
+ * a silent drop back to host execution. `exec` then contains an approved
+ * command inside the isolation policy, ensuring the image on first use.
+ */
+export class SandboxService {
+    runtime;
+    policy;
+    reporter;
+    imageReady;
+    constructor(runtime, policy, reporter) {
+        this.runtime = runtime;
+        this.policy = policy;
+        this.reporter = reporter;
+    }
+    /**
+     * Resolve the runtime and build the policy. THROWS {@link sandboxUnavailable}
+     * when the runtime is missing/unreachable — the caller (session wiring) lets
+     * it propagate so the run stops before any command executes. There is no code
+     * path from here to host execution.
+     */
+    static async create(deps) {
+        const runtime = deps.runtime ?? new DockerRuntime();
+        const detect = deps.detect ?? (() => detectDocker());
+        const capability = await detect();
+        if (!capability.available) {
+            throw sandboxUnavailable(capability.runtime, capability.detail);
+        }
+        const policy = buildPolicy(deps.config.sandbox, deps.cwd);
+        return new SandboxService(runtime, policy, deps.reporter);
+    }
+    /** The runtime backing this service (e.g. "docker") — for logging. */
+    get runtimeName() {
+        return this.runtime.name;
+    }
+    /** The resolved isolation policy — exposed for logging/inspection. */
+    get isolationPolicy() {
+        return this.policy;
+    }
+    /**
+     * Execute an already-approved command inside the box. Ensures the image once
+     * (surfacing the pull via U.4), then delegates to the runtime. A container
+     * that fails to start throws a coded error; an ordinary non-zero command exit
+     * comes back as a normal {@link ExecResult} — exit code is truth.
+     */
+    async exec(command, opts) {
+        await this.ensureImage();
+        return this.runtime.exec(command, this.policy, opts);
+    }
+    /** Ensure the image is present, at most once per service (memoized). */
+    ensureImage() {
+        return (this.imageReady ??= this.runtime
+            .ensureImage(this.policy.image, () => this.reporter?.status(`pulling sandbox image ${this.policy.image}…`))
+            .then(() => this.reporter?.status(null)));
+    }
+}

package/dist/sandbox/types.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Sandbox execution (C.16) — the isolation boundary beneath the U.3 gate.
+ *
+ * When the sandbox is enabled, the highest-risk tools (`run_command`,
+ * `run_tests`) execute inside a container instead of directly on the host: the
+ * project workdir is mounted so the agent edits real files, but the *process*
+ * cannot reach the network, cannot touch the host beyond that mount, and cannot
+ * exhaust the machine. Approval still gates every command (see U.3) — the
+ * sandbox contains what an approved command is able to do; it does not replace
+ * the decision to run it.
+ *
+ * Execution is abstracted behind {@link SandboxRuntime} (Docker ships; podman /
+ * none slot in without touching call sites), and the neutral {@link ExecResult}
+ * matches what host execution conceptually returns so `run_command`/`run_tests`
+ * stay substrate-agnostic — exit code is the source of truth on either path.
+ */
+/** Egress policy for the container. `none` is the default (deny all). */
+export type NetworkPolicy = "none" | "host-loopback" | "full";
+/** One resolved bind mount: an absolute host path exposed in the container. */
+export interface BindMount {
+    /** Absolute host path. */
+    readonly source: string;
+    /** Absolute container path (the workdir mount uses `source === target`). */
+    readonly target: string;
+    /** Read-only when true; the workdir mount is read-write. */
+    readonly readonly: boolean;
+}
+/**
+ * A fully-resolved isolation policy — every knob the runtime needs, already
+ * merged from config and validated. `docker-runtime` turns this (plus the
+ * command) into an argv; nothing here is optional or defaulted downstream.
+ */
+export interface IsolationPolicy {
+    /** Pinned base image the container runs (never chosen dynamically). */
+    readonly image: string;
+    /** Egress policy — `none` unless the user deliberately widened it. */
+    readonly network: NetworkPolicy;
+    /** Non-root `uid:gid` the container runs as (host uid, so mounts stay writable). */
+    readonly user: string;
+    /** Memory cap (`--memory`, also mirrored to `--memory-swap` to disable swap). */
+    readonly memory: string;
+    /** Process/thread cap (`--pids-limit`). */
+    readonly pids: number;
+    /** CPU cap (`--cpus`, fractional allowed). */
+    readonly cpus: number;
+    /** The project workdir, mounted read-write at the identical absolute path. */
+    readonly workdir: 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. */
+    readonly tmpfs: string;
+}
+/** Which end of the output to keep when the byte cap is exceeded. */
+export type CaptureBias = "head" | "tail";
+/** Per-exec bounds handed to a runtime. */
+export interface ExecOptions {
+    /** Host project directory → bind-mounted as the workdir (same absolute path). */
+    readonly cwd: string;
+    /** Wall-clock timeout in ms; overrun kills the container and returns a failure. */
+    readonly timeoutMs: number;
+    /** Cap on combined stdout+stderr bytes captured. */
+    readonly maxOutputBytes: number;
+    /**
+     * Head-bias keeps the start of the output (`run_command`); tail-bias keeps
+     * the end, where test runners print their failure summaries (`run_tests`).
+     */
+    readonly capture: CaptureBias;
+}
+/**
+ * The neutral outcome of one sandboxed execution — the SAME shape host
+ * execution conceptually produces, so both `run_command` and `run_tests` map it
+ * to their own result type without caring which substrate ran the command.
+ */
+export interface ExecResult {
+    /** Process exit code; `null` on a signal kill / timeout. Exit code is truth. */
+    readonly exitCode: number | null;
+    /** Combined stdout+stderr, already bias-capped to `maxOutputBytes`. */
+    readonly output: string;
+    /** True when output was dropped to honor the cap. */
+    readonly outputTruncated: boolean;
+    /** Measured wall-clock duration of the execution. */
+    readonly durationMs: number;
+    /** True when the wall-clock timeout fired and the container was killed. */
+    readonly timedOut: boolean;
+}
+/**
+ * The swappable execution seam. Docker ships as {@link DockerRuntime}; a future
+ * podman/other runtime implements this without touching the tools or service.
+ * `exec` never falls back to the host and never throws for an ordinary non-zero
+ * command exit — it throws only when the container itself cannot run (a coded
+ * {@link CruxyError}), so the fail-loud guarantee is structural.
+ */
+export interface SandboxRuntime {
+    /** Identifier surfaced in errors/logs (e.g. "docker"). */
+    readonly name: string;
+    /**
+     * Ensure `image` is present locally, pulling it if needed. `onPull` fires
+     * once, only if a pull actually starts (so callers can surface it via U.4).
+     * Throws a coded {@link CruxyError} on pull/build failure — never silently
+     * substitutes another image.
+     */
+    ensureImage(image: string, onPull?: () => void): Promise<void>;
+    /** Run `command` inside the box under `policy`, returning a neutral result. */
+    exec(command: string, policy: IsolationPolicy, opts: ExecOptions): Promise<ExecResult>;
+}
+/** Result of probing for a container runtime; presence is a capability. */
+export interface SandboxCapability {
+    /** True when the runtime binary exists AND its daemon is reachable. */
+    readonly available: boolean;
+    /** The runtime that was probed. */
+    readonly runtime: string;
+    /** Why it's unavailable (for the fail-loud error), when not available. */
+    readonly detail?: string;
+}

package/dist/sandbox/types.js

@@ -0,0 +1,17 @@
+/**
+ * Sandbox execution (C.16) — the isolation boundary beneath the U.3 gate.
+ *
+ * When the sandbox is enabled, the highest-risk tools (`run_command`,
+ * `run_tests`) execute inside a container instead of directly on the host: the
+ * project workdir is mounted so the agent edits real files, but the *process*
+ * cannot reach the network, cannot touch the host beyond that mount, and cannot
+ * exhaust the machine. Approval still gates every command (see U.3) — the
+ * sandbox contains what an approved command is able to do; it does not replace
+ * the decision to run it.
+ *
+ * Execution is abstracted behind {@link SandboxRuntime} (Docker ships; podman /
+ * none slot in without touching call sites), and the neutral {@link ExecResult}
+ * matches what host execution conceptually returns so `run_command`/`run_tests`
+ * stay substrate-agnostic — exit code is the source of truth on either path.
+ */
+export {};

package/dist/subagent/orchestrator.d.ts

@@ -3,6 +3,7 @@ import type { ApprovalDecision } from "../approval/types.js";
 import type { CruxyConfig } from "../config/index.js";
 import type { StreamRenderer } from "../render/index.js";
 import type { ApproveAction, ToolContext, ToolRegistry } from "../tools/index.js";
+import type { SandboxService } from "../sandbox/index.js";
 import type { SubagentResult, SubagentSpec } from "./types.js";
 /**
  * Everything a spawn needs from the surrounding session, injected by the
@@ -24,6 +25,12 @@ export interface SubagentOrchestratorDeps {
     } | null;
     projectInstructions?: string | null;
     renderer?: StreamRenderer;
+    /**
+     * The run's sandbox (C.16), when enabled. Threaded into the child ctx so a
+     * subagent's shell/test commands run in the SAME box as the parent's —
+     * sandboxing is never silently dropped for a child.
+     */
+    sandbox?: SandboxService;
     /**
      * Build a fresh, fully-wrapped approval gate for one child run: a NEW
      * `ApprovalService` (so the child gets its own empty session allowlist —

package/dist/subagent/orchestrator.js

@@ -65,6 +65,7 @@ export class SubagentOrchestrator {
                     recordArtifacts(action, artifacts, deps.cwd);
                 return decision;
             },
+            sandbox: deps.sandbox,
         };
         const label = taskLabel(spec.task);
         if (deps.renderer) {