anthropics / anthropics/claude-code

[FEATURE] SessionIdle hook event with exit-2 continuation for any session (generalizes TeammateIdle; reopens #68060)

Open
#94,812 0 comments 0 reactions 0 assignees View on GitHub
area:agents area:hooks enhancement platform:macos
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.