How to wait for an agent to finish without polling
Call the wait_for_agent MCP tool. It returns as soon as the agent reaches idle, blocked or done (or the statuses you pass), or after up to 50 seconds. It listens to status events, so it never polls the pane or reads output.
Why not poll?
An MCP client that wants to know when an agent is done tends to call get_agent_output over and over. Each read costs tokens, and in Herdr it makes the pane jump. PeerBand's connector streams status changes instead, and wait_for_agent uses them.
Using wait_for_agent
Ask your client "Tell the agent to run the tests, then wait until it's done and summarize the result." The client calls:
send_agent_message(agent_id="…", message="Run the tests")
wait_for_agent(agent_id="…", statuses=["idle", "blocked", "done"], timeout_seconds=50)
get_agent_output(agent_id="…")statusesdefaults to idle, blocked and done.timeout_secondsis capped at 50, below common MCP client timeouts. If the agent is still working, the client simply calls it again.- The result says whether the status matched, the current and previous status, and how long it waited.
Idle or done means the agent stopped. It doesn't prove the task succeeded, so read the output when it matters.
Clients with MCP Events
MCP clients that support MCP Events can subscribe to agent status changes and notes instead, and get pushed updates without holding a call open.
For people, not clients
If you're the one waiting, use a webhook instead: Slack or Discord tells you when an agent is done or blocked. See notifications for waiting agents.
Questions
Does wait_for_agent need message access?
No. It only needs agents:read, the same as get_agent_status.
What if my connector is old?
Status events need a connector that supports them. Run peerband update to get the latest CLI and Herdr plugin.