[FEATURE] Expose "waiting for user input" session state in `claude agents --json` and/or the statusline payload

Status Open
Maintainer reply None cached
Activity 2 comments · opened Aug 9, 2026

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 --json reports only busy / idle. Verified on v2.1.220 with a live interactive session: a session that just asked the user a question and is waiting reports idle. (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):

  1. claude agents --json: extend status with a waiting_for_input value (or add a boolean waiting_for_input field), optionally with waiting_since.
  2. Statusline JSON payload: add a session_state field (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.

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