jeo-code 0.12.13 → 0.12.16

package/src/agent/sandbox/types.ts

@@ -0,0 +1,77 @@
+import type { ToolHandler } from "../engine";
+import type { ToolResult } from "../tools";
+
+export interface SandboxMount {
+  readonly host: string;
+  readonly guest: string;
+  readonly mode: "ro" | "rw";
+}
+
+export interface SandboxLimits {
+  readonly memoryBytes: number;
+  readonly pids: number;
+  readonly cpus: number;
+}
+
+export interface SandboxConfig {
+  readonly image: string;
+  readonly limits: SandboxLimits;
+}
+
+export interface SandboxPolicy {
+  readonly sessionKey: string;
+  readonly revision: number;
+  readonly mounts: readonly SandboxMount[];
+  readonly privatePaths?: readonly string[];
+  readonly config: SandboxConfig;
+  readonly digest: string;
+}
+
+export interface SandboxTermination {
+  readonly gone: boolean;
+  readonly residual: readonly string[];
+}
+
+export interface SandboxProcess {
+  readonly name: string;
+  readonly stdin: { write(data: string): unknown; flush(): unknown; end(): unknown };
+  readonly stdout: ReadableStream<Uint8Array>;
+  readonly stderr: ReadableStream<Uint8Array>;
+  readonly exited: Promise<number>;
+  stop(): Promise<SandboxTermination>;
+}
+
+export interface SandboxBackend {
+  preflight(config: SandboxConfig): Promise<{ imageId: string; platform: string }>;
+  launch(policy: SandboxPolicy, bundlePath: string): Promise<SandboxProcess>;
+}
+
+export interface SandboxCallOptions {
+  cwd?: string;
+  signal?: AbortSignal;
+  onProgress?: (text: string) => void;
+}
+
+export interface SandboxExecOptions {
+  cwd?: string;
+  env?: Record<string, string>;
+  stdin?: string;
+  signal?: AbortSignal;
+}
+
+export interface SandboxExecResult extends ToolResult {
+  stdout?: string;
+  stderr?: string;
+  exitCode?: number | null;
+  timedOut?: boolean;
+  aborted?: boolean;
+}
+
+export interface SandboxSupervisor {
+  toolMap(names: readonly string[]): Record<string, ToolHandler>;
+  call(tool: string, args: Record<string, unknown>, options?: SandboxCallOptions): Promise<ToolResult>;
+  exec(argv: readonly string[], options?: SandboxExecOptions): Promise<SandboxExecResult>;
+  replacePolicy(policy: SandboxPolicy): Promise<void>;
+  revoke(): Promise<SandboxTermination>;
+  close(): Promise<void>;
+}

package/src/agent/shell-lease.ts

