[DOCS] SendMessage docs omit relayed permission authority and auto mode blocking behavior

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/tools-reference

Section/Topic

SendMessage cross-session messaging and relayed permission requests

Current Documentation

The tools reference currently says:

"SendMessage sends a message to an agent team teammate, or resumes a subagent by its agent ID."

The subagents page explains that SendMessage can resume stopped subagents, and the Agent SDK TypeScript reference defines a peer message origin:

"Message from another agent session via SendMessage."

The agent teams page says teammate permission requests can bubble up to the lead, but it does not explain how relayed requests differ from human-originated authority.

What's Wrong or Missing?

Claude Code v2.1.166 hardened cross-session messaging so messages relayed via SendMessage from other Claude sessions no longer carry user authority:

• Receivers refuse relayed permission requests.
• Auto mode blocks relayed permission requests.
• The security distinction is about message origin and authority, not only about whether SendMessage can deliver text or resume a subagent.

Current docs describe SendMessage routing and resume behavior, but not the authority boundary. Users building agent-team or SDK workflows may incorrectly assume that a peer session can relay a permission request as though the end user had directly made or approved it.

Suggested Improvement

Add a security note to the SendMessage row or a nearby SendMessage section:

Messages received via SendMessage are treated as peer-originated, not as direct user input. A peer session cannot relay user authority for permission requests. Receivers refuse relayed permission requests, and auto mode blocks them.

Add cross-references from:

• sub-agents resume section
• agent-teams permission-request guidance
• Agent SDK message origin / peer documentation

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/tools-reference | 38 | SendMessage row describes routing/resume only |
| https://code.claude.com/docs/en/sub-agents | 797-809 | Resume section explains SendMessage auto-resume but not authority boundaries |
| https://code.claude.com/docs/en/agent-teams | 248, 381 | Team tools and permission requests are discussed without relayed authority caveat |
| https://code.claude.com/docs/en/agent-sdk/typescript | 1237 | peer origin is defined without permission-authority implications |
| https://code.claude.com/docs/en/auto-mode-config | 9-17, 174-184 | Auto mode docs do not mention blocking relayed permission requests |

Total scope: 5 pages affected.

Version reference: Claude Code v2.1.166 release notes state that messages relayed via SendMessage from other Claude sessions no longer carry user authority, receivers refuse relayed permission requests, and auto mode blocks them.