From 4986ac5b36aab1c898451f0370369f2fd957b2f9 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Thu, 7 May 2026 17:38:01 +0000
Subject: [PATCH] docs: explicit destination addressing and per-destination
 threading

Generated-By: mintlify-agent
---
 api/message-routing.mdx | 20 ++++++++++++++++++++
 features/messaging.mdx  | 36 +++++++++++++++++++++++++++++++++++-
 2 files changed, 55 insertions(+), 1 deletion(-)

diff --git a/api/message-routing.mdx b/api/message-routing.mdx
index 4578590..89310cf 100644
--- a/api/message-routing.mdx
+++ b/api/message-routing.mdx
@@ -69,6 +69,26 @@ The router accepts optional pluggable hooks:
 
 All hooks are optional. Without the permissions module, the system is allow-all.
 
+## Outbound dispatch (in-container)
+
+Before delivery, the agent runner parses the agent's final text and dispatches each `<message to="name">...</message>` block to the named destination.
+
+- Bare text outside `<message>` blocks is **scratchpad** — logged but never sent.
+- `<internal>...</internal>` makes scratchpad intent explicit and is stripped before logging.
+- Wrapping is **required**, even with a single configured destination. There is no fallback that sends bare text to the originating channel.
+
+### Per-destination thread resolution
+
+For each dispatched block, `thread_id` and `in_reply_to` are resolved per destination by querying the most recent inbound message that matches the destination's `channel_type` and `platform_id`:
+
+```sql
+SELECT thread_id, id FROM messages_in
+WHERE channel_type = ? AND platform_id = ?
+ORDER BY seq DESC LIMIT 1
+```
+
+This matters in `agent-shared` sessions, where one session serves multiple messaging groups with distinct thread contexts. If the lookup misses, the runner falls back to the session's inbound routing context.
+
 ## Outbound delivery
 
 ### Delivery polls
diff --git a/features/messaging.mdx b/features/messaging.mdx
index 57cd2b4..0917979 100644
--- a/features/messaging.mdx
+++ b/features/messaging.mdx
@@ -85,7 +85,41 @@ Per-wiring `sender_scope` controls who can trigger the agent:
 
 ## Message formatting
 
-Messages are formatted for the agent with sender information, timestamps, and metadata. The agent-runner inside the container handles formatting for the configured provider.
+Each inbound message is wrapped in an XML element so the agent can see who sent it, when, and from which destination. The `from` attribute carries the destination name resolved from the message's channel and platform ID — the agent uses it to address responses correctly.
+
+| Kind | Format |
+|------|--------|
+| `chat` | `<message id="..." from="..." sender="..." time="..." reply_to="...">...</message>` |
+| `task` | `<task from="..." time="...">Instructions: ...</task>` |
+| `webhook` | `<webhook from="..." source="..." event="...">{...payload...}</webhook>` |
+| `system` | `<system_response from="..." action="..." status="...">{...result...}</system_response>` |
+
+If routing fields can't be matched to a known destination, `from` falls back to `unknown:<channel_type>:<platform_id>` so nothing is silently dropped.
+
+## Response wrapping
+
+The agent **must wrap every response** in a `<message to="name">...</message>` block — this is required even when only one destination is configured. The destinations and required syntax are injected into the system prompt at wake time:
+
+```
+## Sending messages
+
+You can send messages to the following destinations:
+
+- `discord-test`
+- `slack-test`
+
+**Every response must be wrapped** in a `<message to="name">...</message>` block.
+```
+
+Multiple `<message>` blocks can be included in a single response to fan out to several destinations. Text outside of `<message>` blocks is treated as **scratchpad** — logged but not sent. Use `<internal>...</internal>` to make scratchpad intent explicit.
+
+### Per-destination thread resolution
+
+In `agent-shared` sessions where one agent serves multiple messaging groups, each destination may have a different thread context. When dispatching a `<message to="name">` block, the agent runner resolves `thread_id` and `in_reply_to` from the most recent inbound message matching that destination's channel and platform — never from a single global routing context. This prevents one channel's thread from being stamped onto another.
+
+### Compaction safety
+
+Claude Code's PreCompact hook (`bun /app/src/compact-instructions.ts`) emits custom instructions during context compaction so the summary preserves the routing XML structure (`<message from="...">`, `<task from="...">`, `<webhook from="...">`) and the chronological exchange order. The agent must keep seeing which destination sent each message — otherwise it can't address replies correctly after a compaction. The hook is added automatically to every agent group's `settings.json` on init, and back-filled on existing groups.
 
 ## Channel-aware formatting