anthropics / anthropics/claude-code
[FEATURE] SessionIdle hook event with exit-2 continuation for any session (generalizes TeammateIdle; reopens #68060)
- Dominant language
- Python
- Stars
- 145k
- Forks
- 23.1k
- PR merge metrics
- PR metrics pending
Description
### Preflight Checklist
- [ ] I have searched [existing requests](https://github.com/anthropics/claude-code/issues?q=is%3Aissue%20label%3Aenhancement) and this feature hasn't been requested yet (prior request #68060 was closed as inactive; this request expands it)
- [x] This is a single feature request (not multiple features)
### Problem Statement
Hooks fire on actions (`Stop`, tool events, prompt submit); nothing fires while a session sits idle. Agent teams have `TeammateIdle`, which can exit 2 to send feedback and keep a teammate working, but only for teammates spawned by a lead. Independent sessions coordinated by an external orchestrator (our setup: Claude Code and Codex sessions in tmux with a shared task ledger) have no equivalent, so an idle session with work waiting in the ledger cannot be woken by a hook without injecting keystrokes. #68060 asked for an idle/timeout hook for handoffs and was closed as inactive.
### Proposed Solution
- New event `SessionIdle` for the main session: fires once when a turn ends with nothing queued, then at a configurable debounce while the session stays idle (for example `idle_seconds: 120`, capped to a few firings per hour by default).
- Payload: the common fields plus `idle_seconds`, `last_turn_ended_at`, `pending_inbox_count` (held or queued cross-session messages) and `context_window_used_pct`.
- Exit 2 with text on stdout starts a new turn with that text as instructions, the same way `Stop` exit 2 continues and `TeammateIdle` exit 2 keeps a teammate working. Exit 0 does nothing.
- A matcher on `first | repeat` so a hook can run a handoff on the first idle and a cheap check afterwards.
### Alternative Solutions
An external watcher polls the transcript's mtime and injects keystrokes with tmux send-keys, which the model then sees as user input. A Stop hook cannot fire while the session is already idle. Cross-session SendMessage can start a turn in an idle session, but requires another Claude Code session as the sender and delivers as a peer message rather than a hook instruction.
### Priority
High - Significant impact on productivity
### Feature Category
Developer tools/SDK
### Use Case Example
A SessionIdle hook runs a script that reads the team's shared task ledger. If a task is assigned to this session and unacknowledged, the hook exits 2 with "Task T is assigned to you; read your inbox and acknowledge", which starts a new turn. If nothing is assigned, it exits 0 and the session stays idle at zero cost.
### Additional Context
Claude Code 2.1.273, macOS 26.6. Related: #68060 (closed), #91541 (durable cross-runtime messaging for Agent Teams).
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reading the existing Stop and TeammateIdle hook behavior, then review related issues #68060 and #91541 for prior context. Done means defining and implementing SessionIdle semantics, payload fields, first/repeat matching, debounce behavior, and exit-2 continuation without requiring keystroke injection.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- cli, developer-experience, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100