Add background command tools for Agent mode

start_background_command/get_background_output/stop_background_command/
list_background_commands let the agent kick off a dev server or long
build without blocking its own loop on run_command's timeout, then
poll for output later. Capped at 5 concurrent tasks per workspace
with a rolling output buffer, checked against the same dangerous-
command blocklist as run_command, and killed on app quit so nothing
orphans.

Also fixes a stray setState-in-effect (sidebar auto-close on session
change) using React's render-time state-adjustment pattern instead.

Author: voidstackloop

app/src/agent-tools.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach } from "vitest";
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -26,8 +26,25 @@ import {
     readNotes,
     writeNotes,
     fetchUrl,
+    startBackgroundCommand,
+    getBackgroundOutput,
+    stopBackgroundCommand,
+    listBackgroundCommands,
+    killAllBackgroundCommands,
 } from "./agent-tools";
 
+function waitFor(predicate: () => boolean, timeoutMs = 5000): Promise<void> {
+    const start = Date.now();
+    return new Promise((resolve, reject) => {
+        const check = () => {
+            if (predicate()) return resolve();
+            if (Date.now() - start > timeoutMs) return reject(new Error("waitFor timed out"));
+            setTimeout(check, 20);
+        };
+        check();
+    });
+}
+
 describe("agent-tools", () => {
     let workspace: string;
 
@@ -316,6 +333,59 @@ describe("agent-tools", () => {
         });
     });
 
