claude-code - 💡(How to fix) Fix 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)

1. Documentation: extend the SendMessage tool description to note that name-based addressing applies only to currently-active agents, and that UUID (agentId from the Agent tool's spawn response) is required to resume completed agents.
2. 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

1. Spawn a background agent: Agent(... name="worker-1", run_in_background=true)
2. Wait for completion notification
3. Try SendMessage to: "worker-1" -> fails with the message above
4. Try SendMessage to: "<agentId from spawn response>" -> succeeds, resumes session with prior context