Agent mode phase 1: real sandbox and permission system

Agent mode's only protection against run_command/run_code/background commands was a regex blocklist against command text — no OS-level isolation, no resource limits, and the code's own comments already admitted it "can't catch everything a shell is capable of." This adds two independent layers on top of it:

- Network policy (100% enforceable on every platform, since it just refuses
  to run the tool at all): a new networkToolsEnabled setting gates
  web_search, fetch_url, http_request, capture_page_screenshot, and the
  three GitHub tools in executeTool(). Separately, run_command/run_code/
  start_background_command gained a per-call `network` argument (default
  false) so the model has to explicitly ask for network access on a
  command-by-command basis, visible in the approval card like any other
  argument.

- OS-level containment (app/src/command-sandbox.ts): on Linux, wraps the
  command with bubblewrap (bwrap) when installed — confines filesystem
  writes to the workspace and denies network unless the network argument
  above was set. On macOS, generates a sandbox-exec profile doing the same
  (built into macOS, no install needed). On Windows there's no lightweight
  equivalent primitive (Windows Sandbox needs Pro/Enterprise and is a full
  VM-like container; Job Objects/restricted tokens don't confine filesystem
  or network) — stays on the blocklist plus the resource limits below, and
  the new Settings sandbox-status row says so honestly rather than implying
  protection that isn't there. Every call site falls back to running
  unwrapped when no mechanism is available, never a hard failure.
  Deliberately does NOT offer a plain `unshare --net` fallback on Linux:
  creating a network namespace that way commonly requires privileges a
  normal user doesn't have, which would make sandboxing *break* commands
  instead of just not confining them.

- Resource limits (app/src/resource-monitor.ts, cross-platform via
  pidusage): a safety net against a runaway process — configurable memory
  and CPU caps, generous defaults, killing the whole process tree
  (app/src/process-tree.ts, reused from phase 0) on breach. Complements the
  existing 60s run_command timeout, which never applied to background
  commands at all.

New Settings section (Chat & Prompts → Agent runtime) exposes all of this:
the network-tools toggle, the resource limit inputs, and a read-only status
row reporting exactly what's enforced on the current OS.

34 new tests across command-sandbox.test.ts, resource-monitor.test.ts, and
process-tree.test.ts, plus 2 new agent-tools.test.ts cases for the
workspace-scoped background-task cleanup from phase 0.

Author: voidstackloop

app/package-lock.json

@@ -78,6 +78,7 @@
   "devDependencies": {
     "@types/node": "^26.1.1",
     "@types/pdf-parse": "^1.1.5",
+    "@types/pidusage": "^2.0.5",
     "concurrently": "^10.0.3",
     "cross-env": "^10.1.0",
     "electron": "^43.1.1",
@@ -91,6 +92,7 @@
     "ffmpeg-static": "^5.3.0",
     "node-llama-cpp": "^3.19.1",
     "pdf-parse": "^2.4.5",
+    "pidusage": "^4.0.1",
     "tesseract.js": "^5.1.1"
   }
 }

app/package.json

@@ -8,6 +8,9 @@ import type { ToolDefinition } from "./providers/types";
 import { getAccountToken } from "./accounts";
 import { capturePageScreenshot } from "./browser-capture";
 import { killProcessTree } from "./process-tree";
+import { applySandbox } from "./command-sandbox";
+import { monitorProcess } from "./resource-monitor";
+import * as settingsStore from "./settings-store";
 
 const execAsync = promisify(exec);
 
