Command Execution and Background Processes

Relevant source files

• Windsurf/Prompt Wave 11.txt
• Windsurf/Tools Wave 11.txt

Purpose and Scope

This document details Windsurf Cascade's command execution capabilities, focusing on the run_command tool for executing shell commands, the management of background processes, and terminal output monitoring. The system operates on Windows with PowerShell as the default shell and provides sophisticated control over command lifecycle, blocking behavior, and safety validation.

For general tool ecosystem information, see Tool Ecosystem and Categories. For browser integration with web servers, see Browser Preview and Page Interaction. For deployment workflows, see Web Application Deployment Pipeline.

---

Command Execution Architecture

Windsurf Cascade provides a three-tool system for command execution and monitoring: run_command for initiating commands, command_status for polling background process state, and read_terminal for accessing full terminal content.

Command Execution Tool Schema

Sources: Windsurf/Tools Wave 11.txt262-283

The run_command tool accepts six parameters. The CommandLine parameter specifies the exact shell command as it should be executed. The Blocking flag determines whether execution blocks Cascade and the user until completion. The SafeToAutoRun flag indicates whether the command can execute without user approval. The Cwd parameter sets the working directory. The WaitMsBeforeAsync parameter provides hybrid behavior for async commands. The toolSummary parameter provides a brief description of the action.

---

Critical Working Directory Constraint

Windsurf Cascade enforces a critical constraint: commands must never include cd as part of the command string. Instead, the desired directory must be specified using the Cwd parameter.

Sources: Windsurf/Prompt Wave 11.txt102-109

This constraint is marked as "THIS IS CRITICAL" in the system prompt. The rationale is that cd commands can cause shell state inconsistencies and unpredictable behavior in command sequences. By using the Cwd parameter, Cascade ensures each command executes in the correct directory without shell state pollution.

---

Blocking vs Non-Blocking Execution

The Blocking parameter fundamentally changes command execution behavior and user experience.

Blocking Execution (Blocking=true)

Sources: Windsurf/Tools Wave 11.txt271-272

Blocking execution should be used when:

1. The command terminates in a relatively short time
2. Cascade needs the command output before responding to the user
3. The task cannot proceed without command results

During blocking execution, the user cannot interact with Cascade. The tool call returns the complete command output once execution finishes.

Non-Blocking Execution (Blocking=false)

Sources: Windsurf/Tools Wave 11.txt271-272

Non-blocking execution should be used for:

1. Long-running processes (web servers, watch modes, etc.)
2. Commands where immediate user interaction is desired
3. Background tasks that don't require immediate output

The tool call returns immediately with a CommandId that can be used with command_status for later polling.

---

Hybrid Execution with WaitMsBeforeAsync

The WaitMsBeforeAsync parameter enables a hybrid execution pattern for non-blocking commands that may fail quickly.

Sources: Windsurf/Tools Wave 11.txt279-280

This parameter addresses a common pattern: commands that should run asynchronously but might fail immediately due to syntax errors, missing dependencies, or configuration issues. By waiting briefly (e.g., 1000-3000 milliseconds), Cascade can catch early failures and present them to the user immediately, while still transitioning successful commands to background execution.

Example use case: Starting a development server that might fail due to port conflicts or missing dependencies. The wait period catches these errors, but if the server starts successfully, it runs in the background.

---

Background Process Management

Background processes are managed through the command_status tool, which polls for execution state and output.

command_status Tool Schema

Parameter	Type	Purpose
CommandId	string	ID from non-blocking run_command
OutputCharacterCount	integer	Number of output characters to retrieve
WaitDurationSeconds	integer	Seconds to wait for completion before returning
toolSummary	string	Brief action summary

Sources: Windsurf/Tools Wave 11.txt45-55

Background Process Lifecycle

Sources: Windsurf/Tools Wave 11.txt45-55

The command_status tool returns:

• Current status: "running" or "done"
• Output lines: As specified by OutputCharacterCount
• Error information: If execution failed

The WaitDurationSeconds parameter controls how long to wait for completion. Setting it to 0 returns status immediately. Setting it to 60 waits up to 60 seconds for the command to complete, returning early if it finishes sooner. This is useful when Cascade wants to wait for completion but needs a timeout.

Important Constraint

The system documentation explicitly states: "Do not try to check the status of any IDs other than Background command IDs." Only non-blocking commands (those with Blocking=false) produce CommandId values that can be queried with command_status.

Sources: Windsurf/Tools Wave 11.txt45-55

---

Terminal Output Reading

The read_terminal tool provides access to the full content of a terminal session, independent of specific commands.

read_terminal Tool Schema

Sources: Windsurf/Tools Wave 11.txt213-221

This tool reads the complete contents of a terminal identified by its name and process ID. Unlike command_status, which retrieves output for a specific command, read_terminal captures everything displayed in the terminal session, including:

