Subagent liveness/death observability for long-running orchestrators (per-agent deadline, crash-path notification, status poll)

Summary

A long-running orchestrator session that spawns background subagents (via the Agent tool) currently has no reliable way to learn when a subagent crashes or its connection drops mid-run. Normal completion notifies, and — since v2.1.199 — a subagent ending on an API error reports back with its last output (much appreciated). But a harness-level crash / socket drop appears to produce no notification, no timeout, and no status signal, so an event-driven orchestrator can idle indefinitely on a dead subagent until a human intervenes.

This is a request for subagent liveness/death observability so orchestrators can guarantee a bounded-time wake for every spawned unit of work. Three concrete, independently-useful asks:

1. Per-agent deadline / timeout on the Agent tool

An optional max-duration on a spawned (background) subagent. On expiry the harness marks it failed and delivers the same kind of failure notification the API-error path already produces (naming a timeout, including last output). Today any deadline must be implemented entirely orchestrator-side.

2. Guaranteed crash-path death notification

When a background subagent dies from a crash or connection drop (not an API error), deliver a failure notification to the parent, symmetric with the v2.1.199 API-error behavior. Right now this path is undocumented and appears silent — it is the core gap.

3. A status-poll API for spawned agents

A parent-callable AgentStatus-style query returning, per spawned agent: running | completed | failed, plus a last-activity timestamp. This lets an orchestrator pull liveness rather than depend solely on pushed events. (We currently emulate this by stat-ing the subagent transcript file's mtime under ~/.claude/projects/…/subagents/agent-<id>.jsonl — which works but relies on an undocumented path layout.)

Context / why

We run a persistent "merge orchestrator" session that spawns short-lived subagents to do bounded units of work (rebase a branch, apply a CI fix, review a diff). When a subagent goes quiet from a socket-level failure, the orchestrator — being event-driven — has no wake to react to and stalls. We can (and do) work around it with an orchestrator-side watchdog: a spawn registry with per-task deadlines, a monitor that treats stale transcript mtime as "no progress," and a SendMessage probe (which usefully auto-resumes a dead-with-transcript subagent). That mitigation is viable today, but items 1–3 would let the harness provide the signal directly instead of every orchestrator re-deriving it.

Happy to split this into three issues if that suits triage. Thanks for the recent API-error-reporting improvement — it already closed part of this gap.