feat(tools): add run in background to execute command

This new parameter allows commands like development servers or monitoring processes to run in the background without requiring user interaction after initiation. This improves the user experience for long-running tasks.

Author: hassoncs

src/core/prompts/tools/execute-command.ts

@@ -6,15 +6,17 @@ Description: Request to execute a CLI command on the system. Use this when you n
 Parameters:
 - command: (required) The CLI command to execute. This should be valid for the current operating system. Ensure the command is properly formatted and does not contain any harmful instructions.
 - cwd: (optional) The working directory to execute the command in (default: ${args.cwd})
+- runInBackground: (optional) If true, auto run the command in the background without user interaction. Use this for long-running commands like dev servers or monitoring commands (default: false)
 Usage:
 <execute_command>
 <command>Your command here</command>
 <cwd>Working directory path (optional)</cwd>
 </execute_command>
 
-Example: Requesting to execute npm run dev
+Example: Requesting to execute npm run dev in background
 <execute_command>
 <command>npm run dev</command>
+<runInBackground>true</runInBackground>
 </execute_command>
 
 Example: Requesting to execute ls in a specific directory if directed

src/core/tools/__tests__/executeCommandTimeout.integration.spec.ts

@@ -21,6 +21,7 @@ vitest.mock("../../prompts/responses", () => ({
 	formatResponse: {
 		toolError: vitest.fn((msg) => `Tool Error: ${msg}`),
 		rooIgnoreError: vitest.fn((msg) => `RooIgnore Error: ${msg}`),
+		toolResult: vitest.fn((content, images) => `Tool Result: ${content}`),
 	},
 }))
 vitest.mock("../../../utils/text-normalization", () => ({
@@ -52,6 +53,7 @@ describe("Command Execution Timeout Integration", () => {
 					postMessageToWebview: vitest.fn(),
 				}),
 			},
+			ask: vitest.fn(),
 			say: vitest.fn().mockResolvedValue(undefined),
 		}
 
@@ -409,4 +411,60 @@ describe("Command Execution Timeout Integration", () => {
 			expect(result2).toContain("terminated after exceeding")
 		}, 5000)
 	})
+
+	describe("runInBackground Integration", () => {
+		it("should automatically continue command execution when runInBackground is true", async () => {
+			// Setup a command that produces output
+			mockProcess = {
+				continue: vitest.fn(),
+				abort: vitest.fn(),
+			}
+
+			mockTerminal = {
+				runCommand: vitest.fn().mockImplementation((command, callbacks) => {
+					// Simulate command producing output
+					setTimeout(() => {
+						callbacks.onLine("Starting development server...\n", mockProcess)
+					}, 10)
+
+					// Simulate command completion
+					setTimeout(() => {
+						callbacks.onCompleted("Development server started successfully")
+						callbacks.onShellExecutionComplete({ exitCode: 0 })
+					}, 50)
+
+					return Promise.resolve()
+				}),
+				getCurrentWorkingDirectory: vitest.fn().mockReturnValue({
+					toPosix: () => "/test/directory",
+				}),
+			}
+			;(TerminalRegistry.getOrCreateTerminal as any).mockResolvedValue(mockTerminal)
+
+			const options: ExecuteCommandOptions = {
+				executionId: "test-execution-id",
+				command: "npm run dev",
+				runInBackground: true,
+				terminalShellIntegrationDisabled: true,
+				terminalOutputLineLimit: 500,
+				terminalOutputCharacterLimit: 10000,
+				commandExecutionTimeout: 0,
+			}
+
+			// Execute the command
+			const [rejected] = await executeCommand(mockTask, options)
+
+			// Wait for async operations to complete
+			await new Promise((resolve) => setTimeout(resolve, 100))
+
+			expect(rejected).toBe(false)
+			expect(TerminalRegistry.getOrCreateTerminal).toHaveBeenCalledWith("/test/directory", undefined, "execa")
+			expect(mockTerminal.runCommand).toHaveBeenCalledWith("npm run dev", expect.any(Object))
+			expect(mockProcess.continue).toHaveBeenCalled()
+
+			// The task.ask method should not be called since runInBackground skips user interaction
+			// Note: We can't verify this directly since the callback is async and may not be called
+			// in this test scenario, but the important thing is that the command completes successfully
+		})
+	})
 })

src/core/tools/__tests__/executeCommandTool.spec.ts

