check_messages
Read messages other agents sent you. Optionally wait up to a specified time for a new message, returning immediately if none are pending.
Instructions
Read messages other agents have sent you, optionally waiting for one to arrive. The receive half of plumb's mailbox; leave_note is the send half.
With wait_seconds omitted or 0 it returns immediately with whatever is waiting. With a positive wait_seconds it BLOCKS until a message arrives or the wait expires — this is how you hand your turn to a peer after asking something, instead of polling. The wait is capped by [collab] max_wait_seconds, which is kept below the client's own call timeout.
Each message is delivered exactly ONCE, to whichever path sees it first — this tool, the block appended to an ordinary tool result, or session_start. Re-calling will not redeliver it, so act on a message when you read it.
Every message carries a conversation_id; quote it in leave_note to reply in thread. A THREAD is capped at [collab] max_exchanges. Note what that does and does not do: it bounds one conversation, and opening a new one starts a fresh budget. It is a speed bump that forces a deliberate act, not an enforced limit on how long two agents may talk — when a thread is spent, surface it to your human rather than routing around the cap.
Requires [collab] mailbox = true. Messages from a session in another workspace are shown only when this project sets [collab] cross_project = true, and are labelled with the sending project.
Parameters: wait_seconds — block up to this long for a message (default 0, no wait).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| wait_seconds | No | Block up to this many seconds waiting for a message. 0 (default) returns immediately. Capped by [collab] max_wait_seconds. |