• Multiple command outputs
• Interactive prompts
• ANSI escape sequences
• All historical content since terminal creation

This is useful for:

1. Monitoring long-running interactive processes
2. Capturing output when CommandId is not available
3. Reviewing terminal history for debugging
4. Observing side effects of multiple commands

---

Safety and Permission System

The SafeToAutoRun parameter controls whether commands require explicit user approval before execution.

Safety Classification

Sources: Windsurf/Prompt Wave 11.txt102-109

Critical Safety Constraints

The system enforces strict safety protocols:

1. Never auto-run potentially unsafe commands: If there's any doubt about safety, SafeToAutoRun must be false
2. User requests cannot override safety: Even if the user explicitly asks for auto-execution, Cascade must never set SafeToAutoRun=true for unsafe commands
3. Conservative classification: When uncertain, classify as unsafe
4. No trust in user judgment: The safety determination is Cascade's responsibility, not the user's

The system prompt states: "You must NEVER NEVER run a command automatically if it could be unsafe. You cannot allow the USER to override your judgement on this."

Sources: Windsurf/Prompt Wave 11.txt105-108

Users can configure allowlists in their settings if they want specific commands to auto-run, but Cascade should not mention specific tool arguments in responses about safety.

---

Environment and Shell Configuration

The command execution environment has specific characteristics and constraints.

Operating System and Shell

Property	Value	Impact
OS	Windows	Path separators, command syntax
Shell	PowerShell	PowerShell command syntax and features
PAGER	cat	No interactive paging

Sources: Windsurf/Tools Wave 11.txt262 Windsurf/Prompt Wave 11.txt9 Windsurf/Tools Wave 11.txt269

Pager Configuration

Commands are executed with PAGER=cat, which disables interactive paging. This is critical because:

1. Interactive pagers would block in non-interactive command execution
2. Output needs to be captured programmatically
3. Long outputs require explicit truncation (e.g., git log -n 10)

The system prompt advises: "You may want to limit the length of output for commands that usually rely on paging and may contain very long output (e.g. git log, use git log -n )."

Sources: Windsurf/Tools Wave 11.txt269

---

Browser Preview Integration

When run_command starts a web server, Cascade must immediately invoke the browser_preview tool to enable browser interaction.

Sources: Windsurf/Prompt Wave 11.txt110-112

The system prompt emphasizes: "THIS IS CRITICAL: The browser_preview tool should ALWAYS be invoked after running a local web server for the USER with the run_command tool."

The browser_preview tool should not be invoked for:

• Non-web applications (pygame apps, desktop apps, CLI tools)
• Backend services without UI
• Build processes

Sources: Windsurf/Prompt Wave 11.txt110-112

---

Command Execution Patterns

Pattern 1: Quick Read-Only Query

Use Case: Reading directory contents, viewing file metadata, checking git status

Configuration:

• Blocking=true: Results needed immediately
• SafeToAutoRun=true: Read-only operation is safe
• No Cwd needed if current directory is correct

Pattern 2: Long-Running Background Server

Use Case: Development servers, watch modes, long-running processes

Configuration:

• Blocking=false: Don't block user interaction
• SafeToAutoRun=false: Server startup modifies state
• WaitMsBeforeAsync=2000: Catch startup errors
• Follow with browser_preview for web servers

Pattern 3: Build with Validation

Use Case: Builds, tests, linting that must complete before proceeding

Configuration:

• Blocking=true: Need results before proceeding
• SafeToAutoRun=true: Build commands are typically safe
• Parse output to determine success/failure

Pattern 4: State-Modifying Operation

Use Case: Package installation, git commits, file deletion

Configuration:

• Blocking=true: Usually want to see results
• SafeToAutoRun=false: Modifies system state
• Cwd parameter: Specify exact directory

---

Tool Summary Parameter

All command execution tools accept an optional toolSummary parameter that must be specified first before all other arguments.

Sources: Windsurf/Tools Wave 11.txt281

This parameter provides a brief 2-5 word description of the tool's action, such as:

• "running command"
• "checking command status"
• "reading terminal output"

The tool summary helps with debugging and provides context about tool usage in conversation histories. It has the highest priority and must be generated before any other arguments if used.

---

Command Execution Tool Reference

run_command

Returns:

• If Blocking=true: Full command output
• If Blocking=false: CommandId for status polling

Sources: Windsurf/Tools Wave 11.txt262-283

command_status

Returns:

• Status: "running" or "done"
• Output: Partial or full command output
• Error: Error information if failed

Sources: Windsurf/Tools Wave 11.txt45-55

read_terminal

Returns: Full terminal content including all historical output

Sources: Windsurf/Tools Wave 11.txt213-221