@cruxy/cli 0.12.0 → 0.14.0

package/dist/tools/shell/run-command.js

@@ -26,9 +26,43 @@ export const runCommandTool = {
                 error: decision.feedback ?? "command denied by the user",
             };
         }
-        return runBounded(input.command, ctx);
+        // Substrate is chosen SOLELY by ctx.sandbox: present → run in the box (C.16),
+        // never on the host; absent → host, unchanged. There is no fallback path — a
+        // sandbox that can't run throws a coded error (see runSandboxed) rather than
+        // silently reaching runBounded.
+        return ctx.sandbox
+            ? runSandboxed(input.command, ctx)
+            : runBounded(input.command, ctx);
     },
 };
+/**
+ * Run inside the sandbox and map the neutral ExecResult onto the IDENTICAL
+ * ToolResult the host path produces — same "exit code N" framing, same
+ * truncation note, same timeout message — so the tool is substrate-agnostic.
+ * A container-start / image failure throws a coded CruxyError from
+ * `sandbox.exec` and propagates; we deliberately do not catch it (fail loud).
+ */
+function runSandboxed(command, ctx) {
+    const { timeoutMs, maxOutputBytes } = ctx.config.shell;
+    return ctx
+        .sandbox.exec(command, {
+        cwd: ctx.cwd,
+        timeoutMs,
+        maxOutputBytes,
+        capture: "head",
+    })
+        .then((result) => {
+        if (result.timedOut) {
+            return { ok: false, error: `timed out after ${timeoutMs}ms` };
+        }
+        const exit = result.exitCode ?? "unknown";
+        let output = `exit code ${exit}\n${result.output}`;
+        if (result.outputTruncated) {
+            output += `\n… [output truncated at ${maxOutputBytes} bytes]`;
+        }
+        return { ok: true, output };
+    });
+}
 /** Spawn the command, capture bounded output, and enforce the timeout. */
 function runBounded(command, ctx) {
     const { timeoutMs, maxOutputBytes } = ctx.config.shell;

package/dist/tools/types.d.ts

@@ -1,6 +1,7 @@
 import type { z, ZodTypeAny } from "zod";
 import type { CruxyConfig } from "../config/index.js";
 import type { ApprovalDecision } from "../approval/types.js";
+import type { SandboxService } from "../sandbox/index.js";
 import type { logger } from "../utils/logger.js";
 /** The leveled logger instance shared across the CLI. */
 type Logger = typeof logger;
@@ -131,6 +132,15 @@ export interface ToolContext {
      * tools never call this.
      */
     requestApproval(action: ApproveAction): Promise<ApprovalDecision>;
+    /**
+     * Isolation substrate for the shell + test tools (C.16). Present ONLY when
+     * the sandbox is enabled; when set, `run_command`/`run_tests` execute the
+     * approved command inside the container and NEVER on the host. Its mere
+     * presence is the switch — there is no host fallback once it is set (an
+     * unavailable runtime fails loud at construction, before this is ever
+     * populated). Absent → host execution, unchanged.
+     */
+    sandbox?: SandboxService;
 }
 /**
  * The one interface every tool implements. `parameters` is a zod schema; it both

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {