feat: implemented Bash run_in_background support

Author: qorzj

src/prompt.ts

@@ -351,6 +351,11 @@ export function getTools(_options: PromptToolOptions = {}, externalTools: ToolDe
               },
               uniqueItems: true,
             },
+            run_in_background: {
+              type: "boolean",
+              description:
+                "Set to true to run the command in the background. Use this only when you need to perform a blocking task and do not need the result immediately.",
+            },
           },
           required: ["command", "sideEffects"],
           additionalProperties: false,

src/session.ts

@@ -2172,6 +2172,7 @@ ${skillMd}
       onProcessExit: (pid) => this.removeSessionProcess(sessionId, pid),
       onProcessStdout: (pid, chunk) => this.onProcessStdout?.(Number(pid), chunk),
       onProcessTimeoutControl: (pid, control) => this.setSessionProcessTimeoutControl(sessionId, pid, control),
+      onBackgroundProcessComplete: (completion) => this.addBackgroundProcessCompletionMessage(sessionId, completion),
       onBeforeFileMutation: (filePath) => this.prepareFileMutationCheckpoint(sessionId, filePath),
       onAfterFileMutation: (filePath) => this.recordFileMutationCheckpoint(sessionId, filePath),
       shouldStop: () => this.isInterrupted(sessionId),
@@ -2677,6 +2678,46 @@ ${skillMd}
     });
   }
 
