Report whether the server and its database answer, with the database path. Call it when another tool fails with an INTERNAL error or no answer, to tell a down server from a bad request.

Create a project without registering an agent, returning id, slug, human_key and created_at. Repeating the same repository path returns the existing project. Other tools fail with NOT_FOUND until it exists; register_agent and macro_start_session create it themselves.

Register or update an agent identity in a project, creating the project if needed. Omit name to get a generated adjective+noun name, unless task_description starts with a session tag an eligible or lifecycle-bound agent already has; then that agent is updated. Re-registering an existing name replaces its program, model and task and clears inactivity retirement. Authoritative lifecycle closure requires a verified reopen. If the register hook already told you your name, pass it as name, or start task_description with the session tag it gave you. To also reserve paths and read your inbox in one call, use macro_start_session.

Ensure the project, register an agent, optionally reserve paths, and return {project, agent, file_reservations, inbox}. The inbox contains the latest metadata without marking mail read; use fetch_inbox for bodies and unread-mail draining. Reuse the hook's name as agent_name or its session tag in task_description to avoid a second identity. Conflicting paths appear under file_reservations.conflicts; other paths are granted. If already registered and only checking mail, use fetch_inbox instead.

Return one agent's profile: program, model, task description, T3 thread (t3_thread, null outside T3) and first and last activity times. An unknown name fails with NOT_FOUND, naming recently active agents. Profile metadata and activity do not prove the session or model is currently running. To see every agent in a project, use list_agents.

Return an array of non-retired agents in a project, most recently active first, with program, model, task and session details, including t3_thread for a T3 link. Use it to find who to message; whois returns one agent. active_within_days filters recent activity, not whether a session is running. Metadata and activity do not prove current session or model liveness. waiting_for_mail is true while a wake hook or bridge has a wait open on this server that began after the agent's last end report. false does not prove that no wait is open: a wait opened before the end report, or refused because its session ID names several registrations, shows false. session_ended_at is when the host's SessionEnd hook reported the end, or null if none is recorded or the agent has acted since. Neither proves a session is running or ended; confirm with the owning host before retiring another agent. limit caps this single result; there is no continuation cursor, so a full result may omit agents.

At an agreed whole-session closeout or a whole-session completion with nothing remaining, record the closeout, release owned resources and finish required dependency notices, then retire your own registration in every project you joined. Under T3 Code do not retire yourself: the server retires closed or idle threads where configured. Before retiring another agent, confirm with its owning host that its session has ended; roster data or a ping timeout is insufficient. Retire an agent whose session has ended, so it no longer appears in list_agents and new messages to it fail. Its messages stay. unretire_agent reverses it, and so does the agent registering again or sending, reading mail or reserving files as itself. Lookups such as whois and list_agents do not.

Bring a retired agent back into list_agents so it can receive messages again; earlier messages stay unchanged. Returns {agent_name, retired:false}. Calling on an already active agent also succeeds and refreshes its activity time, as every revival does. Registering, sending, reading mail or reserving files revives the caller automatically; use this to revive another agent. An unknown name fails with NOT_FOUND.

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. Use spaces between words and numbers. Under T3 Code, refer to another agent by its thread link, title, not its registered name; use the name only if the user asks, no thread id is known or T3 fails. Elsewhere 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.

Reply in a message's thread, returning the stored message with reply_to. message_id selects the original in this project. Omit to to address its sender; cc and bcc are added only when supplied. The original's topic and importance are inherited, with a 'Re:' subject; importance can be overridden. ack_required defaults to false; set it explicitly to request acknowledgement of this reply. For retries within 7 days, reuse a nonempty idempotency_key with identical arguments. To start a new thread, use send_message. 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. Use spaces between words and numbers. Under T3 Code, refer to another agent by its thread link, title, not its registered name; use the name only if the user asks, no thread id is known or T3 fails. Elsewhere 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.

Withdraw your message from recipients whose delivery has not been read, acknowledged or withdrawn. Returns message_id, revision and per-recipient withdrawn/already_withdrawn/too_late results. Omit recipients for all deliveries; an explicit subset must be nonempty and valid. Retains content and audit history. Previews and injected context cannot be recalled. Requires explicit server activation after all readers are qualified. A nonempty idempotency_key is required; identical retries replay even when execution is disabled or the sender closes.

Change only your message's low/normal/high/urgent priority. Requires current expected_revision from inbox, history or sender receipt and a nonempty idempotency_key. Returns message_id, revision, importance and changed. A stale revision fails before a matching-value no-op. Edits affect metadata only: no new inbox notice or repeated instruction, and priority does not grant authority. Requires explicit server activation; identical retries replay before activation, lifecycle or revision checks.

