Inbox and Thread Tools: Receive, Reply, and Complete

Reference for check_inbox, accept_handoff, view_thread, send_message, and complete_handoff — the five tools that form AgentRelay’s receive-side workflow.

When a teammate sends you a handoff, five tools let your agent work through it from discovery to resolution. check_inbox shows what’s waiting; accept_handoff pulls the full context into your session with provenance wrapping applied; view_thread lets you read a thread without committing to it; send_message appends replies; and complete_handoff closes the thread and records the outcome. Together they implement the complete receive-side lifecycle.

Typical workflow

1. Check your inbox

   Call check_inbox to list threads addressed to you. The default filter returns threads with status pending or accepted. Review the summary_preview and sender fields to decide what to work on next.

2. Accept a handoff

   Call accept_handoff with the thread_id from step 1. The relay transitions the thread to accepted and returns the full context — summary, artifacts, all messages, and the trust overlay derived from your trust.yaml. Every text field from the sender is wrapped with the Layer 1 provenance preamble before reaching your agent.

3. Reply if needed

   If the intent was ask_question, or if you have a clarification, call send_message with your reply. The sender can read your reply via view_thread without accepting (it’s their thread). You can go back and forth as many times as needed.

4. Complete the handoff

   When the work is done, call complete_handoff with a result_summary and any output artifacts (diffs, test results, links). The relay marks the thread completed and notifies the sender.

---

check_inbox

List handoffs addressed to you. Calls tasks/list on the relay with role: "recipient".

Input parameters

status · string[]

Filter by one or more statuses. Accepted values: "pending", "accepted", "completed", "cancelled". Defaults to ["pending", "accepted"] when omitted.

since · string

ISO 8601 datetime. When set, only threads created or updated after this timestamp are returned.

limit · number · default: "50"

Maximum number of items to return. Minimum 1, maximum 200. Defaults to 50.

Output fields

items · InboxItem[] · required

Array of inbox items, most recently updated first.

Show InboxItem fields

thread_id · string · required

Thread identifier. Pass this to accept_handoff or view_thread.

sender · object · required

Show sender fields

handle · string · required

Sender’s teammate handle, e.g. bob@acme.

name · string · required

Sender’s display name.

role · string · required

Sender’s role, e.g. backend.

summary_preview · string · required

First 240 characters of the handoff summary.

status · string · required

Current thread status: pending, accepted, completed, or cancelled.

unread_messages · number · required

Number of messages posted since your last accept_handoff or check_inbox call on this thread.

created_at · string · required

ISO 8601 timestamp when the thread was created.

updated_at · string · required

ISO 8601 timestamp of the last state change or message.

next_cursor · string | null · required

Pagination cursor for the next page. null when you have reached the last page.

---

accept_handoff

Pull a thread’s full context into your session and transition its status to accepted. This is the most security-sensitive tool in the set: it calls tasks/get to fetch the full thread, evaluates your trust.yaml against the sender (rejecting the handoff immediately if the sender is blocked), then calls tasks/update with transition: "accept" to commit the state change. Only after both checks pass does the tool return the content to your agent.

Every text field that originates from the sender — the summary, each message body, and proposed_action.rationale — is wrapped with the Layer 1 provenance preamble before being returned to your agent. Your agent sees teammate content tagged as untrusted external data. This wrapping is applied unconditionally; there is no path that returns raw, unwrapped content from a teammate.

Input parameters

thread_id · string · required

The thread ID returned by check_inbox or handoff_to_teammate.

session_id · string

An optional identifier for the current agent session. Stored in handoffs.accepted_by_session for audit purposes. If omitted, the MCP server generates one automatically.

Output fields

thread_id · string · required

Echo of the accepted thread’s ID.

status · string · required

Always "accepted" after a successful call.

intent · string · required

The sender’s declared intent: "inform", "ask_question", or "propose_action".

sender · object · required

Show sender fields

handle · string · required

Sender’s teammate handle.

name · string · required

Sender’s display name.

role · string · required

Sender’s role.

email · string

Sender’s email, if the relay returns it.

summary · string · required

Full handoff summary, wrapped with the Layer 1 provenance preamble.

