## Background mode
For long-running non-interactive commands (e.g. starting a dev server that must keep running), set `background: true` (default false). The command then keeps running after this tool call returns:
- The tool returns the path of the command's output file (in the OS temp area's `.agent` directory). All output — stdout and stderr — is written to that file RAW: no truncation, no filtering, no credential scrubbing. Do not run commands that print secrets in background mode.
- Do NOT append a trailing `&` (shell background operator) to the command — `background: true` already detaches it, and a `&` makes the wrapping shell exit immediately, so the session's watchdog treats the command as finished and kills the long-running process you meant to keep alive.
- Read progress with the read tool on that path. When the command exits, the line `[exit status: N]` is appended to the end of the file UNCONDITIONALLY — including exit 0 (signal kills read `[exit status: terminated by signal]`). Its presence with ANY exit code is the only signal that the command finished; its absence means the command is still running. Do not treat a non-zero exit as a launch failure — it is a normal completion.
- `timeout_secs` is IGNORED in background mode. The command runs until it exits, you stop it, or your run ends.
- Stop the session with the same tool: pass only `stop: "<output-file-path>"` (the exact path returned by the launch). Stop is two-stage: SIGTERM, ~5s grace, then SIGKILL to the whole process group. Stopping an already-finished session is a no-op. Do not combine `stop` with `background` or `command`.
- Sessions are strictly scoped to the agent that started them: no other agent can read or stop them, and they are force-killed when your run ends (success, error, or abort). Never assume a background process survives past your run — if you need it later, restart it.
- Launch failures (command not found, not executable) are returned as a tool error immediately — check the tool response before assuming the session started.
Caveats: output is unbounded — a command that prints forever will fill the temp disk. Prefer commands that write modest output, and tail large outputs via the shell tool (the read tool caps text files at 10 MB). Output files persist in the temp area until the periodic temp cleaner or the OS temp sweep reclaims them (the daemon performs no startup purge).
Background-mode greps are NOT served by the engine — `background: true` runs the real system `grep`, so the Grep notes below do not apply to it.