## 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.
- {{trailing_separator}}
- 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 (`[exit status: terminated by signal]` if a signal ended it). 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_semantics}} 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 when your run ends — success, error, or abort — the session's process tree is destroyed. 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. That check is Unix-only: on Windows a missing or non-executable command starts a session whose file holds the interpreter's error and ends with `[exit status: 1]`.
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` bypasses the interception, so the Grep notes below do not apply to it: the `grep` that runs is the host's own, if the host has one.