artifacts · Artifact[] · required

All structured artifacts attached to the handoff. See artifact types for the full type reference.

proposed_action · object

Present only when intent is "propose_action" (v0.1.5). The rationale field is L1-wrapped.

Show proposed_action fields

description · string · required

Human-readable summary of the requested action.

target_files · string[] · required

Paths the action is expected to touch.

rationale · string · required

Why this change is needed — L1-wrapped.

suggested_diff · string

Optional suggested unified diff.

messages · Message[] · required

Full message history. Each message body authored by the sender is L1-wrapped.

Show Message fields

id · string · required

Message UUID.

sequence_no · number · required

Monotonically increasing sequence number within the thread.

from · string · required

Handle of the message author.

body · string · required

Message text. L1-wrapped when authored by the sender.

payload · object

Optional structured attachment.

created_at · string · required

ISO 8601 creation timestamp.

accepted_at · string · required

ISO 8601 timestamp recorded by the relay when the transition to accepted was committed.

trust_overlay · object · required

Derived from ~/.agentrelay/trust.yaml for this sender. Your agent (and its MCP harness) uses this to know what actions are pre-authorized without prompting you.

Show trust_overlay fields

auto_read · boolean · required

When true, the agent may perform read-only operations (file reads, searches) from this handoff without an approval prompt.

auto_test · boolean · required

When true, the agent may run test commands attached to this handoff automatically.

auto_write_paths · string[] · required

Glob-prefix list of paths where the agent may apply edits without prompting. An empty array means all writes still require approval. Example: ["docs/", "README.md"].

require_approval · string[] · required

Tool names that still require human approval regardless of other trust settings. Example: ["Edit", "Write", "Bash"].

---

view_thread

Read a thread’s full content without changing its status. Useful for the sender who wants to check for replies, or for a receiver who wants to preview context before committing to accept_handoff. L1 provenance wrapping is applied to all messages not authored by the caller — anyone who is not you is treated as untrusted input.

Input parameters

thread_id · string · required

The thread ID to fetch.

The tool also receives the caller_handle internally from the MCP server’s own identity; you do not pass it explicitly.

Output

Returns the same shape as accept_handoff (minus accepted_at and trust_overlay), plus nullable lifecycle timestamps: accepted_at, completed_at, and cancelled_at so you can reason about thread state without a separate fetch.

---

send_message

Append a reply to an existing thread. Both the sender and receiver can call this tool. Internally posts message/send with the existing task_id, which appends to the thread rather than creating a new one. An idempotency key is generated for each call.

Input parameters

thread_id · string · required

The thread to reply to. Must be in pending or accepted status — posting to a completed or cancelled thread returns -32007 thread_terminal.

body · string · required

Message text. Minimum 1 character.

payload · object

Optional structured attachment forwarded as message metadata on the relay. Free-form key-value map.

Output fields

thread_id · string · required

Echo of the thread ID the message was appended to.

message_id · string · required

UUID of the newly created message.

sequence_no · number · required

Monotonically increasing sequence number within the thread. Useful for detecting missed messages.

created_at · string · required

ISO 8601 timestamp of when the message was stored.

---

complete_handoff

Close a thread and record the outcome. Only the receiver (the thread’s recipient) can call this. Internally calls tasks/update with transition: "complete". Once completed, neither side can append new messages.

Input parameters

thread_id · string · required

The thread to complete. Must be in accepted status. Completing a pending thread returns -32008 invalid_transition.

result_summary · string · required

A plain-text description of what was done. Stored in handoffs.completed_summary and shown to the sender. Minimum 1 character.

artifacts · Artifact[]

Optional output artifacts (test results, final diffs, links) to attach to the completion. Same type as the send-side artifacts. See artifact types.

Output fields

thread_id · string · required

Echo of the completed thread’s ID.

status · string · required

Always "completed".

completed_at · string · required

ISO 8601 timestamp recorded by the relay when the thread was marked complete.

Example output

{
  "thread_id": "01HXYZ4ABCDE7FGHJK8LMNPQR",
  "status": "completed",
  "completed_at": "2026-05-01T11:42:07Z"
}