@@ -131,40 +134,43 @@ export const AGENT_TOOLS: ToolDefinition[] = [
     {
         name: "run_command",
         description:
-            "Execute a shell command in the workspace (or a subdirectory of it) and return its stdout/stderr/exit code. Use for builds, tests, git, npm, etc. Commands that could affect the system outside the workspace (deleting elsewhere, shutting down the machine, privilege escalation, etc.) are rejected.",
+            "Execute a shell command in the workspace (or a subdirectory of it) and return its stdout/stderr/exit code. Use for builds, tests, git, npm, etc. Commands that could affect the system outside the workspace (deleting elsewhere, shutting down the machine, privilege escalation, etc.) are rejected. Runs inside an OS-level sandbox confined to the workspace where the platform supports it (Linux with bubblewrap installed, macOS always) — on Windows this containment isn't available and only the command-text checks above apply.",
         parameters: {
             type: "object",
             properties: {
                 command: { type: "string", description: "The shell command to run." },
                 cwd: { type: "string", description: 'Working directory for the command, relative to the workspace root. Defaults to "."' },
+                network: { type: "boolean", description: "Whether this command needs network access (e.g. npm install, curl). Defaults to false — most commands don't need it." },
             },
             required: ["command"],
         },
     },
     {
         name: "run_code",
         description:
-            "Run a Python or JavaScript code snippet in the workspace and return its stdout/stderr/exit code. A convenience over run_command for multi-line code (no shell-quoting to worry about) — it is not a sandbox: the code runs with the same permissions as run_command and is subject to the same safety checks.",
+            "Run a Python or JavaScript code snippet in the workspace and return its stdout/stderr/exit code. A convenience over run_command for multi-line code (no shell-quoting to worry about) — subject to the same sandboxing (where available) and safety checks as run_command.",
         parameters: {
             type: "object",
             properties: {
                 language: { type: "string", enum: ["python", "javascript"], description: "Which interpreter to run the code with." },
                 code: { type: "string", description: "The full source code to execute." },
                 cwd: { type: "string", description: 'Working directory, relative to the workspace root. Defaults to "."' },
+                network: { type: "boolean", description: "Whether this code needs network access. Defaults to false." },
             },
             required: ["language", "code"],
         },
     },
     {
         name: "start_background_command",
         description:
-            "Start a long-running command (dev server, build watcher, long test run) in the background and return immediately with a task id. Use get_background_output to check on it later and stop_background_command when done — unlike run_command, this doesn't block or time out. Subject to the same safety checks as run_command.",
+            "Start a long-running command (dev server, build watcher, long test run) in the background and return immediately with a task id. Use get_background_output to check on it later and stop_background_command when done — unlike run_command, this doesn't block or time out. Subject to the same safety checks and sandboxing as run_command.",
         parameters: {
             type: "object",
             properties: {
                 command: { type: "string", description: "The shell command to run." },
                 cwd: { type: "string", description: 'Working directory, relative to the workspace root. Defaults to "."' },
                 name: { type: "string", description: "Short human-readable label for this task (e.g. \"dev server\")." },
+                network: { type: "boolean", description: "Whether this command needs network access (e.g. a dev server that fetches data). Defaults to false." },
             },
             required: ["command"],
         },
@@ -784,24 +790,45 @@ function formatCommandResult(stdout: string, stderr: string, exitCode: number |
     return parts.join("\n\n");
 }
 
-export async function runCommand(workspaceRoot: string, command: string, relativeCwd = "."): Promise<string> {
+export async function runCommand(
+    workspaceRoot: string,
+    command: string,
+    relativeCwd = ".",
+    network = false
+): Promise<string> {
     const dangerReason = findDangerousCommandReason(command);
     if (dangerReason) throw new Error(dangerReason);
 
     const cwd = resolveSafePath(workspaceRoot, relativeCwd);
+    const wrappedCommand = applySandbox(command, { workspaceRoot, allowNetwork: network });
+    const settings = settingsStore.getSettings();
+    let stopMonitor = () => {};
     try {
-        const { stdout, stderr } = await execAsync(command, {
+        const execPromise = execAsync(wrappedCommand, {
             cwd,
             timeout: COMMAND_TIMEOUT_MS,
             maxBuffer: 10 * 1024 * 1024,
         });
+        // execPromise.child is a documented feature of promisify(exec) — the
+        // returned promise carries the underlying ChildProcess, which is the
+        // only way to get its pid for resource-monitor.ts to watch.
+        if (execPromise.child.pid) {
+            stopMonitor = monitorProcess(
+                execPromise.child.pid,
+                { maxMemoryMB: settings.sandboxMaxMemoryMB, maxCpuPercent: settings.sandboxMaxCpuPercent },
+                () => execPromise.child.kill()
+            );
+        }
+        const { stdout, stderr } = await execPromise;
         return formatCommandResult(stdout, stderr, 0);
     } catch (err) {
         const e = err as { stdout?: string; stderr?: string; code?: number; killed?: boolean; message: string };
         if (e.killed) {
             return `Command timed out after ${COMMAND_TIMEOUT_MS / 1000}s.\n\n${formatCommandResult(e.stdout ?? "", e.stderr ?? "", e.code ?? null)}`;
         }
         return formatCommandResult(e.stdout ?? "", e.stderr ?? e.message, e.code ?? null);
+    } finally {
+        stopMonitor();
     }
 }
 
@@ -815,7 +842,8 @@ export async function runCode(
     workspaceRoot: string,
     language: "python" | "javascript",
     code: string,
-    relativeCwd = "."
+    relativeCwd = ".",
+    network = false
 ): Promise<string> {
     const dangerReason = findDangerousCommandReason(code);
     if (dangerReason) throw new Error(dangerReason);
@@ -825,7 +853,7 @@ export async function runCode(
     fs.writeFileSync(tmpFile, code);
     try {
         const interpreter = language === "python" ? "python3" : "node";
-        return await runCommand(workspaceRoot, `${interpreter} "${tmpFile}"`, relativeCwd);
+        return await runCommand(workspaceRoot, `${interpreter} "${tmpFile}"`, relativeCwd, network);
     } finally {
         fs.rmSync(tmpFile, { force: true });
     }
@@ -856,7 +884,8 @@ export function startBackgroundCommand(
     workspaceRoot: string,
     command: string,
     relativeCwd = ".",
-    name?: string
+    name?: string,
+    network = false
 ): { taskId: string; name: string } {
     const dangerReason = findDangerousCommandReason(command);
     if (dangerReason) throw new Error(dangerReason);
@@ -866,12 +895,13 @@ export function startBackgroundCommand(
     }
 
     const cwd = resolveSafePath(workspaceRoot, relativeCwd);
+    const wrappedCommand = applySandbox(command, { workspaceRoot, allowNetwork: network });
     // detached so the shell becomes its own process group leader — lets
     // killProcessTree() below signal the whole group (shell + whatever it
     // spawned, e.g. `npm run dev` spawning `node`) instead of just the shell
     // itself, which is all a plain .kill() would reach. No effect on Windows,
     // where killProcessTree uses `taskkill /t` instead.
-    const child = spawn(command, {
+    const child = spawn(wrappedCommand, {
         cwd,
         shell: true,
         stdio: ["ignore", "pipe", "pipe"],
@@ -900,7 +930,16 @@ export function startBackgroundCommand(
         task.output += `\n[failed to start: ${err.message}]`;
         task.exitCode = -1;
     });
+    const settings = settingsStore.getSettings();
+    const stopMonitor = child.pid
+        ? monitorProcess(
+              child.pid,
+              { maxMemoryMB: settings.sandboxMaxMemoryMB, maxCpuPercent: settings.sandboxMaxCpuPercent },
+              (reason) => append(Buffer.from(`\n[background task stopped: ${reason}]`))
+          )
+        : () => {};
     child.on("exit", (code) => {
+        stopMonitor();
         task.exitCode = code ?? -1;
     });
     backgroundTasks.set(id, task);
@@ -1357,7 +1396,25 @@ export async function githubReadFile(repository: string, filePath: string, ref?:
     return content.length > MAX_READ_CHARS ? `${content.slice(0, MAX_READ_CHARS)}\n\n[truncated]` : content;
 }
 
+// Tools that reach the network — gated by settings.networkToolsEnabled as a
+// baseline that's 100% enforceable on every platform (refusing to run the
+// tool at all, rather than trying to block network access after the fact,
+// which is what command-sandbox.ts's per-call `network` argument does for
+// run_command/run_code/start_background_command instead).
+const NETWORK_TOOLS = new Set([
+    "web_search",
+    "fetch_url",
+    "http_request",
+    "capture_page_screenshot",
+    "github_list_repositories",
+    "github_repository_tree",
+    "github_read_file",
+]);
+
 export async function executeTool(workspaceRoot: string, name: string, args: Record<string, unknown>): Promise<unknown> {
+    if (NETWORK_TOOLS.has(name) && settingsStore.getSettings().networkToolsEnabled === false) {
+        throw new Error(`Network access for agent tools is turned off in Settings — "${name}" can't run.`);
+    }
     switch (name) {
         case "read_file":
             return readFile(
@@ -1391,17 +1448,18 @@ export async function executeTool(workspaceRoot: string, name: string, args: Rec
         case "search_files":
             return searchFiles(workspaceRoot, String(args.query ?? ""), args.path ? String(args.path) : ".");
         case "run_command":
-            return runCommand(workspaceRoot, String(args.command ?? ""), args.cwd ? String(args.cwd) : ".");
+            return runCommand(workspaceRoot, String(args.command ?? ""), args.cwd ? String(args.cwd) : ".", args.network === true);
         case "run_code": {
             const language = args.language === "python" ? "python" : "javascript";
-            return runCode(workspaceRoot, language, String(args.code ?? ""), args.cwd ? String(args.cwd) : ".");
+            return runCode(workspaceRoot, language, String(args.code ?? ""), args.cwd ? String(args.cwd) : ".", args.network === true);
         }
         case "start_background_command":
             return startBackgroundCommand(
                 workspaceRoot,
                 String(args.command ?? ""),
                 args.cwd ? String(args.cwd) : ".",
-                args.name ? String(args.name) : undefined
+                args.name ? String(args.name) : undefined,
+                args.network === true
             );
         case "get_background_output":
             return getBackgroundOutput(String(args.task_id ?? ""));

app/src/agent-tools.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from "vitest";
+import { detectSandboxCapabilities, wrapCommand, applySandbox } from "./command-sandbox";
+
+const has = (available: string[]) => (cmd: string) => available.includes(cmd);
+
+describe("detectSandboxCapabilities", () => {
+    it("prefers bubblewrap on Linux when available", () => {
+        expect(detectSandboxCapabilities("linux", has(["bwrap"]))).toEqual({
+            filesystemConfinement: true,
+            networkDenial: true,
+            mechanism: "bubblewrap",
+        });
+    });
+
+    it("reports no containment on Linux without bubblewrap", () => {
+        expect(detectSandboxCapabilities("linux", has([]))).toEqual({
+            filesystemConfinement: false,
+            networkDenial: false,
+            mechanism: "none",
+        });
+    });
+
+    it("uses sandbox-exec on macOS when available", () => {
+        expect(detectSandboxCapabilities("darwin", has(["sandbox-exec"]))).toEqual({
+            filesystemConfinement: true,
+            networkDenial: true,
+            mechanism: "sandbox-exec",
+        });
+    });
+
+    it("reports no containment on macOS without sandbox-exec", () => {
+        expect(detectSandboxCapabilities("darwin", has([]))).toEqual({
+            filesystemConfinement: false,
+            networkDenial: false,
+            mechanism: "none",
+        });
+    });
+
+    it("always reports no containment on Windows, regardless of PATH", () => {
+        expect(detectSandboxCapabilities("win32", has(["bwrap", "sandbox-exec"]))).toEqual({
+            filesystemConfinement: false,
+            networkDenial: false,
+            mechanism: "none",
+        });
+    });
+});
+
+describe("wrapCommand", () => {
+    it("returns null when no sandbox mechanism is available", () => {
+        expect(wrapCommand("echo hi", { workspaceRoot: "/ws", allowNetwork: false }, "win32", has([]))).toBeNull();
+        expect(wrapCommand("echo hi", { workspaceRoot: "/ws", allowNetwork: false }, "linux", has([]))).toBeNull();
+    });
+
+    it("builds a bubblewrap invocation confining writes to the workspace, network denied by default", () => {
+        const wrapped = wrapCommand("npm test", { workspaceRoot: "/home/user/project", allowNetwork: false }, "linux", has(["bwrap"]));
+        expect(wrapped?.command).toBe("bwrap");
+        expect(wrapped?.args).toContain("--unshare-all");
+        expect(wrapped?.args).not.toContain("--share-net");
+        expect(wrapped?.args).toEqual(expect.arrayContaining(["--bind", "/home/user/project", "/home/user/project"]));
+        expect(wrapped?.args.slice(-3)).toEqual(["sh", "-c", "npm test"]);
+    });
+
+    it("adds --share-net to the bubblewrap invocation when network is explicitly allowed", () => {
+        const wrapped = wrapCommand("npm install", { workspaceRoot: "/home/user/project", allowNetwork: true }, "linux", has(["bwrap"]));
+        expect(wrapped?.args).toContain("--share-net");
+    });
+
+    it("builds a sandbox-exec invocation with a profile scoped to the workspace", () => {
+        const wrapped = wrapCommand("npm test", { workspaceRoot: "/Users/me/project", allowNetwork: false }, "darwin", has(["sandbox-exec"]));
+        expect(wrapped?.command).toBe("sandbox-exec");
+        expect(wrapped?.args[0]).toBe("-p");
+        expect(wrapped?.args[1]).toContain('(allow file-write* (subpath "/Users/me/project"))');
+        expect(wrapped?.args[1]).toContain("(deny network*)");
+        expect(wrapped?.args.slice(-3)).toEqual(["sh", "-c", "npm test"]);
+    });
+
+    it("allows network in the sandbox-exec profile when requested", () => {
+        const wrapped = wrapCommand("curl example.com", { workspaceRoot: "/Users/me/project", allowNetwork: true }, "darwin", has(["sandbox-exec"]));
+        expect(wrapped?.args[1]).toContain("(allow network*)");
+        expect(wrapped?.args[1]).not.toContain("(deny network*)");
+    });
+});
+
+describe("applySandbox", () => {
+    it("returns the command unchanged when no sandbox mechanism is available", () => {
+        expect(applySandbox("echo hi", { workspaceRoot: "/ws", allowNetwork: false }, "win32", has(["bwrap"]))).toBe("echo hi");
+    });
+
+    it("folds a bubblewrap-wrapped command into a single shell string ending in the original command", () => {
+        const result = applySandbox("npm test", { workspaceRoot: "/home/user/project", allowNetwork: false }, "linux", has(["bwrap"]));
+        expect(result.startsWith("'bwrap' ")).toBe(true);
+        expect(result).toContain("'/home/user/project'");
+        expect(result.endsWith("'sh' '-c' 'npm test'")).toBe(true);
+    });
+
+    it("shell-quotes a workspace path containing a single quote so it can't break out of the wrapper", () => {
+        const result = applySandbox("echo hi", { workspaceRoot: "/home/user/it's-a-project", allowNetwork: false }, "linux", has(["bwrap"]));
+        // A raw unescaped single quote here would terminate the shell string
+        // early and let the rest of the path be interpreted as commands.
+        expect(result).toContain("'/home/user/it'\\''s-a-project'");
+    });
+});