wake_when_idle
Wake when watched agents go idle or a timeout passes, holding delivery until pane input clears. Use one-shot for specific agents or a standing watch for all project workers.
Instructions
Wake up when watched agents go idle (exact state from Claude Code hooks) or max_wait_seconds passes - except delivery HOLDS past that bound instead, for as long as the target pane is on a dialog or has unsubmitted human text in it, rather than pasting the wake body into either (.claude/rules/tmux-and-panes.md). Two shapes, and you pass EXACTLY ONE of them. agents=[...] is a ONE-SHOT over a named list: mode=any fires on the first fresh idle transition, mode=all fires when every watched agent is idle (returns already_satisfied without scheduling anything if they all are now), and either way it stops watching once it fires. scope="project" is a STANDING WATCH over the crew you spawn in this project, including workers spawned later: it never stops watching, and on each finish it delivers a roster naming who finished and who is still going, until max_wait_seconds runs out or you wake_cancel it. You may hold ONE standing watch per project: a second call is refused and names the one already running, since two would report every finish twice. Use the standing watch when you are running more than one worker - a one-shot leaves every other worker unwatched from the moment it fires. Use either instead of polling. Refuses a lead target: a lead has no idle/working state channel.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | ||
| mode | No | Defaults to any. Only meaningful with agents. | |
| scope | No | Watch the crew you spawn in this project as a STANDING watch that keeps watching after each finish, including workers spawned later. Mutually exclusive with agents. | |
| agents | No | Agents to watch, as a ONE-SHOT. Mutually exclusive with scope. | |
| deliver_to | No | Deliver to a spawned agent instead of this session. | |
| project_id | No | Different project override. Use ONLY when the user explicitly asks for another project by name; otherwise stay in the current scope, even when results are empty. | |
| max_wait_seconds | No | For agents=[...]: how long to wait for idle before firing anyway, default 900. For scope="project": THE WATCH'S LIFETIME, default 14400 (4 hours), after which it delivers one last wake saying it has expired and stops watching. Not a hard deadline either way: delivery holds past it while the target pane is on a dialog or has unsubmitted text, until the pane clears. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | ||
| note | No | ||
| scope | No | ||
| status | No | ||
| wake_id | No | ||
| standing | No | ||
| watching | No | ||
| deliver_to | No | ||
| expires_at | No | ||
| watching_now | No | ||
| max_wait_seconds | No |