# Background Agent Execution

## How it works

The parent agent decides at dispatch time whether a sub-agent runs in background by passing `background: true` in the tool input. The sub-agent doesn't know or care — it runs identically to foreground.

### Dispatch

```
visualDesignExpert({ task: "...", background: true })
productVision({ task: "...", background: true })
```

### Split lifecycle (runner.ts)

When `background: true`:

1. The runner creates its own AbortController (detached from the parent turn signal)
2. The sub-agent's LLM runs normally — streaming, thinking, tool calls
3. After the first LLM turn that produces text content, the runner **resolves the parent's promise early** with that text + `backgrounded: true`
4. The sub-agent loop continues in the background — more tool calls, more LLM turns
5. On completion, `onBackgroundComplete` fires, pushing the result to the notification queue

The parent agent gets the initial response immediately and continues its turn. The background agent keeps working.

### Result delivery (headless.ts)

A notification queue collects background completions. Delivery:

- **If Remy is idle** — deliver immediately as a hidden automated message
- **If Remy is mid-turn** — queue and flush after `turn_done`
- **Multiple completions** — batched into one message

Format (hidden, XML-tagged):
```
@@automated::background_results@@
<background_results>
<tool_result id="toolu_abc" name="visualDesignExpert">
Result text here...
</tool_result>
</background_results>
```

### Events

The `tool_start` event includes `background: true` when a tool is backgrounded. The frontend knows every subsequent event with that `parentToolId` is background work — no need to flag every individual event.

### Process management

Background agents stay in the tool registry after the parent's promise settles. The existing `stop_tool` and `restart_tool` stdin commands work on them. Stopping a background agent via `stop_tool` is how users cancel dangling work.

### Which sub-agents support this?

- **designExpert** — return font/color/layout recommendations immediately, generate images in background
- **productVision** — return initial plan immediately, write roadmap files in background
- **codeSanityCheck** — NOT a candidate, Remy needs the advice before proceeding
- **browserAutomation** — NOT a candidate, results inform Remy's next action

## Future considerations

- **Resource budgets** — token/cost ceilings for background agents running unattended
- **Checkpoint/resume** — serialized state for surviving process restarts
- **Speculative execution** — start work optimistically, cancel if the parent's reasoning goes a different direction
- **Fan-out** — dispatch multiple background agents in parallel, collect results