@@ -0,0 +1,190 @@
+/**
+ * Process-group-safe shell spawn for background jobs and monitors.
+ *
+ * A bare `bash -c <command>` is its own process-group leader (`detached`), but the
+ * moment that shell is reaped its PGID becomes reusable by an unrelated process. Any
+ * later `kill(-pgid)` could then hit a stranger's group. So on POSIX the registries
+ * never signal a group whose leader has been reaped, and the user's command runs as
+ * a CHILD of a small "lease holder" shell that stays alive — keeping the PGID pinned
+ * (the kernel never reuses a pid/pgid while a group member, zombies included, exists)
+ * — until the registry explicitly `release()`s it:
+ *
+ *   - exit status travels through a private status file (stdout/stderr EOF cannot carry
+ *     it, and a descendant holding those pipes would delay it indefinitely; Bun's extra
+ *     stdio pipes are unreliable on Linux, so no fd beyond 0-2 is used);
+ *   - the holder closes its own stdout/stderr first, so only real descendants keep
+ *     the output pipes open;
+ *   - release is "stdin closed"; the holder only reads it after the command exits, so a
+ *     registry that dies does NOT clean up a still-running command (same as before the lease).
+ *
+ * `killGroup()` is the only place a group signal is sent. It refuses once the holder
+ * is gone or released (`"unpinned"`), so callers report an unconfirmed termination
+ * instead of signalling a possibly reused PGID. A delivered SIGKILL reaches every
+ * member of the pinned group atomically; descendants that left the group (`setsid`)
+ * are not reachable and show up as output pipes that stay open; a descendant that left
+ * the group AND closed both pipes is undetectable, so EOF alone never proves it ended.
+ *
+ * Residual window (cannot be closed from JS): the holder dying — only by an external
+ * or in-command group/SIGKILL — and its pid wrapping around before the exit event
+ * reaches this process.
+ *
+ * Windows has no process groups here: `killGroup()` is `"unsupported"` and callers
+ * must keep the job unresolved.
+ */
+import * as cp from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { Readable } from "node:stream";
+
+export interface ShellReader {
+  read(): Promise<{ done?: boolean; value?: Uint8Array }>;
+  cancel(): Promise<void>;
+}
+
+export type GroupKill = "delivered" | "unpinned" | "unsupported" | { error: unknown };
+
+export interface LeasedShell {
+  readonly stdout: ShellReader;
+  readonly stderr: ShellReader;
+  /** The command's exit code; `null` when the lease holder ended without reporting one. */
+  readonly exit: Promise<number | null>;
+  /** Settles once the OS process owning the group (or the direct shell) is reaped. */
+  readonly reaped: Promise<void>;
+  /** SIGKILL the pinned group; never signals an unpinned or released group. */
+  killGroup(): GroupKill;
+  /** Best-effort single-process kill; proves nothing about descendants. */
+  killDirect(): void;
+  /** Let the holder exit. After this, `killGroup()` reports `"unpinned"`. */
+  release(): void;
+  /** Free pipe handles after the process is reaped. */
+  dispose(): void;
+}
+
+/** Resolve true if `promise` settles within `ms`, else false. */
+export async function settlesWithin(promise: Promise<unknown>, ms: number): Promise<boolean> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      promise.then(() => true),
+      new Promise<false>(resolve => { timer = setTimeout(() => resolve(false), ms); }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// $1 = command, $2 = status file, $3 = caller's BASH_ENV. fd0 is the release pipe and never reaches the
+// command. The holder's own stderr goes to /dev/null (its "Killed" job notices are not command output) and
+// BASH_ENV is withheld from the holder itself, so a startup file runs once, inside the command's shell.
+const HOLDER_SCRIPT = [
+  "exec 9>&2 2>/dev/null",
+  'if [ -n "$3" ]; then export BASH_ENV="$3"; fi',
+  'bash -c "$1" bash 0</dev/null 2>&9 9>&-',
+  "c=$?",
+  "exec 1>&- 9>&-",
+  "printf '%s\\n' \"$c\" > \"$2\" || exit \"$c\"", // unreportable: end the lease instead of waiting forever
+  "read -r _",
+  'exit "$c"',
+].join("\n");
+
+const STATUS_POLL_MIN_MS = 5;
+const STATUS_POLL_MAX_MS = 50;
+
+export function spawnLeasedShell(command: string, cwd: string): LeasedShell {
+  return process.platform === "win32" ? spawnDirect(command, cwd) : spawnLeased(command, cwd);
+}
+
+function spawnDirect(command: string, cwd: string): LeasedShell {
+  const proc = Bun.spawn(["bash", "-c", command], { cwd, stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+  const stdout = proc.stdout.getReader();
+  const stderr = proc.stderr.getReader();
+  const reaped = proc.exited.then(() => undefined);
+  return {
+    stdout, stderr,
+    exit: proc.exited,
+    reaped,
+    killGroup: () => "unsupported",
+    killDirect: () => { try { proc.kill(9); } catch { /* best effort only */ } },
+    release: () => {},
+    dispose: () => { void stdout.cancel().catch(() => {}); void stderr.cancel().catch(() => {}); },
+  };
+}
+
+function spawnLeased(command: string, cwd: string): LeasedShell {
+  // node:child_process reports a bad cwd inconsistently across Bun versions (an 'error' event on
+  // some, a holder that exits 127 on others); check up front so start() fails like Bun.spawn did.
+  if (!fs.statSync(cwd).isDirectory()) throw new Error(`ENOTDIR: not a directory, stat '${cwd}'`);
+  const leaseDir = fs.mkdtempSync(path.join(os.tmpdir(), "jeo-lease-"));
+  const statusFile = path.join(leaseDir, "status");
+  const cleanup = () => { try { fs.rmSync(leaseDir, { recursive: true, force: true }); } catch { /* best effort only */ } };
+  const { BASH_ENV: userBashEnv, ...env } = process.env;
+  let child: cp.ChildProcess;
+  try {
+    child = cp.spawn("bash", ["-c", HOLDER_SCRIPT, "bash", command, statusFile, userBashEnv ?? ""], {
+      cwd, env, detached: true, stdio: ["pipe", "pipe", "pipe"],
+    });
+  } catch (error) { cleanup(); throw error; }
+  child.on("error", () => {});
+  if (child.pid === undefined) { cleanup(); throw new Error('Executable not found in $PATH: "bash"'); }
+  const pid = child.pid;
+  const stdin = child.stdin!;
+  stdin.on("error", () => {});
+
+  let gone = false;
+  let released = false;
+  let delivered = false;
+  const reaped = new Promise<void>(resolve => {
+    child.once("exit", () => { gone = true; resolve(); });
+    child.once("error", () => { gone = true; resolve(); });
+  });
+
+  const readStatus = (): number | null => {
+    try {
+      const match = /^(\d{1,3})\n$/.exec(fs.readFileSync(statusFile, "utf8"));
+      return match ? Number(match[1]) : null;
+    } catch { return null; }
+  };
+  // Poll with backoff: no fd beyond 0-2 and no fs.watch, both unreliable on Bun/Linux. The holder
+  // writes the file only after the command exits and stays alive until released, so a reported
+  // status always comes from a pinned group; none by the time the holder is reaped means a lost lease.
+  const exit = new Promise<number | null>(resolve => {
+    let delay = STATUS_POLL_MIN_MS;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const settle = (code: number | null) => { clearTimeout(timer); resolve(code); };
+    const tick = () => {
+      const code = readStatus();
+      if (code !== null) return settle(code);
+      if (gone) return settle(null);
+      delay = Math.min(delay * 2, STATUS_POLL_MAX_MS);
+      timer = setTimeout(tick, delay);
+    };
+    timer = setTimeout(tick, delay);
+    void reaped.then(() => { clearTimeout(timer); tick(); });
+  });
+
+  const reader = (stream: Readable): ShellReader => {
+    const web = Readable.toWeb(stream).getReader();
+    return { read: () => web.read(), cancel: () => web.cancel() };
+  };
+  const stdout = reader(child.stdout!);
+  const stderr = reader(child.stderr!);
+
+  return {
+    stdout, stderr, exit, reaped,
+    killGroup(): GroupKill {
+      if (delivered) return "delivered"; // the whole group already holds SIGKILL
+      if (gone || released || child.exitCode !== null || child.signalCode !== null) return "unpinned";
+      try { process.kill(-pid, "SIGKILL"); delivered = true; return "delivered"; }
+      catch (error) { return (error as NodeJS.ErrnoException).code === "ESRCH" ? "unpinned" : { error }; }
+    },
+    killDirect() { try { child.kill("SIGKILL"); } catch { /* best effort only */ } },
+    release() { released = true; stdin.end(); },
+    dispose() {
+      void stdout.cancel().catch(() => {});
+      void stderr.cancel().catch(() => {});
+      stdin.destroy();
+      cleanup();
+    },
+  };
+}

package/src/agent/state.ts

@@ -6,6 +6,25 @@ import type { AuthProvider } from "../auth/storage";
 import { OPENAI_COMPAT_PROVIDERS } from "../ai/providers/openai-compatible-catalog";
 import { resolveCustomApiKey, setCustomProviders, type CustomProviderConfig } from "../ai/providers/custom-providers";
 import { jeoEnv } from "../util/env";
+import type { SandboxConfig } from "./sandbox/types";
+import { currentSandboxExecution } from "./hooks";
+import { discoverAgentGuidanceFiles, loadProjectContext } from "./context-files";
+import type { ToolHandler } from "./engine";
+import { createTodoTool, type TodoItem } from "./todo-tool";
+import { executeMemoryOperation } from "./memory";
+import { executeSkillCatalogOperation } from "../skills/catalog";
+import { encodeHandsFrame, MAX_FRAME_BYTES } from "./sandbox/rpc";
+import { readGoalFile, clearGoalState } from "./goal-verifier";
+import { inspectApprovalPath } from "../commands/approve";
+
+/** Only workspace workflow data crosses this boundary; global config stays in the brain. */
+async function sandboxWorkflow<T>(operation: string, args: Record<string, unknown>, cwd: string): Promise<T> {
+  const sandbox = currentSandboxExecution();
+  if (!sandbox) throw new Error("SANDBOX_WORKFLOW: missing execution scope");
+  const result = await sandbox.supervisor.call("__workflow", { operation, ...args }, { cwd, signal: sandbox.signal });
+  if (!result.success) throw new Error(result.error || "SANDBOX_WORKFLOW: operation failed");
+  return JSON.parse(result.output) as T;
+}
 
 /** Persisted OAuth credential set (access + refresh + expiry) for a provider. */
 export interface StoredOAuth {
@@ -57,6 +76,8 @@ export interface Config {
    *  overrides. Resolve with `resolveWikiRoot()`. */
   wikiRoot?: string;
   theme?: string;
+  /** Explicit local container image and finite session resource limits; never auto-pulled. */
+  sandbox?: SandboxConfig;
   /** Terminal-bell notifications (gajae-code 0.7.8 parity). `bell` is the master
    *  toggle; per-event flags refine it. Env `JEO_NOTIFY_BELL=1/0` force-overrides. */
   notify?: {
@@ -582,6 +603,10 @@ export function getLocalJeoDir(cwd: string = process.cwd()): string {
  *  correctness requirement — a missing .gitignore degrades gracefully to "no
  *  ignore", not a broken feature). */
 export async function ensureJeoGitignore(cwd: string = process.cwd()): Promise<void> {
+  if (currentSandboxExecution()) {
+    await sandboxWorkflow("ensureGitignore", {}, cwd);
+    return;
+  }
   const gitignorePath = path.join(getLocalJeoDir(cwd), ".gitignore");
   try {
     await fs.access(gitignorePath);
@@ -654,6 +679,7 @@ export async function readWorkflowState(
   skill: "deep-interview" | "ralplan" | "team" | "ultragoal",
   cwd: string = process.cwd()
 ): Promise<WorkflowState | null> {
+  if (currentSandboxExecution()) return sandboxWorkflow("read", { skill }, cwd);
   const statePath = path.join(getLocalJeoDir(cwd), "state", `${skill}-state.json`);
   return loadWorkflowStateFile(statePath, false);
 }
@@ -667,6 +693,7 @@ export async function readWorkflowStateStrict(
   skill: "deep-interview" | "ralplan" | "team" | "ultragoal",
   cwd: string = process.cwd()
 ): Promise<WorkflowState | null> {
+  if (currentSandboxExecution()) return sandboxWorkflow("readStrict", { skill }, cwd);
   const statePath = path.join(getLocalJeoDir(cwd), "state", `${skill}-state.json`);
   return loadWorkflowStateFile(statePath, true);
 }
@@ -676,6 +703,7 @@ export async function writeWorkflowState(
   state: WorkflowState,
   cwd: string = process.cwd()
 ): Promise<string> {
+  if (currentSandboxExecution()) return sandboxWorkflow("write", { skill, state }, cwd);
   const stateDir = path.join(getLocalJeoDir(cwd), "state");
   await fs.mkdir(stateDir, { recursive: true });
   const statePath = path.join(stateDir, `${skill}-state.json`);
@@ -705,6 +733,10 @@ export async function clearWorkflowState(
   skill: "deep-interview" | "ralplan" | "team" | "ultragoal",
   cwd: string = process.cwd()
 ): Promise<void> {
+  if (currentSandboxExecution()) {
+    await sandboxWorkflow("clear", { skill }, cwd);
+    return;
+  }
   const statePath = path.join(getLocalJeoDir(cwd), "state", `${skill}-state.json`);
   try {
     await fs.unlink(statePath);
@@ -736,6 +768,19 @@ export async function acquireWorkflowRunLock(
   skill: "team" | "ultragoal",
   cwd: string = process.cwd(),
 ): Promise<() => Promise<void>> {
+  if (currentSandboxExecution()) {
+    const sandbox = currentSandboxExecution()!;
+    const token = await sandboxWorkflow<unknown>("acquireLock", { skill }, cwd);
+    if (typeof token !== "string" || !token) throw new Error("SANDBOX_WORKFLOW: invalid lock token");
+    let released = false;
+    return async () => {
+      if (released) return;
+      // Capture the owning supervisor: release can run after its caller's ALS scope ends.
+      const result = await sandbox.supervisor.call("__workflow", { operation: "releaseLock", token }, { cwd });
+      if (!result.success) throw new Error(result.error || "SANDBOX_WORKFLOW: lock release failed");
+      released = true;
+    };
+  }
   const stateDir = path.join(getLocalJeoDir(cwd), "state");
   await fs.mkdir(stateDir, { recursive: true });
   const lockPath = path.join(stateDir, `${skill}.lock`);
@@ -781,6 +826,128 @@ export async function acquireWorkflowRunLock(
   throw new Error(`could not acquire ${lockPath} even after stale-lock takeover.`);
 }
 
+/** Read exact UTF-8 workflow bytes; never feed a silently truncated plan into an executor. */
+export async function readWorkflowFile(filePath: string, cwd: string = process.cwd()): Promise<string> {
+  if (currentSandboxExecution()) return sandboxWorkflow("readFile", { path: filePath }, cwd);
+  const file = await fs.open(path.resolve(cwd, filePath), "r");
+  let content: string;
+  try {
+    const stat = await file.stat();
+    if (!stat.isFile() || stat.size > MAX_FRAME_BYTES) throw new Error("Workflow file exceeds bounded sandbox transport or is not a regular file");
+    const bytes = Buffer.allocUnsafe(stat.size + 1);
+    let length = 0;
+    while (length < bytes.length) {
+      const chunk = await file.read(bytes, length, bytes.length - length, length);
+      if (chunk.bytesRead === 0) break;
+      length += chunk.bytesRead;
+    }
+    if (length !== stat.size) throw new Error("Workflow file changed during read");
+    content = new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, length));
+  } finally { await file.close(); }
+  // The nested JSON string must fit the final RPC envelope, including its largest permitted identity.
+  encodeHandsFrame({ id: "x".repeat(256), type: "result", result: { success: true, output: JSON.stringify(content) } });
+  return content;
+}
+
+/** Atomically publish a workflow artifact through the same guest filesystem boundary as tool writes. */
+export async function writeWorkflowFile(filePath: string, content: string, cwd: string = process.cwd()): Promise<void> {
+  if (currentSandboxExecution()) { await sandboxWorkflow("writeFile", { path: filePath, content }, cwd); return; }
+  if (Buffer.byteLength(content, "utf8") > MAX_FRAME_BYTES) throw new Error("Workflow file exceeds bounded sandbox transport");
+  const target = path.resolve(cwd, filePath);
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  const temporary = path.join(path.dirname(target), `.jeo-workflow-${crypto.randomUUID()}.tmp`);
+  try {
+    await fs.writeFile(temporary, content, { flag: "wx", mode: 0o600 });
+    await fs.rename(temporary, target);
+  } catch (error) {
+    try { await fs.unlink(temporary); }
+    catch (cleanupError) { if ((cleanupError as NodeJS.ErrnoException).code !== "ENOENT") throw new AggregateError([error, cleanupError], "Workflow artifact write and temporary cleanup failed"); }
+    throw error;
+  }
+}
+
+/** Create once per hands worker so opaque lock tokens retain their guest-held release callbacks. */
+export function createWorkflowStateTool(): ToolHandler {
+  const locks = new Map<string, () => Promise<void>>();
+  let todos: TodoItem[] = [];
+  const todo = createTodoTool({ onChange: items => { todos = items; } });
+  return async (args, cwd) => {
+    if (currentSandboxExecution()) throw new Error("SANDBOX_WORKFLOW: guest handler cannot run in the brain");
+    try {
+      let value: unknown = null;
+      switch (args.operation) {
+        case "readGoal": value = await readGoalFile(cwd); break;
+        case "clearGoal": await clearGoalState(cwd); break;
+        case "approvalPath": {
+          if (typeof args.path !== "string") throw new Error("Invalid approval path");
+          value = await inspectApprovalPath(args.path, cwd);
+          break;
+        }
+        case "readFile": {
+          if (typeof args.path !== "string") throw new Error("Invalid workflow file path");
+          value = await readWorkflowFile(args.path, cwd);
+          break;
+        }
+        case "writeFile": {
+          if (typeof args.path !== "string" || typeof args.content !== "string") throw new Error("Invalid workflow file write");
+          await writeWorkflowFile(args.path, args.content, cwd);
+          break;
+        }
+        case "memory": {
+          if (typeof args.action !== "string") throw new Error("Invalid memory action");
+          value = await executeMemoryOperation(args.action, args, cwd);
+          break;
+        }
+        case "skillCatalog": value = await executeSkillCatalogOperation(args, cwd); break;
+        case "loadContext": value = await loadProjectContext(cwd); break;
+        case "discoverGuidance": value = await discoverAgentGuidanceFiles(cwd); break;
+        case "ensureGitignore": await ensureJeoGitignore(cwd); break;
+        case "todo": {
+          if (!args.args || typeof args.args !== "object" || Array.isArray(args.args)) throw new Error("Invalid todo arguments");
+          value = { result: await todo(args.args, cwd), todos };
+          break;
+        }
+        case "releaseLock": {
+          if (typeof args.token !== "string") throw new Error("Invalid workflow lock token");
+          const release = locks.get(args.token);
+          if (!release) throw new Error("Unknown workflow lock token");
+          await release();
+          locks.delete(args.token);
+          break;
+        }
+        default: {
+          const skill = args.skill;
+          if (skill !== "deep-interview" && skill !== "ralplan" && skill !== "team" && skill !== "ultragoal") {
+            throw new Error("Invalid workflow skill");
+          }
+          switch (args.operation) {
+            case "read": value = await readWorkflowState(skill, cwd); break;
+            case "readStrict": value = await readWorkflowStateStrict(skill, cwd); break;
+            case "write": {
+              if (!args.state || typeof args.state !== "object" || Array.isArray(args.state)) throw new Error("Invalid workflow state");
+              value = await writeWorkflowState(skill, args.state as WorkflowState, cwd);
+              break;
+            }
+            case "clear": await clearWorkflowState(skill, cwd); break;
+            case "acquireLock": {
+              if (skill !== "team" && skill !== "ultragoal") throw new Error("Invalid run-lock skill");
+              const release = await acquireWorkflowRunLock(skill, cwd);
+              const token = crypto.randomUUID();
+              locks.set(token, release);
+              value = token;
+              break;
+            }
+            default: throw new Error("Unknown workflow operation");
+          }
+        }
+      }
+      return { success: true, output: JSON.stringify(value) };
+    } catch (error) {
+      return { success: false, output: "", error: error instanceof Error ? error.message : String(error) };
+    }
+  };
+}
+
 /** Returns true if the agent is running in development mode (enables self-improvement). */
 export function isDevMode(): boolean {
   return jeoEnv("DEV_MODE") === "1" || process.env.NODE_ENV === "development";

package/src/agent/subagents.ts

@@ -9,7 +9,7 @@
  * review/plan lane physically cannot edit the repo, mirroring gjc's read-only
  * role agents.
  */
-import { DEFAULT_TOOLS, TOOL_PROTOCOL, READONLY_TOOL_PROTOCOL, WORKING_DISCIPLINE, type ToolHandler } from "./engine";
+import { DEFAULT_TOOLS, SANDBOX_MEDIATED_TOOLS, TOOL_PROTOCOL, READONLY_TOOL_PROTOCOL, WORKING_DISCIPLINE, type ToolHandler } from "./engine";
 import type { Config } from "./state";
 import type { CatalogModel } from "../ai/model-catalog";
 import architectPrompt from "../prompts/agents/architect.md" with { type: "text" };
@@ -304,7 +304,7 @@ export function subagentToolset(role: SubagentRole): Record<string, ToolHandler>
   if (prefixes && prefixes.length > 0) {
     const inner = DEFAULT_TOOLS.bash;
     const guarded: Record<string, ToolHandler> = { ...DEFAULT_TOOLS };
-    guarded.bash = async (a, cwd) => {
+    guarded.bash = async (a, cwd, onProgress) => {
       const command = String(a.command ?? a.cmd ?? "");
       if (!bashCommandAllowed(command, prefixes)) {
         return {
@@ -315,8 +315,9 @@ export function subagentToolset(role: SubagentRole): Record<string, ToolHandler>
             `Received: ${command.trim().slice(0, 120)}`,
         };
       }
-      return inner(a, cwd);
+      return inner(a, cwd, onProgress);
     };
+    SANDBOX_MEDIATED_TOOLS.add(guarded.bash);
     return guarded;
   }
   return DEFAULT_TOOLS;

package/src/agent/task-tool.ts

@@ -35,6 +35,7 @@ import type { SubagentRegistry } from "./subagent-registry";
 import { ensureSessionNotifyEndpoint, type SessionNotifyEndpoint } from "./notify/session-endpoint";
 import { inferTierForModel, tierModelPool, credentialScopeFor, selectFromPool, strongestMidTierCredentialed, type RoutingConfig } from "./prompt-router";
 import { isRateLimitError } from "../util/retry";
+import { currentSandboxExecution, withSandboxExecution, type SandboxExecutionScope } from "./hooks";
 
 /** `runSubagentOnce`/`createTaskTool`'s config requirement: everything
  *  `resolveSubagentModel`/`resolveSubagentMaxSteps`/`resolveSubagentThinking` need
@@ -100,6 +101,7 @@ export interface TaskToolOptions {
    *  one — a detached launch attaches `registry` to THIS instead of starting a
    *  second, competing endpoint (see `ensureSessionNotifyEndpoint`). */
   sessionEndpoint?: SessionNotifyEndpoint;
+  sandbox?: SandboxExecutionScope;
 }
 
 /** Max concurrent subagents in a fan-out batch (both read-only AND the mutating
@@ -281,6 +283,7 @@ export interface RunSubagentOptions {
   detachedId?: string;
   /** SubagentRegistry to report live activity into (e.g. current tool or step). */
   registry?: SubagentRegistry;
+  sandbox?: SandboxExecutionScope;
 }
 
 
@@ -332,6 +335,9 @@ export async function runSubagentOnce(
   cwd: string,
   opts: RunSubagentOptions,
 ): Promise<SubagentRunResult> {
+  if (opts.sandbox && currentSandboxExecution() !== opts.sandbox) {
+    return withSandboxExecution(opts.sandbox, () => runSubagentOnce(role, taskText, context, cwd, opts));
+  }
   const { steer, slot, detachedId, projectContext: preloadedContext, signal } = opts;
   // Tag every live event with its fan-out slot or detached ID so a parent monitor can tell
   // task 1 from task 3 or detached tasks apart when several subagents stream concurrently.
@@ -616,6 +622,7 @@ export async function runSubagentOnce(
  * handler accepts `{ role?, task | prompt | assignment, context? }`.
  */
 export function createTaskTool(opts: TaskToolOptions): ToolHandler {
+  const sandbox = opts.sandbox ?? currentSandboxExecution();
   /** Run ONE subagent via the shared execution core, binding this tool instance's
    *  config/signal/onEvent (the original single-task path). */
   const runOne = (
@@ -643,6 +650,7 @@ export function createTaskTool(opts: TaskToolOptions): ToolHandler {
   ): Promise<SubagentRunResult> =>
     runSubagentOnce(role, taskText, context, cwd, {
       config: opts.config,
+      sandbox,
       signal: extra.signal ?? opts.signal,
       onEvent: opts.onEvent,
       steer: extra.steer,

package/src/agent/todo-tool.ts

@@ -10,6 +10,7 @@
  */
 import type { ToolHandler } from "./engine";
 import type { ToolResult } from "./tools";
+import { currentSandboxExecution } from "./hooks";
 
 export type TodoStatus = "pending" | "in_progress" | "done";
 
@@ -23,6 +24,20 @@ export interface TodoToolOptions {
   onChange?: (items: TodoItem[]) => void;
 }
 
+interface SandboxTodoReply {
+  result: ToolResult;
+  todos: TodoItem[];
+}
+
+function isSandboxTodoReply(value: unknown): value is SandboxTodoReply {
+  if (!value || typeof value !== "object") return false;
+  const { result, todos } = value as Partial<SandboxTodoReply>;
+  return !!result && typeof result.success === "boolean" && typeof result.output === "string" &&
+    (result.error === undefined || typeof result.error === "string") && Array.isArray(todos) &&
+    todos.every(item => !!item && typeof item.title === "string" &&
+      (item.status === "pending" || item.status === "in_progress" || item.status === "done"));
+}
+
 /** One-line protocol description appended to the launch system prompt. */
 export const TODO_TOOL_PROTOCOL_LINE =
   `todo   {todos:[{title,status}]}  — declare/update your task plan ` +
@@ -70,7 +85,21 @@ export function renderTodoChecklist(items: TodoItem[]): string {
 /** Build a `todo` ToolHandler. Maintains the current list in a closure. */
 export function createTodoTool(opts: TodoToolOptions = {}): ToolHandler {
   let current: TodoItem[] = [];
-  return async (args: Record<string, any>): Promise<ToolResult> => {
+  return async (args: Record<string, any>, cwd: string): Promise<ToolResult> => {
+    const sandbox = currentSandboxExecution();
+    if (sandbox) {
+      const response = await sandbox.supervisor.call("__workflow", { operation: "todo", args }, { cwd, signal: sandbox.signal });
+      if (!response.success) return response;
+      const reply: unknown = JSON.parse(response.output);
+      if (!isSandboxTodoReply(reply)) throw new Error("SANDBOX_TODO: invalid guest response");
+      // Parent callback is presentation only; normalization and plan mutation ran in hands.
+      if (reply.result.success) opts.onChange?.(reply.todos);
+      return {
+        success: reply.result.success,
+        output: reply.result.output,
+        ...(reply.result.error !== undefined ? { error: reply.result.error } : {}),
+      };
+    }
     const items = parseTodoItems(args);
     if (!items) {
       return {

package/src/agent/tool-schemas.ts

@@ -133,6 +133,19 @@ const SCHEMAS: Record<string, NativeToolSchema> = {
       required: ["action"],
     },
   },
+  sandbox_request: {
+    name: "sandbox_request",
+    description: "Request an additional session sandbox mount with host and mode ro|rw, or inspect grants and their guest paths with action=status. This tool cannot approve, reject, or revoke access; only authenticated human /sandbox controls can do that.",
+    parameters: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["request", "status"] },
+        host: STRING,
+        mode: { type: "string", enum: ["ro", "rw"] },
+      },
+      required: [],
+    },
+  },
   done: {
     name: "done",
     description: "Call when the task is fully implemented AND verified. The reason is shown to the user as your message.",