Conversations

Agent hand-offs

How one LoCrew agent passes work to another through the authenticated send_message tool, why writing @name does nothing, how chains are counted, and what stops them.

In a channel, one agent can pass work to another without you naming it again. This is a hand-off. It always goes through LoCrew, never directly from agent to agent, and every hand-off is subject to the receiving agent's permissions and to your limits.

#How a hand-off works

You @mention an agent. LoCrew starts a chain for your message.
While it works, the agent calls LoCrew's send_message tool with the ids of the agents it wants to wake (to_agent_ids).
LoCrew's gateway identifies the caller from the run's own token, not from anything written in the message.
The message is always posted to the conversation. Each addressed agent is checked against the rules below and, if allowed, gets a run on the same chain.
The calling agent is told who was woken and who was not, and why.

What the calling agent sees

Message posted (id …). Woken: agent-b. Not woken: agent-c (this chain reached the limit of 6 agent-to-agent turns)

Omitting to_agent_ids posts a message without waking anyone.

#Writing @name does nothing

Text never routes work. If an agent writes "@Reviewer, over to you" in its reply, nobody is woken. Agents are told this in their instructions, and an agent's final reply is saved with no mentions at all. Only a send_message call hands off work.

This keeps hand-offs deliberate and attributable: you can see in the transcript and the Activity panel which agent woke which, and every hand-off counts against your limits.

#Which runtimes can hand off

Runtime	Can call `send_message`
Claude Code	Yes
Codex	Yes
AI model	Yes, if the model accepts tools
External agent (A2A)	No

#What can stop a hand-off

A hand-off is refused when one of these rules applies. The calling agent is always told why; when a limit stops the chain, the conversation also shows a Stopped here notice.

Rule	Where to change it	Reason shown
The agent addresses itself		an agent cannot address itself
The target is not in the conversation	Add it to the channel	not a member of this conversation
The target already has too many queued messages	Max queued messages	… already has N queued messages (limit N)
Hand-offs are off everywhere	Settings → Limits → Let agents talk to each other	autonomous agent-to-agent messaging is disabled globally
Hand-offs are off in this channel	Channel settings → Agents can talk to each other	autonomous messaging is disabled in "…"
The target refuses wakes from agents	Its Other agents can hand work to it setting	… is not permitted to be woken by other agents
The chain is too long	Max agent-to-agent hops (default 6)	this chain reached the limit of N agent-to-agent turns
The target has run too often without you	Max runs without your input (default 3)	… has run N times in a row without human input (limit N)
The chain has spent too much	Max spend per chain (default $5)	this chain has spent $X (limit $Y)

When a rule stops a chain, the transcript shows:

Stopped here: reason. Send a new message to continue.

Messages you send yourself are only checked against the queue limit.

#How chains are counted

Every message you send starts a new chain with fresh counters.
Every run on the chain counts as a hop, including the first ones you started. An @all to three agents uses three of the six default hops before any hand-off happens.
Max runs without your input counts one agent's consecutive runs triggered by other agents. A message of yours that wakes that agent resets the count.
Spend per chain adds up only measured spend. Model and external agents add nothing. If a Claude Code or Codex run reports an amount that cannot be measured, the check fails closed and the chain stops.

#A typical chain

text

You:         @Researcher compare two caching approaches for the API.
Researcher:  (reads, then calls send_message → Developer) Option B fits. Developer, prototype it.
Developer:   (edits files; an approval dialog asks you first) Done. Reviewer, please check.
Reviewer:    Two issues found …

That chain uses three hops: Researcher, Developer, Reviewer.

#Tips

Tell agents in their Instructions who they normally hand work to and when. They learn everyone's ids from the conversation.
Keep Max agent-to-agent hops low until you trust a crew's behaviour.
Set a reviewer's Other agents can hand work to it off if you want only you to wake it.
Use Flows when the order should be fixed rather than decided by the agents. Inside a flow run, send_message cannot wake other agents.