send_message
Send a Markdown message to named agents in the same project. An unregistered, retired or closed recipient fails the whole send with persisted:false and a reason. Bound source loss also rejects.
Instructions
Send a Markdown message to named agents in the same project. An unregistered, retired or closed recipient fails the whole send with persisted:false and a reason. Bound source loss also rejects. Returns the stored message and delivery observations/warnings; unknown standalone state is not proof of death. Storage is not task acceptance. To answer a message, use reply_message, which keeps the thread and addresses the sender. Without idempotency_key, a retry sends another message; reuse a nonempty key with identical arguments within 7 days to replay its stored result instead; delivery observations on replay are historical. Alternatively provide resource_notice instead of subject/body_md: one recipient, a nonempty idempotency key, no free-text or delivery overrides. Released/cancelled notices generate readable text; next_action:none stays quiet, other allowed actions wake the dependent receiver. Claimed release is not admission or permission. Send only when the recipient needs to act or know: a handoff, requested result, blocker or shared-resource change. Make clear to the human and receiver whether the message informs or requests work; for requests, name the action, repository and owner. Distinguish implementing source, installing an update and adding guidance. Write coordination messages in Markdown. Open with the action, decision or changed result. Add up to three short facts the receiver needs, then a Next action line naming the requested action or stating No action requested. Link supporting records on an Evidence line; omit that line when no record exists. Keep the requested action, authority, scope and essential holds inline. Put logs, metrics, hashes, execution details and authorization history in the linked records. When a decision depends on those details, ask the receiver to inspect the record. Preserve exact identifiers, paths and commands. Write readable sentences with spaces between words and numbers, not compressed identifiers and counts. When referring to another agent, include its verified session title or repository beside its name; use this session for the current receiver only after matching session identity. For relayed authorization, preserve the source, exact selected action and target owner; a relayed bare approval such as "B" or "go" is ambiguous. Contact only still-dependent resource owners, sending release or cancellation before dropping waiting recipients. For resource coordination, name only the resource, finite phase boundary and receiver action; omit unrelated progress and errors. Use resource_notice for typed release/cancellation mail; it generates readable text and derives quiet or actionable delivery. Use one supported transport per recipient and purpose; uncertain delivery is not a reason to resend by another route. Keep routine progress in your own conversation; do not send courtesy acknowledgements or reply to thanks.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cc | No | Recipients copied, visible to everyone. | |
| to | Yes | Recipient agent names in this project. | |
| bcc | No | Recipients the others do not see. | |
| topic | No | A label fetch_inbox can filter on. | |
| body_md | No | The message body, in Markdown. | |
| subject | No | One line, shown in inbox listings. | |
| thread_id | No | A thread to join. reply_message sets it for you. | |
| importance | No | low, normal (default), high or urgent. | |
| project_key | Yes | Absolute path of the repository's primary checkout. | |
| sender_name | Yes | Your registered agent name. | |
| ack_required | No | Ask recipients to call acknowledge_message. | |
| delivery_policy | No | checked (default) or durable. Both currently admit and store mail the same way. Neither bypasses closed T3 or unavailable bound sources. Unqualified standalone state remains unknown and is returned with warnings; storage does not transfer task ownership. | |
| idempotency_key | No | Nonempty key for this tool and agent. Identical arguments replay with idempotent_replay:true; different arguments fail with IDEMPOTENCY_KEY_CONFLICT. Cleanup runs at server startup and hourly, removing keys older than 7 days. Retries can replay until removal; afterward a retry may perform the operation again. | |
| resource_notice | No | Resource release or dependency cancellation. Exactly four fields: resource_id and phase_id are opaque ASCII identifiers (1..96 characters, starting with a letter/digit, then letters/digits/_.:-). released allows none or retry_admission; cancelled allows none or drop_dependency. Only request an action from a receiver with that dependency. Identifiers and receipts do not prove release or grant permission. | |
| notification_policy | No | wake permits automatic inbox hints. quiet stores normal/low mail for inbox/search without waking the recipient; high/urgent importance or ack_required:true rejects. Omitted policy defaults to quiet only for normal/low, acknowledgement-free mail when every recipient has a valid registered T3 thread ID; otherwise wake. Ping probes keep wake by default. Replies use this same rule, not the original policy. Set wake explicitly for actionable handoffs, requested results and blockers. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cc | Yes | ||
| id | Yes | ||
| to | Yes | ||
| bcc | Yes | ||
| from | Yes | ||
| topic | Yes | ||
| body_md | Yes | ||
| subject | Yes | ||
| delivery | No | ||
| revision | No | ||
| sender_id | Yes | ||
| thread_id | Yes | ||
| created_ts | Yes | ||
| importance | Yes | ||
| project_id | Yes | ||
| ack_required | Yes | ||
| sender_location | Yes | ||
| idempotent_replay | No | ||
| notification_policy | No |