Launch a Background Job

启动一个后台任务

Pass run_in_background: true to the bash tool. It returns a handle bg-N immediately instead of blocking:

给 bash 传 run_in_background: true，它立即返回句柄 bg-N：

bash(command="go build ./...", run_in_background=true)
→ [bg: started bg-1] $ go build ./...
  Track with: monitor(job="bg-1", action=poll|wait|kill).

• No timeout — background mode ignores timeout_ms. The job runs until it exits, is killed, or the session ends.
• 后台模式下 timeout_ms 被忽略——任务一直跑到退出、被杀、或会话结束。
• Best for: long builds, full test suites, dev servers, file watchers.
• 适用场景：长 build、完整测试套件、dev server、文件 watcher。

Track with monitor

用 monitor 跟踪

poll (default) — incremental output since last check

poll（默认）——看自上次以来的新输出 + 状态

monitor(job="bg-1")
→ [bg-1: running, elapsed=12s]
  <new output since last poll>

Cursor is server-side — each poll returns only incremental output. No new output = (no new output).

游标是服务端记的——每次 poll 只给你增量输出。

wait — block until exit / match / timeout

wait——阻塞直到完成 / 命中 / 超时

monitor(job="bg-1", action=wait, timeout_ms=60000)
→ [bg-1: exited code=0, elapsed=43s]
  <final output>

Three exit paths: task exits, until_regex matches ("Listening on" for a dev server), or timeout.

三条退出路径：任务退出、until_regex 命中（如 dev server 的 "Listening on"）、超时。

Cancelling a wait (Esc) stops observing but leaves the job running.

取消 wait（Esc）停止观察但让任务继续跑。

kill — terminate

kill——终止

monitor(job="bg-1", action=kill)
→ [bg-1: killed, elapsed=67s]

Lifecycle

生命周期

• Jobs live until: they exit, you kill them, or the session ends.
• 任务一直存活到：自己退出、被 kill、或会话结束。
• Not persisted across restarts — bg jobs never survive a session restart.
• 不跨重启——后台任务不会在会话重启后存活。
• Up to N concurrent jobs (ring buffer). Oldest job is evicted on overflow.
• 最多 N 个并发任务（环形缓冲），溢出时淘汰最老的。

Design: PRD feature-bash-monitor.md

设计文档：PRD feature-bash-monitor.md