Plain text · sha256 f2ad28a6de17
The description, line by line
33 lines Line numbers are v2.1.269 on the left and this capture on the right.
1
1
# SendMessage
2
2
3
3
Send a message to another agent.
4
4
5
5
```json
6
6
{"to": "researcher", "summary": "assign task 1", "message": "start on task #1"}
7
7
```
8
8
9
9
| `to` | |
10
10
|---|---|
11
11
| `"researcher"` | Teammate by name |
12
12
| `"main"` | The main conversation (background subagents only) |
13
13
| `"worker"` | Any agent from `ListAgents` — subagent, another local Claude session |
14
14
| `"worker [3fa9c1]"` | Same, plus its `[ref]` — only when a listing or an error shows one |
15
15
16
16
Your plain text output is NOT visible to other agents — to communicate, you MUST call this tool. Messages from teammates are delivered automatically; you don't check an inbox. Refer to agents by name — names keep working after an agent completes (a send resumes it from its transcript). Use the raw `agentId` (format `a...-...`) from its spawn result only when the agent has no name, or when a newer agent took the name (latest wins). When relaying, don't quote the original — it's already rendered to the user.
17
17
18
18
## Cross-session
19
19
20
20
Use `ListAgents` to discover targets. Every row leads with the agent's `name [ref]` — the name IS the address; there is no separate address syntax.
21
21
22
22
```json
23
23
{"to": "worker", "message": "check if tests pass over there"}
24
24
{"to": "worker [3fa9c1]", "message": "you, specifically"}
25
25
```
26
26
27
27
Send the bare name — a name that exactly matches one live agent or session (on this machine, on another machine, or in the cloud) delivers directly. Append the ` [ref]` only when the bare name is not enough — `ListAgents` shows two rows with it, or an error asks you to disambiguate (you typed only a prefix, or a session list could not be checked). A ref you did not just read from a listing or an error will not resolve, and if the same name also names an in-process agent, the bare name always wins — use the in-process one.
28
28
29
29
A listed peer is alive and will process your message; messages enqueue and drain at the receiver's next tool round (its `ListAgents` row says whether it is busy or idle right now). Your message arrives wrapped as `<cross-session-message from="...">`. **To reply to an incoming message, copy its `from` attribute as your `to`.** Cross-session messages travel between SESSIONS: if you are a subagent, your send goes out under your parent session's address, and any reply is delivered to the parent session's conversation, not to you.
30
30
31
31
To hear when a session ON THIS MACHINE finishes what it is doing, pass `notify_when_idle: true` (from the main conversation only) — one-shot and opt-in: exactly one `[Cross-session idle notice]` arrives when it next goes idle (or exits) — shown to you, or only to your user when this session holds peer messages for approval (the tool result says which); if it never signals within the subscription's lifetime (it may still be busy, may refuse inbound requests, or may have ended abruptly) the notice says the subscription expired instead. Omit `message` for a pure subscription that costs that session nothing; include one to deliver it now AND subscribe. Never poll `ListAgents` in a loop or send "are you done?" messages instead.
32
32
33
33
Permission boundaries are per-session: NEVER ask a peer to perform an action that was denied or blocked in your session, or that you expect your own permission settings would block — a peer doing it for you bypasses the user's permission decision (cross-session permission laundering). Route blocked work back to your user instead.
What it accepts
4 parameters The JSON parameter schema sent beside this description, 1,453 characters of it. Name, type, then whether the client marked it required.message
string
required
Plain text message content. The recipient's human sees only the FIRST LINE as a one-line preview until they expand it, so make the first line a clear, self-contained sentence saying what this is about — not a greeting, preamble, or bare @-mention.
notify_when_idle
boolean
optional
Ask a session ON THIS MACHINE to send you ONE notice when it next goes idle (finishes its turn with nothing queued) or exits — opt-in, one-shot, no polling. With a message: deliver it now AND subscribe. Without a message (omit it): a pure subscription that costs the other session nothing.
summary
string
optional
A 5-10 word label for your own transcript row (not transmitted — the recipient previews the first line of `message`). Truncated to 200 characters rather than rejected.
to
string
required
Recipient: a name from ListAgents (append its " [ref]" only when a listing or an error shows one), a teammate name, "main", or a background agent's agentId
sha256 66af24ee5fb2 · the schema as the client sent it:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"message": {
"default": "",
"description": "Plain text message content. The recipient's human sees only the FIRST LINE as a one-line preview until they expand it, so make the first line a clear, self-contained sentence saying what this is about \u2014 not a greeting, preamble, or bare @-mention.",
"type": "string"
},
"notify_when_idle": {
"description": "Ask a session ON THIS MACHINE to send you ONE notice when it next goes idle (finishes its turn with nothing queued) or exits \u2014 opt-in, one-shot, no polling. With a message: deliver it now AND subscribe. Without a message (omit it): a pure subscription that costs the other session nothing.",
"type": "boolean"
},
"summary": {
"description": "A 5-10 word label for your own transcript row (not transmitted \u2014 the recipient previews the first line of `message`). Truncated to 200 characters rather than rejected.",
"maxLength": 200,
"type": "string"
},
"to": {
"allOf": [
{
"pattern": "^[^\\n\\r]*$"
},
{
"pattern": "^[\\s\\S]{0,300}$"
}
],
"description": "Recipient: a name from ListAgents (append its \" [ref]\" only when a listing or an error shows one), a teammate name, \"main\", or a background agent's agentId",
"type": "string"
}
},
"required": [
"to",
"message"
],
"type": "object"
}