4.3 KiB
SendMessageTool
Send messages to agent teammates and handle protocol requests/responses in a team.
Schema
Every call has three fields:
- to: The recipient address (string, required)
- message: The message content — either a plain string or a structured protocol object (required)
- summary: A 5-10 word preview shown in the UI
Addressing (to)
There is one team per session. Addressing is by member name:
| Address | Meaning |
|---|---|
"researcher" |
Direct message to the teammate named "researcher" |
"*" |
Broadcast to all teammates (except yourself) |
Structured protocol messages (shutdown, plan approval) cannot be broadcast — they require a specific recipient name.
Plain Text Messages
Send a message to a single specific teammate:
{
"to": "researcher",
"message": "Start working on task #1",
"summary": "Assign task #1 to researcher"
}
IMPORTANT for teammates: Your plain text output is NOT visible to the team lead or other teammates. To communicate with anyone on your team, you MUST use this tool. Just typing a response or acknowledgment in text is not enough.
Broadcast to All Teammates (USE SPARINGLY)
Send the same message to everyone on the team at once:
{
"to": "*",
"message": "Critical blocking issue found — stop all work",
"summary": "Critical blocking issue found"
}
WARNING: Broadcasting is expensive. Each broadcast sends a separate message to every teammate. Costs scale linearly with team size.
CRITICAL: Use broadcast only when absolutely necessary. Valid use cases:
- Critical issues requiring immediate team-wide attention
- Major announcements that genuinely affect every teammate equally
Default to direct messages. Use a specific to name for responding to one teammate, normal back-and-forth, or anything that doesn't require everyone's attention.
Structured Protocol Messages
Shutdown Request
Ask a teammate to gracefully shut down:
{
"to": "researcher",
"message": {
"type": "shutdown_request",
"reason": "Task complete, wrapping up the session"
}
}
The teammate will receive a shutdown request and can either approve (exit) or reject (continue working).
Shutdown Response
When you receive a shutdown request as a JSON message with type: "shutdown_request", you MUST respond to approve or reject it. Do NOT just acknowledge in text — call this tool.
Approve:
{
"to": "team-lead",
"message": {
"type": "shutdown_response",
"request_id": "abc-123",
"approve": true
}
}
Extract requestId from the incoming JSON and pass it as request_id. This sends confirmation to the leader and terminates your process.
Reject:
{
"to": "team-lead",
"message": {
"type": "shutdown_response",
"request_id": "abc-123",
"approve": false,
"reason": "Still working on task #3, need 5 more minutes"
}
}
Plan Approval Response
When a teammate with plan_mode_required calls ExitPlanMode, they send you a plan approval request as a JSON message with type: "plan_approval_request".
Approve:
{
"to": "researcher",
"message": {
"type": "plan_approval_response",
"request_id": "abc-123",
"approve": true
}
}
After approval, the teammate will automatically exit plan mode and can proceed with implementation.
Reject:
{
"to": "researcher",
"message": {
"type": "plan_approval_response",
"request_id": "abc-123",
"approve": false,
"feedback": "Please add error handling for the API calls"
}
}
The teammate will receive the rejection with your feedback and can revise their plan.
Important Notes
- Messages from teammates are automatically delivered to you. You do NOT need to manually check your inbox.
- When reporting on teammate messages, you do NOT need to quote the original message — it's already rendered to the user.
- IMPORTANT: Always refer to teammates by their NAME (e.g., "team-lead", "researcher"), never by UUID.
- Do NOT send structured JSON status messages. Use TaskUpdate to mark tasks completed and the system will automatically send idle notifications when you stop.