[FEATURE] Expose "waiting for user input" session state in `claude agents --json` and/or the statusline payload
Preflight Checklist
- [x] I searched existing requests before filing. Closest priors — all closed as stale by the bot with guidance to open a new issue if still relevant: #38184 (reliable session state detection API), #40589 (add state field to statusline JSON), #52856 (headless
claude status --json). This request is narrower than #52856 and fresher than #40589: it asks for one specific signal, with current-version verification. - [x] This is a single feature request.
Problem Statement
Multi-session ("fleet") setups need to distinguish a session blocked waiting for a human reply from a session that is simply idle. Today neither supported surface exposes that:
claude agents --jsonreports onlybusy/idle. Verified on v2.1.220 with a live interactive session: a session that just asked the user a question and is waiting reportsidle. (During a boot-time trust-folder dialog, the session does not appear in the list at all.)- The statusline JSON payload (verified on v2.1.226) includes
session_id,model,effort,cost,context_window,transcript_path,version… but no session-state field.
The only workaround is parsing the .jsonl transcripts (compare last inbound message vs last assistant reply). That is an undocumented internal format that changes across releases, so every tool built on it breaks regularly. Tooling authors who deliberately restrict themselves to contractual surfaces (CLI JSON output, statusline payload) currently cannot offer this signal at all.
Proposed Solution
Either surface would work (both would be ideal):
claude agents --json: extendstatuswith awaiting_for_inputvalue (or add a booleanwaiting_for_inputfield), optionally withwaiting_since.- Statusline JSON payload: add a
session_statefield (e.g.working/waiting_for_input/idle).
Claude Code necessarily knows this state internally (the TUI renders it); the request is only to expose it on an already-supported machine-readable surface.
Use Cases
- Fleet dashboards / observability tools: "session X has been waiting for you for 2 h" is the single most actionable signal for a human operating several sessions.
- Orchestrators and lifecycle automation: a recycler/restarter must not kill a session that is waiting on a human answer — today it cannot tell.
- Notification systems: alert only on waiting, stay silent on idle.
Additional Context
Environment: Claude Code v2.1.226, macOS (darwin). Happy to provide the test transcripts or re-run verifications on newer builds.
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