Status update (2026-05-08)

The main Phase C work for this issue has landed through #3684 and follow-ups:

• feat(core): event monitor tool with throttled stdout streaming (Phase C) #3684 added the Monitor tool, MonitorRegistry, throttled stdout/stderr event notifications, idle/max-event self-stop, and the monitor task kind.
• feat(cli): wire Monitor entries into combined Background tasks dialog #3791 wired monitor entries into the combined Background tasks pill/dialog.
• feat(core): add Monitor(...) permission namespace #3726 added the dedicated Monitor(...) permission namespace.
• fix(monitor): correct Windows taskkill spawn assertion to include stdio option #3784 and fix(core): address post-merge monitor tool and UI routing issues #3792 covered post-merge Windows / throttle / UI-routing fix-ups.

One important correctness gap remained for subagent usage: when a subagent started a monitor, monitor notifications were routed to the parent agent instead of the subagent that owned the monitor. That is tracked by #3925 and fixed in #3933.

After #3933 merges, this issue's core requirement — long-running monitor output being pushed back to the agent that started the monitor — should be covered for top-level agents, foreground/background subagents, forked agents, and resumed background agents.

Explicitly not treated as a blocker for this issue: extending send_message to monitor entries. Per the #3634 roadmap discussion, monitor/shell entries do not currently have a receiver-side message protocol, so send_message remains agent-only in v1. task_stop already covers monitor cancellation.

Recommended closure condition: close this issue once #3933 is merged.

Parent

Phase C from the background task management roadmap: #3634

Motivation

Today the agent has no way to run a long-lived watcher (tail -F, inotifywait, polling loops) and receive events back asynchronously. It either blocks the turn with a foreground bash or fire-and-forgets a background shell. The event monitor fills this gap: a new Monitor tool whose stdout lines push events back to the agent with sensible throttling.

Scope

Core (no PR dependencies — can start now)

• New Monitor tool: long-running script, stdout lines pushed back to the agent via feat: background subagents with headless and SDK support #3076's task_notification framework
• Throttling: configurable rate limiting so a noisy watcher doesn't flood the agent
• Self-stop: monitor auto-terminates after configurable idle timeout or max events
• MonitorRegistry: independent registry mirroring the lifecycle shape of BackgroundShellRegistry (feat(core): managed background shell pool with /tasks command #3642) — running / completed / failed / cancelled, AbortController, output capture
• New entry kind: monitor

Follow-up (gated on #3471 / #3488 landing)

• Wire monitor entries into unified pill / dialog / task_stop (~100-200 LOC)
• BashTool ergonomics: detect tail -f / polling-loop intents and suggest Monitor instead

Design points

Per the aligned design in #3634:

1. BackgroundTaskEntry with kind: 'monitor'
2. Same task_stop cancellation path (follow-up)
3. Same send_message steering path where applicable (follow-up)
4. Unified transcript path: <projectDir>/tasks/<sessionId>/monitor-<id>.jsonl
5. Two-layer PR cleavage: core plumbing PR + per-kind UI integration follow-up

Related

• Background task management: roadmap and next steps #3634 — Background tasks roadmap
• feat: background subagents with headless and SDK support #3076 — Background subagents + task_notification framework (merged)
• feat(core): managed background shell pool with /tasks command #3642 — Managed background shell pool (Phase B, in review)
• feat(core): model-facing agent control (task_stop, send_message, per-agent transcript) #3471 — Model-facing agent control (task_stop / send_message)
• feat(cli): background-agent UI — pill, combined dialog, detail view #3488 — User-facing background-agent UI (pill / dialog)