docs(sendmessage): clarify name registry semantics for completed agents
Summary
The SendMessage tool's documentation states "Refer to teammates by name, never by UUID." This guidance is accurate for concurrent multi-agent coordination, but it does not cover the resume-after-completion pattern, where the name registry has already deregistered the agent.
Observed behavior
After a background sub-agent completes, attempting SendMessage to: "<agent-name>" returns:
{"success":false,"message":"No agent named '<name>' is currently addressable. Spawn a new one or use the agent ID."}
Retrying with the agent's UUID (e.g., SendMessage to: "<agentId from the Agent tool's spawn response>") succeeds and resumes the prior session with full context intact.
Observed deterministically across 20+ post-completion SendMessage attempts in a single session (5 background agents x 4 multi-round resume cycles, every single name-based call failed, every single UUID-based call succeeded).
Expected vs actual
- Docs say: refer to teammates by name
- Actual: name is only valid while the agent is active. Post-completion, only UUID resolves.
Proposed improvements (either or both)
- Documentation: extend the
SendMessagetool description to note that name-based addressing applies only to currently-active agents, and that UUID (agentIdfrom the Agent tool's spawn response) is required to resume completed agents. - Behavior: keep the name registry valid for a configurable grace period after agent completion, so the same identifier works for both active coordination and resume patterns.
Repro
- Spawn a background agent:
Agent(... name="worker-1", run_in_background=true) - Wait for completion notification
- Try
SendMessage to: "worker-1"-> fails with the message above - Try
SendMessage to: "<agentId from spawn response>"-> succeeds, resumes session with prior context
This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