@@ -66,8 +66,8 @@ beforeEach(() => {
 
 		// Get the custom working directory if provided
 		const customCwd = block.params.cwd
-
-		const [userRejected, result] = await mockExecuteCommand(cline, block.params.command, customCwd)
+		const runInBackground = block.params.runInBackground === "true"
+		const [userRejected, result] = await mockExecuteCommand(cline, block.params.command, customCwd, runInBackground)
 
 		if (userRejected) {
 			cline.didRejectTool = true
@@ -309,4 +309,41 @@ describe("executeCommandTool", () => {
 			expect(mockOptions.commandExecutionTimeout).toBeDefined()
 		})
 	})
+
+	describe("runInBackground parameter", () => {
+		it("should extract runInBackground parameter when set to 'true'", async () => {
+			mockToolUse.params.command = "npm run dev"
+			mockToolUse.params.runInBackground = "true"
+
+			await executeCommandTool(
+				mockCline as unknown as Task,
+				mockToolUse,
+				mockAskApproval as unknown as AskApproval,
+				mockHandleError as unknown as HandleError,
+				mockPushToolResult as unknown as PushToolResult,
+				mockRemoveClosingTag as unknown as RemoveClosingTag,
+			)
+
+			expect(mockExecuteCommand).toHaveBeenCalled()
+			const lastCall = mockExecuteCommand.mock.calls[mockExecuteCommand.mock.calls.length - 1]
+			expect(lastCall[3]).toBe(true) // runInBackground parameter should be true
+		})
+
+		it("should default runInBackground to false when parameter is missing", async () => {
+			mockToolUse.params.command = "echo test"
+
+			await executeCommandTool(
+				mockCline as unknown as Task,
+				mockToolUse,
+				mockAskApproval as unknown as AskApproval,
+				mockHandleError as unknown as HandleError,
+				mockPushToolResult as unknown as PushToolResult,
+				mockRemoveClosingTag as unknown as RemoveClosingTag,
+			)
+
+			expect(mockExecuteCommand).toHaveBeenCalled()
+			const lastCall = mockExecuteCommand.mock.calls[mockExecuteCommand.mock.calls.length - 1]
+			expect(lastCall[3]).toBe(false) // runInBackground parameter should be false
+		})
+	})
 })

src/core/tools/executeCommandTool.ts

@@ -30,6 +30,7 @@ export async function executeCommandTool(
 ) {
 	let command: string | undefined = block.params.command
 	const customCwd: string | undefined = block.params.cwd
+	const runInBackground: boolean = block.params.runInBackground === "true"
 
 	try {
 		if (block.partial) {
@@ -94,6 +95,7 @@ export async function executeCommandTool(
 				terminalOutputLineLimit,
 				terminalOutputCharacterLimit,
 				commandExecutionTimeout,
+				runInBackground,
 			}
 
 			try {
@@ -141,6 +143,7 @@ export type ExecuteCommandOptions = {
 	terminalOutputLineLimit?: number
 	terminalOutputCharacterLimit?: number
 	commandExecutionTimeout?: number
+	runInBackground?: boolean
 }
 
 export async function executeCommand(
@@ -153,6 +156,7 @@ export async function executeCommand(
 		terminalOutputLineLimit = 500,
 		terminalOutputCharacterLimit = DEFAULT_TERMINAL_OUTPUT_CHARACTER_LIMIT,
 		commandExecutionTimeout = 0,
+		runInBackground: runInBackgroundRequested = false,
 	}: ExecuteCommandOptions,
 ): Promise<[boolean, ToolResponse]> {
 	// Convert milliseconds back to seconds for display purposes.
@@ -174,7 +178,7 @@ export async function executeCommand(
 	}
 
 	let message: { text?: string; images?: string[] } | undefined
-	let runInBackground = false
+	let runInBackground = runInBackgroundRequested
 	let completed = false
 	let result: string = ""
 	let exitDetails: ExitCodeDetails | undefined
@@ -195,7 +199,10 @@ export async function executeCommand(
 			const status: CommandExecutionStatus = { executionId, status: "output", output: compressedOutput }
 			provider?.postMessageToWebview({ type: "commandExecutionStatus", text: JSON.stringify(status) })
 
-			if (runInBackground) {
+			// If runInBackgroundRequested, automatically continue the process
+			if (runInBackgroundRequested && !completed) {
+				completed = true
+				process.continue()
 				return
 			}
 

src/shared/tools.ts

@@ -67,6 +67,7 @@ export const toolParamNames = [
 	"todos",
 	"prompt",
 	"image",
+	"runInBackground",
 ] as const
 
 export type ToolParamName = (typeof toolParamNames)[number]
@@ -82,7 +83,7 @@ export interface ToolUse {
 export interface ExecuteCommandToolUse extends ToolUse {
 	name: "execute_command"
 	// Pick<Record<ToolParamName, string>, "command"> makes "command" required, but Partial<> makes it optional
-	params: Partial<Pick<Record<ToolParamName, string>, "command" | "cwd">>
+	params: Partial<Pick<Record<ToolParamName, string>, "command" | "cwd" | "runInBackground">>
 }
 
 export interface ReadFileToolUse extends ToolUse {