Return an array of your latest received message metadata, newest first; include_bodies adds body_md. At session start or after a mail notice, set unread_only:true, include_bodies:true and mark_read:true. Stop when fewer than limit messages return (default 20, capped at 1000); repeat only after a full page. For a metadata preview, set mark_read:false; include_bodies defaults to false and mark_read to true. Each entry's sender_t3_thread is the sender's T3 thread id (null outside T3). Filters combine, so omit optional filters when draining all unread mail. Use search_messages for project-wide text matching, or mark_message_read or acknowledge_message for one message.

Return one newest-first page across registrations matching your host/session tag or T3 thread. Use machine-derived host and session_id, with t3_thread when known; never guess from an agent name. Each receipt includes project_key and agent_name for replies and acknowledgements. Defaults: unread_only:true, mark_read:true, include_bodies:false, limit:20. To drain, include bodies; stop when fewer than limit messages return (default 20, capped at 1000), repeating only after a full page. With mark_read:false or unread_only:false, this is a bounded preview, not a drain. The CLI swarmail inbox --session discovers identity and drains without mailbox arguments. Session identity selects inboxes and is not authentication: whoever can reach the server can read any mailbox.

Mark one received message read without acknowledging it, returning message_id, read and read_at. A repeat keeps the first read time but refreshes your agent's activity time. fetch_inbox already marks what it returns unless mark_read:false. When the message has ack_required, use acknowledge_message instead. Fails with NOT_FOUND unless you are a recipient.

Acknowledge one received message and mark it read, returning message_id, acknowledged, acknowledged_at and read_at. Repeated calls preserve first read and acknowledgement timestamps but refresh your agent's activity time. Acknowledge ack_required mail after acting on it; if you cannot or will not act, reply with the reason. Acknowledging lets the sender see the acknowledgement in get_message_delivery_receipt and ack_overdue_only stops listing it. To mark read without acknowledging, use mark_message_read. Fails with NOT_FOUND unless you are a recipient.

Return a message's persisted_at and recipients with kind, read_at, acknowledged, acknowledged_at and admission. Admission observations are historical; null admission means no snapshot was recorded. Storage/read/acknowledgement do not establish task acceptance. Null timestamps mean that recipient has not read or acknowledged it yet; they are not delivery errors. Use it as the sender to check an ack_required message; recipients use fetch_inbox. message_id must exist in this project or the call fails with NOT_FOUND.

Search subjects and bodies across a project, returning {result, next_cursor?} without marking mail read. All query words must match; filters narrow those matches. Results rank by best match unless ranking:'recency'. Each excerpt has up to 512 Unicode code points and >>>matched text<<< markers; include_body_md adds full bodies. Keep query, filters and ranking unchanged when passing next_cursor as cursor; no next_cursor means the last page. Use fetch_inbox for your received unread mail, or summarize_thread for a thread's participants and recent messages.

Return {thread_id, summary:{participants, total_messages}, messages} for you to summarize; this tool does not generate prose or mark mail read. Find thread_id with search_messages or fetch_inbox. per_thread_limit selects the newest messages with full bodies, returned oldest first. It defaults to 50 and caps at 1000, with no continuation cursor; total_messages counts the entire thread, even when messages is truncated. Use search_messages for text matching and fetch_inbox to drain unread mail. No matching thread returns zero messages.

Reserve repository-relative paths or globs so other agents know what you are editing. Returns {granted, conflicts}; grants include reservation ids and expiry times, while conflicts name the requested path and its holders. Conflicts do not fail the call, and nothing blocks the edit itself; the optional git guard refuses commits touching another agent's exclusive reservation. Reserving a path you already hold updates it. Extend with renew_file_reservations and release with release_file_reservations when done.

Return every active exclusive reservation in a project as an array of {id, agent, path_pattern, reason, expires_ts}. Released and expired reservations are left out. The git guard on another machine calls it to refuse a commit or push that touches a path someone here reserved.

Extend your active reservations by extend_seconds past their current expiry; each call extends again. Omit paths and file_reservation_ids for all; empty filters impose no restriction, and two nonempty filters must both match. Returns {renewed, file_reservations} with old and new expiry times; no matches returns zero and an empty array. Expired reservations are not renewed; reserve them again with file_reservation_paths.

Release your active reservations when you finish work so other agents can reserve those paths. While work continues, use renew_file_reservations instead. Omit both filters to release all; supply paths or file_reservation_ids for a subset. Empty filters impose no restriction; two nonempty filters must both match. Returns how many were released; zero is not an error.