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

Status Fixed / completed

Maintainer reply ✓ Yes — bcherny

Activity 3 comments · opened Jun 6, 2026 · closed Aug 17, 2026

💡 Likely answer: A maintainer (bcherny, collaborator) responded on this thread — see the highlighted reply below.

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.

View original on GitHub ↗

3 Comments

coygeek · 3 months ago

Still relevant as of 2026-07-01. The agent-teams Permissions subsection now documents the v2.1.166 cross-session hardening (peer-originated messages do not carry user authority; receivers refuse relayed permission requests; auto mode treats relayed approval claims as untrusted input — see https://code.claude.com/docs/en/agent-teams#permissions). However, four of the five pages called out in the issue still omit the authority boundary: the SendMessage row at https://code.claude.com/docs/en/tools-reference describes only routing/resume, the Resume subagents section at https://code.claude.com/docs/en/sub-agents explains SendMessage auto-resume without authority context, the Agent SDK peer origin definition at https://code.claude.com/docs/en/agent-sdk/typescript covers routing shape but not permission-authority implications, and the auto-mode documentation at https://code.claude.com/docs/en/auto-mode-config does not mention that the classifier blocks relayed SendMessage permission requests. Adding a short security sentence on each of those pages plus a cross-reference to the agent-teams Permissions section would close the gap.

bcherny collaborator · 2 months ago

Thanks — this is now covered in the docs. The cross-session messaging page has a "How a session treats an incoming message" section stating that a message from another session never counts as your consent (it can't answer a pending permission prompt), can't change configuration, and that the receiving session's own permission prompts still fire; the agent teams page says the same for teammate messages and links across.

https://code.claude.com/docs/en/cross-session-messaging#how-a-session-treats-an-incoming-message and https://code.claude.com/docs/en/agent-teams

Closing as documented; reopen if a spot is still missing.

🤖 Generated with Claude Code

github-actions[bot] · 9 days ago

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.