hive

Overview Schema Source Related Servers Discussions Admin

wake_when_idle

Wake you when watched agents or project crews go idle, replacing polling. Supports one-shot agent lists or standing project watches, with delivery held during dialogs or unsubmitted text.

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 for workers, plus one for the queen, 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. Arming a one-shot of the same mode for the same deliver target and an identical watched set cancels your own older pending one and names it in the receipt's superseded. 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. agents=[...] refuses a lead: it watches worker state, which a lead does not write. lead_project_id is the QUEEN's alone: a one-shot that fires when another registered project's running lead ENDS A TURN (never 'finished its work'), stored in and delivered to the queen's own project, and ended with a named reason if that lead's pane dies, is reissued, or restarts.

Input Schema

TableJSON Schema

Name	Required	Description
`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.
`lead_project_id`	No	QUEEN ONLY: wake when the running lead of this OTHER registered project ends a turn. The wake is stored in the queen's own project and delivered only to the queen; the watched lead is read, never typed into. Mutually exclusive with agents and scope; refuses project_id and deliver_to.
`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

TableJSON 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
`lead_watch`	No
`superseded`	No
`hive_notice`	No
`watching_now`	No
`max_wait_seconds`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.7.0Oct 5, 2026

addedOutput schema / properties / superseded

Added value: +{
+  "items": {
+    "exclusiveMinimum": 0,
+    "maximum": 9007199254740991,
+    "type": "integer"
+  },
+  "type": "array"
+}

Changed2 schema fields changedv1.4.0Sep 30, 2026

addedInput schema / properties / lead_project_id

Added value: +{
+  "description": "QUEEN ONLY: wake when the running lead of this OTHER registered project ends a turn. The wake is stored in the queen's own project and delivered only to the queen; the watched lead is read, never typed into. Mutually exclusive with agents and scope; refuses project_id and deliver_to.",
+  "exclusiveMinimum": 0,
+  "maximum": 9007199254740991,
+  "type": "integer"
+}

addedOutput schema / properties / lead_watch

Added value: +{
+  "additionalProperties": {},
+  "propertyNames": {
+    "type": "string"
+  },
+  "type": "object"
+}

Changed1 schema field changedv1.2.2Sep 26, 2026
- addedOutput schema / properties / hive_notice
```
Added value: +{
+  "type": "string"
+}
```
First observedv1.0.0Sep 22, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare the safety profile (readOnlyHint/destructiveHint false, idempotentHint false); the description adds substantial behavior beyond that: delivery HOLDS past max_wait_seconds while the pane has a dialog or unsubmitted text, same-mode/same-target arming supersedes a pending watch and names it in 'superseded', only one standing watch per project is allowed with a second refused, and the lead watch ends with a named reason on pane death/reissue/restart.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded, and the length is partly justified by three modes and eight parameters. However, the entire definition is one dense run-on paragraph with no bullets, headings, or separators, which makes the many branching rules hard to parse and re-read.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be spelled out, and the description still covers delivery targets, roster/receipt contents, supersession, expiry behavior, and per-shape defaults. Nothing an agent needs to invoke the tool correctly appears to be missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 88%, so the baseline is 3, but the description adds real meaning beyond the schema: mode=any fires on the first fresh idle transition while mode=all fires when every watched agent is idle (returning already_satisfied), and max_wait_seconds means different things per shape (900 default for agents, 14400 lifetime for scope). This is more than the schema alone conveys.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening clause gives a specific verb and trigger ('Wake up when watched agents go idle ... or max_wait_seconds passes'), and the body then separates the tool into three named shapes (agents one-shot, scope='project' standing watch, lead_project_id queen watch). This lets an agent distinguish it from siblings like wake_set, wake_get, wake_update, and wake_cancel without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to pick each shape ('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'), names the alternative it replaces ('Use either instead of polling'), and lists exclusions ('agents=[...] refuses a lead', 'lead_project_id is the QUEEN's alone').

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.