+    describe("background commands", () => {
+        afterEach(() => {
+            killAllBackgroundCommands();
+        });
+
+        it("starts a command and returns a task id immediately", () => {
+            const { taskId, name } = startBackgroundCommand(workspace, "echo hello-background");
+            expect(taskId).toBeTruthy();
+            expect(name).toBe("echo hello-background");
+        });
+
+        it("captures output as the command runs and reports its exit", async () => {
+            const { taskId } = startBackgroundCommand(workspace, "echo from-bg-task");
+            await waitFor(() => getBackgroundOutput(taskId).includes("exited with code 0"));
+            const output = getBackgroundOutput(taskId);
+            expect(output).toContain("from-bg-task");
+            expect(output).toContain("exited with code 0");
+        });
+
+        it("reports a still-running task as running, not exited", () => {
+            const { taskId } = startBackgroundCommand(workspace, "sleep 5");
+            expect(getBackgroundOutput(taskId)).toContain("running");
+        });
+
+        it("stops a running task on request", async () => {
+            const { taskId } = startBackgroundCommand(workspace, "sleep 30");
+            const result = stopBackgroundCommand(taskId);
+            expect(result).toContain("stopped");
+            await waitFor(() => getBackgroundOutput(taskId).includes("exited"));
+        });
+
+        it("lists all started tasks with their status", () => {
+            const a = startBackgroundCommand(workspace, "echo a");
+            const b = startBackgroundCommand(workspace, "echo b");
+            const list = listBackgroundCommands();
+            expect(list.map((t) => t.id)).toEqual(expect.arrayContaining([a.taskId, b.taskId]));
+        });
+
+        it("throws for an unknown task id", () => {
+            expect(() => getBackgroundOutput("does-not-exist")).toThrow(/No background task/);
+            expect(() => stopBackgroundCommand("does-not-exist")).toThrow(/No background task/);
+        });
+
+        it("blocks a dangerous command from ever starting", () => {
+            expect(() => startBackgroundCommand(workspace, "sudo rm -rf /")).toThrow(/blocked/);
+        });
+
+        it("caps the number of concurrently running background tasks", () => {
+            for (let i = 0; i < 5; i++) startBackgroundCommand(workspace, "sleep 5", ".", `task-${i}`);
+            expect(() => startBackgroundCommand(workspace, "sleep 5")).toThrow(/Already running/);
+        });
+    });
+
     describe("git tools", () => {
         beforeEach(() => {
             execSync("git init -q", { cwd: workspace });

app/src/agent-tools.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { exec } from "node:child_process";
+import { exec, spawn, type ChildProcess } from "node:child_process";
 import { promisify } from "node:util";
 import { randomUUID } from "node:crypto";
 import type { ToolDefinition } from "./providers/types";
@@ -153,6 +153,47 @@ export const AGENT_TOOLS: ToolDefinition[] = [
             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.",
+        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\")." },
+            },
+            required: ["command"],
+        },
+    },
+    {
+        name: "get_background_output",
+        description: "Get the current status and recent output of a background command started with start_background_command.",
+        parameters: {
+            type: "object",
+            properties: {
+                task_id: { type: "string", description: "The task id returned by start_background_command." },
+            },
+            required: ["task_id"],
+        },
+    },
+    {
+        name: "stop_background_command",
+        description: "Stop a running background command by its task id.",
+        parameters: {
+            type: "object",
+            properties: {
+                task_id: { type: "string", description: "The task id returned by start_background_command." },
+            },
+            required: ["task_id"],
+        },
+    },
+    {
+        name: "list_background_commands",
+        description: "List all background commands from this session with their status.",
+        parameters: { type: "object", properties: {}, required: [] },
+    },
     {
         name: "git_status",
         description: "Show the working tree status (git status) for the workspace.",
@@ -679,6 +720,105 @@ export async function runCode(
     }
 }
 
+interface BackgroundTask {
+    id: string;
+    name: string;
+    command: string;
+    process: ChildProcess;
+    // Rolling tail of combined stdout+stderr — capped so a chatty dev server
+    // can't grow memory unboundedly over a long session.
+    output: string;
+    exitCode: number | null;
+    startedAt: number;
+}
+
+const MAX_BACKGROUND_TASKS = 5;
+const MAX_BACKGROUND_OUTPUT_CHARS = 100_000;
+const BACKGROUND_OUTPUT_TAIL_CHARS = 20_000;
+const backgroundTasks = new Map<string, BackgroundTask>();
+
+export function startBackgroundCommand(
+    workspaceRoot: string,
+    command: string,
+    relativeCwd = ".",
+    name?: string
+): { taskId: string; name: string } {
+    const dangerReason = findDangerousCommandReason(command);
+    if (dangerReason) throw new Error(dangerReason);
+    const runningCount = [...backgroundTasks.values()].filter((t) => t.exitCode === null).length;
+    if (runningCount >= MAX_BACKGROUND_TASKS) {
+        throw new Error(`Already running ${MAX_BACKGROUND_TASKS} background commands — stop one first.`);
+    }
+
+    const cwd = resolveSafePath(workspaceRoot, relativeCwd);
+    const child = spawn(command, { cwd, shell: true, stdio: ["ignore", "pipe", "pipe"] });
+    const id = randomUUID().slice(0, 8);
+    const task: BackgroundTask = {
+        id,
+        name: name?.trim() || command.slice(0, 40),
+        command,
+        process: child,
+        output: "",
+        exitCode: null,
+        startedAt: Date.now(),
+    };
+    const append = (chunk: Buffer) => {
+        task.output += chunk.toString();
+        if (task.output.length > MAX_BACKGROUND_OUTPUT_CHARS) {
+            task.output = task.output.slice(-MAX_BACKGROUND_OUTPUT_CHARS);
+        }
+    };
+    child.stdout?.on("data", append);
+    child.stderr?.on("data", append);
+    child.on("error", (err) => {
+        task.output += `\n[failed to start: ${err.message}]`;
+        task.exitCode = -1;
+    });
+    child.on("exit", (code) => {
+        task.exitCode = code ?? -1;
+    });
+    backgroundTasks.set(id, task);
+    return { taskId: id, name: task.name };
+}
+
+export function getBackgroundOutput(taskId: string): string {
+    const task = backgroundTasks.get(taskId);
+    if (!task) throw new Error(`No background task with id "${taskId}".`);
+    const status =
+        task.exitCode === null
+            ? `running (${Math.round((Date.now() - task.startedAt) / 1000)}s)`
+            : `exited with code ${task.exitCode}`;
+    const tail =
+        task.output.length > BACKGROUND_OUTPUT_TAIL_CHARS
+            ? `[...earlier output trimmed]\n${task.output.slice(-BACKGROUND_OUTPUT_TAIL_CHARS)}`
+            : task.output;
+    return `Task ${task.id} (${task.name}): ${status}\n--- output ---\n${tail || "(no output yet)"}`;
+}
+
+export function stopBackgroundCommand(taskId: string): string {
+    const task = backgroundTasks.get(taskId);
+    if (!task) throw new Error(`No background task with id "${taskId}".`);
+    if (task.exitCode !== null) return `Task ${task.id} had already exited with code ${task.exitCode}.`;
+    task.process.kill();
+    return `Task ${task.id} (${task.name}) stopped.`;
+}
+
+export function listBackgroundCommands(): { id: string; name: string; command: string; status: string }[] {
+    return [...backgroundTasks.values()].map((t) => ({
+        id: t.id,
+        name: t.name,
+        command: t.command,
+        status: t.exitCode === null ? "running" : `exited (${t.exitCode})`,
+    }));
+}
+
+export function killAllBackgroundCommands(): void {
+    for (const task of backgroundTasks.values()) {
+        if (task.exitCode === null) task.process.kill();
+    }
+    backgroundTasks.clear();
+}
+
 function gitCommand(workspaceRoot: string, args: string): Promise<string> {
     return runCommand(workspaceRoot, `git ${args}`, ".");
 }
@@ -947,6 +1087,19 @@ export async function executeTool(workspaceRoot: string, name: string, args: Rec
             const language = args.language === "python" ? "python" : "javascript";
             return runCode(workspaceRoot, language, String(args.code ?? ""), args.cwd ? String(args.cwd) : ".");
         }
+        case "start_background_command":
+            return startBackgroundCommand(
+                workspaceRoot,
+                String(args.command ?? ""),
+                args.cwd ? String(args.cwd) : ".",
+                args.name ? String(args.name) : undefined
+            );
+        case "get_background_output":
+            return getBackgroundOutput(String(args.task_id ?? ""));
+        case "stop_background_command":
+            return stopBackgroundCommand(String(args.task_id ?? ""));
+        case "list_background_commands":
+            return listBackgroundCommands();
         case "git_status":
             return gitStatus(workspaceRoot);
         case "git_diff":

app/src/main.ts

@@ -779,12 +779,14 @@ app.whenReady().then(async () => {
 app.on("window-all-closed", () => {
     ollama.stop();
     localServers.stopAll();
+    agentTools.killAllBackgroundCommands();
     mcpClient.disconnectAll();
     if (process.platform !== "darwin") app.quit();
 });
 
 app.on("before-quit", () => {
     ollama.stop();
     localServers.stopAll();
+    agentTools.killAllBackgroundCommands();
     void llamacpp.dispose();
 });

frontend/src/components/layout.tsx

@@ -535,8 +535,15 @@ export default function Layout() {
     const [showOnboarding, setShowOnboarding] = useState(false);
     const [keybindings, setKeybindings] = useState<Record<KeybindingAction, string>>(DEFAULT_KEYBINDINGS);
     const [sidebarOpen, setSidebarOpen] = useState(false);
-
-    useEffect(() => setSidebarOpen(false), [sessionId]);
+    // Closes the mobile sidebar on navigating to a session — adjusted during
+    // render (not an effect) per React's "resetting state when a prop
+    // changes" pattern, since the reset needs to happen before the closed
+    // sidebar's first paint rather than flash open-then-closed.
+    const [prevSessionId, setPrevSessionId] = useState(sessionId);
+    if (sessionId !== prevSessionId) {
+        setPrevSessionId(sessionId);
+        setSidebarOpen(false);
+    }
 
     useEffect(() => {
         if (!hasApi) return;

frontend/src/pages/Chat.tsx

@@ -123,6 +123,8 @@ const READ_ONLY_TOOLS = new Set([
     "github_list_repositories",
     "github_repository_tree",
     "github_read_file",
+    "get_background_output",
+    "list_background_commands",
 ]);
 
 // Vision models can already reason over any attached image — these just save