ollie-9p/prompts/tools-process.md

Background Processes

Start, monitor, and manage background processes that outlive a single tool call.

Starting a background process

Use detach: true on an execute_code step to immediately background the process:

execute_code: steps=[{code: "make test", detach: true}]
execute_code: steps=[{code: "./run-server.sh", detach: true}]

Returns: partial output + [detached: pid N]. The process continues running; its stdout/stderr are captured in a 64KB ring buffer.

Inspecting background processes

Tool	Args	Purpose
process_list	(none)	List all detached processes: PID, command, status, start time
process_output	<pid>	Read the last 64KB of combined stdout/stderr
process_signal	<pid> [TERM|KILL]	Send a signal (default: TERM)
process_dismiss	<pid>	Remove a finished process from the list

call_tool: calls=[{tool: "process_list"}]
call_tool: calls=[{tool: "process_output", args: ["12345"]}]
call_tool: calls=[{tool: "process_signal", args: ["12345", "TERM"]}]
call_tool: calls=[{tool: "process_dismiss", args: ["12345"]}]

When to use

• Long-running builds (make, cargo build) where you want to do other work while waiting
• Servers or daemons you need running during the session
• Tests that take a long time to complete
• Any command where blocking the agent is wasteful

Lifecycle

1. Launch: detach: true → get PID
2. Poll: process_output <pid> to check progress
3. React: read output, decide if done or needs intervention
4. Clean up: process_signal to stop, process_dismiss to remove from list

Auto-notification: when a detached process exits, its final output (last 2KB) is automatically injected into the agent's context. You don't need to poll for completion — you'll be notified.

Constraints

• detach: true is per-step. Can combine with elevated: true. Cannot combine with parallel.
• Ring buffer is 64KB — older output is overwritten. For large output, redirect to a file within the command itself.
• PID args must be strings (tool convention): args: ["12345"] not args: [12345].