# 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]`.