+  private addBackgroundProcessCompletionMessage(
+    sessionId: string,
+    completion: {
+      command: string;
+      outputPath: string;
+      ok: boolean;
+      exitCode: number | null;
+      signal: string | null;
+      error?: string;
+      completedAtMs: number;
+      startedAtMs: number;
+    }
+  ): void {
+    const status = completion.ok ? "completed" : "failed";
+    const exitText =
+      completion.exitCode !== null
+        ? `exit code ${completion.exitCode}`
+        : completion.signal
+          ? `signal ${completion.signal}`
+          : completion.error || "unknown status";
+    const durationMs = Math.max(0, completion.completedAtMs - completion.startedAtMs);
+    const content =
+      `Background command "${completion.command}" ${status} with ${exitText} ` +
+      `after ${this.formatBackgroundDuration(durationMs)}. Output: ${completion.outputPath}`;
+    this.addSessionSystemMessage(sessionId, content, true);
+  }
+
+  private formatBackgroundDuration(durationMs: number): string {
+    if (durationMs < 1000) {
+      return `${durationMs}ms`;
+    }
+    const seconds = Math.round(durationMs / 1000);
+    if (seconds < 60) {
+      return `${seconds}s`;
+    }
+    const minutes = Math.floor(seconds / 60);
+    const remainingSeconds = seconds % 60;
+    return remainingSeconds > 0 ? `${minutes}m ${remainingSeconds}s` : `${minutes}m`;
+  }
+
   private removeSessionProcess(sessionId: string, processId: string | number): void {
     const now = new Date().toISOString();
     this.processTimeoutControls.delete(this.getProcessControlKey(sessionId, processId));

src/tests/prompt.test.ts

@@ -30,6 +30,8 @@ test("getTools requires bash sideEffects permission scopes", () => {
   assert.equal(sideEffects.type, "array");
   assert.equal(sideEffects.items?.enum?.includes("write-out-cwd"), true);
   assert.equal(sideEffects.items?.enum?.includes("unknown"), true);
+  const runInBackground = tool.function.parameters.properties.run_in_background as { type?: unknown };
+  assert.equal(runInBackground.type, "boolean");
 });
 
 test("getSystemPrompt always includes WebSearch docs", () => {
@@ -43,6 +45,12 @@ test("getSystemPrompt includes UpdatePlan docs", () => {
   assert.equal(prompt.includes("The `plan` argument is a markdown string, not an array of step objects."), true);
 });
 
+test("getSystemPrompt includes Bash background guidance", () => {
+  const prompt = getSystemPrompt("/tmp/project");
+  assert.equal(prompt.includes("run_in_background: true"), true);
+  assert.equal(prompt.includes("do not add `&`"), true);
+});
+
 test("getSystemPrompt does not include runtime context", () => {
   const prompt = getSystemPrompt("/tmp/project");
   assert.equal(prompt.includes("# Local Workspace Environment"), false);

src/tests/tool-handlers.test.ts

@@ -4,7 +4,7 @@ import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import { setTimeout as delay } from "node:timers/promises";
-import type { ProcessTimeoutControl, ToolExecutionContext } from "../tools/executor";
+import type { BackgroundProcessCompletion, ProcessTimeoutControl, ToolExecutionContext } from "../tools/executor";
 import { handleBashTool } from "../tools/bash-handler";
 import { handleEditTool } from "../tools/edit-handler";
 import { handleReadTool } from "../tools/read-handler";
@@ -104,6 +104,78 @@ test("Bash timeout control can extend the active command deadline", async () =>
   assert.equal(result.metadata?.timeoutMs, 1000);
 });
 
+test("Bash can run commands in the background and report completion output", async () => {
+  const workspace = createTempWorkspace();
+  let completion: BackgroundProcessCompletion | null = null;
+  const starts: Array<string | number> = [];
+  const exits: Array<string | number> = [];
+  const startedAt = Date.now();
+
+  const result = await handleBashTool(
+    {
+      command: "printf 'start\\n'; sleep 0.2; printf 'done\\n'",
+      run_in_background: true,
+    },
+    createContext("bash-background", workspace, {
+      bashTimeoutMs: 10,
+      bashMinTimeoutMs: 1,
+      onProcessStart: (pid) => starts.push(pid),
+      onProcessExit: (pid) => exits.push(pid),
+      onBackgroundProcessComplete: (event) => {
+        completion = event;
+      },
+    })
+  );
+
+  assert.equal(result.ok, true);
+  assert.equal(result.metadata?.runInBackground, true);
+  assert.equal(typeof result.metadata?.backgroundTaskId, "string");
+  assert.equal(typeof result.metadata?.outputPath, "string");
+  assert.ok(Date.now() - startedAt < 500);
+  assert.equal(starts.length, 1);
+
+  await waitFor(() => completion !== null, 2000);
+
+  assert.ok(completion);
+  const done = completion as BackgroundProcessCompletion;
+  assert.equal(done.ok, true);
+  assert.equal(done.exitCode, 0);
+  assert.equal(exits.length, 1);
+  const outputPath = done.outputPath;
+  const output = fs.readFileSync(outputPath, "utf8");
+  assert.match(output, /start/);
+  assert.match(output, /done/);
+  assert.doesNotMatch(output, /__DEEPCODE_PWD__/);
+});
+
+test("Bash background completion reports failed exit codes", async () => {
+  const workspace = createTempWorkspace();
+  let completion: BackgroundProcessCompletion | null = null;
+
+  const result = await handleBashTool(
+    {
+      command: "printf 'bad\\n'; exit 7",
+      run_in_background: true,
+    },
+    createContext("bash-background-failure", workspace, {
+      onBackgroundProcessComplete: (event) => {
+        completion = event;
+      },
+    })
+  );
+
+  assert.equal(result.ok, true);
+  await waitFor(() => completion !== null, 2000);
+
+  assert.ok(completion);
+  const done = completion as BackgroundProcessCompletion;
+  assert.equal(done.ok, false);
+  assert.equal(done.exitCode, 7);
+  assert.match(done.error ?? "", /exit code 7/);
+  const output = fs.readFileSync(done.outputPath, "utf8");
+  assert.match(output, /bad/);
+});
+
 test("UpdatePlan accepts a markdown task list string", async () => {
   const workspace = createTempWorkspace();
   const plan = ["## Task List", "", "- [>] Inspect current behavior", "- [ ] Implement UpdatePlan"].join("\n");

src/tools/bash-handler.ts

@@ -1,4 +1,8 @@
 import { spawn } from "child_process";
+import { randomUUID } from "crypto";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
 import { DEFAULT_BASH_TIMEOUT_MS, clampBashTimeoutMs } from "../common/bash-timeout";
 import { killProcessTree } from "../common/process-tree";
 import type { ProcessTimeoutControl, ProcessTimeoutInfo, ToolExecutionContext, ToolExecutionResult } from "./executor";
@@ -13,6 +17,7 @@ import {
 
 const MAX_OUTPUT_CHARS = 30000;
 const MAX_CAPTURE_CHARS = 10 * 1024 * 1024;
+const BACKGROUND_OUTPUT_DIR = path.join(os.tmpdir(), "deepcode-background");
 const sessionWorkingDirs = new Map<string, string>();
 
 export function clearSessionWorkingDir(sessionId: string): void {
@@ -51,6 +56,11 @@ export async function handleBashTool(
 
   const startCwd = getSessionCwd(context.sessionId, context.projectRoot);
   const { shellPath, shellArgs, marker } = buildShellCommand(command);
+  const runInBackground = isTrue(args.run_in_background);
+
+  if (runInBackground) {
+    return startBackgroundShellCommand(shellPath, shellArgs, startCwd, command, marker, context);
+  }
 
   const execution = await executeShellCommand(shellPath, shellArgs, startCwd, command, context);
   const result = buildToolCommandResult(
@@ -75,6 +85,10 @@ export async function handleBashTool(
   return formatResult(result, "bash");
 }
 
+function isTrue(value: unknown): boolean {
+  return value === true || value === "true";
+}
+
 function getSessionCwd(sessionId: string, fallback: string): string {
   return sessionWorkingDirs.get(sessionId) ?? fallback;
 }
@@ -235,6 +249,125 @@ async function executeShellCommand(
   });
 }
 
+function startBackgroundShellCommand(
+  shellPath: string,
+  shellArgs: string[],
+  cwd: string,
+  command: string,
+  marker: string,
+  context: ToolExecutionContext
+): ToolExecutionResult {
+  fs.mkdirSync(BACKGROUND_OUTPUT_DIR, { recursive: true });
+  const taskId = `bash-${randomUUID()}`;
+  const outputPath = path.join(BACKGROUND_OUTPUT_DIR, `${taskId}.log`);
+  const startedAtMs = Date.now();
+  const detached = process.platform !== "win32";
+  const configuredEnv = context.createOpenAIClient?.().env ?? {};
+  const child = spawn(shellPath, shellArgs, {
+    cwd,
+    env: buildShellEnv(shellPath, configuredEnv),
+    detached,
+    windowsHide: true,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  const pid = child.pid;
+  const processId = typeof pid === "number" ? pid : -1;
+
+  let stdout = "";
+  let stderr = "";
+  let error: string | undefined;
+
+  const appendOutputFile = (chunk: string | Buffer) => {
+    try {
+      fs.appendFileSync(outputPath, chunk);
+    } catch {
+      // Keep the background process running even if temp-file writes fail.
+    }
+  };
+
+  if (typeof pid === "number") {
+    context.onProcessStart?.(pid, command);
+  }
+
+  child.stdout?.on("data", (chunk: string | Buffer) => {
+    stdout = appendChunk(stdout, chunk);
+    appendOutputFile(chunk);
+    const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+    if (typeof pid === "number") {
+      context.onProcessStdout?.(pid, text);
+    }
+  });
+  child.stderr?.on("data", (chunk: string | Buffer) => {
+    stderr = appendChunk(stderr, chunk);
+    appendOutputFile(chunk);
+    const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+    if (typeof pid === "number") {
+      context.onProcessStdout?.(pid, text);
+    }
+  });
+
+  child.on("error", (spawnError) => {
+    error = spawnError.message;
+  });
+
+  child.on("close", (code, signal) => {
+    const markerResult = stripMarker(stdout, marker);
+    const finalOutput = joinOutput(markerResult.output, stderr);
+    const result = buildToolCommandResult(
+      stdout,
+      stderr,
+      marker,
+      typeof code === "number" ? code : null,
+      signal ?? null,
+      shellPath,
+      cwd
+    );
+    updateSessionCwd(context.sessionId, cwd, result.cwd);
+    writeFinalBackgroundOutput(outputPath, finalOutput);
+    if (typeof pid === "number") {
+      context.onProcessExit?.(pid);
+    }
+    const ok = !error && result.exitCode === 0 && result.signal === null;
+    context.onBackgroundProcessComplete?.({
+      taskId,
+      processId,
+      command,
+      outputPath,
+      ok,
+      exitCode: result.exitCode,
+      signal: result.signal,
+      error: ok ? undefined : buildErrorMessage(result.exitCode, result.signal, error),
+      cwd: result.cwd,
+      shellPath,
+      startedAtMs,
+      completedAtMs: Date.now(),
+    });
+  });
+
+  return {
+    ok: true,
+    name: "bash",
+    output: `Command running in background with ID: ${taskId}. Output is being written to: ${outputPath}`,
+    metadata: {
+      backgroundTaskId: taskId,
+      processId: typeof pid === "number" ? pid : null,
+      outputPath,
+      cwd,
+      shellPath,
+      startCwd: cwd,
+      runInBackground: true,
+    },
+  };
+}
+
+function writeFinalBackgroundOutput(outputPath: string, output: string | undefined): void {
+  try {
+    fs.writeFileSync(outputPath, output ?? "", "utf8");
+  } catch {
+    // Ignore notification/output persistence failures; the tool result already returned.
+  }
+}
+
 function appendChunk(existing: string, chunk: string | Buffer): string {
   if (existing.length >= MAX_CAPTURE_CHARS) {
     return existing;

src/tools/executor.ts

@@ -41,6 +41,7 @@ export type ToolExecutionContext = {
   onProcessExit?: (processId: string | number) => void;
   onProcessStdout?: (processId: string | number, chunk: string) => void;
   onProcessTimeoutControl?: (processId: string | number, control: ProcessTimeoutControl | null) => void;
+  onBackgroundProcessComplete?: (completion: BackgroundProcessCompletion) => void;
   onBeforeFileMutation?: (filePath: string) => void;
   onAfterFileMutation?: (filePath: string) => void;
   bashTimeoutMs?: number;
@@ -52,11 +53,27 @@ export type ToolExecutionHooks = {
   onProcessExit?: (processId: string | number) => void;
   onProcessStdout?: (processId: string | number, chunk: string) => void;
   onProcessTimeoutControl?: (processId: string | number, control: ProcessTimeoutControl | null) => void;
+  onBackgroundProcessComplete?: (completion: BackgroundProcessCompletion) => void;
   onBeforeFileMutation?: (filePath: string) => void;
   onAfterFileMutation?: (filePath: string) => void;
   shouldStop?: () => boolean;
 };
 
+export type BackgroundProcessCompletion = {
+  taskId: string;
+  processId: number;
+  command: string;
+  outputPath: string;
+  ok: boolean;
+  exitCode: number | null;
+  signal: string | null;
+  error?: string;
+  cwd: string | null;
+  shellPath: string;
+  startedAtMs: number;
+  completedAtMs: number;
+};
+
 export type ProcessTimeoutInfo = {
   timeoutMs: number;
   startedAtMs: number;
@@ -230,6 +247,7 @@ export class ToolExecutor {
         onProcessExit: hooks?.onProcessExit,
         onProcessStdout: hooks?.onProcessStdout,
         onProcessTimeoutControl: hooks?.onProcessTimeoutControl,
+        onBackgroundProcessComplete: hooks?.onBackgroundProcessComplete,
         onBeforeFileMutation: hooks?.onBeforeFileMutation,
         onAfterFileMutation: hooks?.onAfterFileMutation,
       });