# Message Format Reference > How each message type is formatted across verbosity levels and platforms. --- ## 1. Visibility Matrix Which message types are shown at each verbosity level: | Message Type | Low | Medium | High | |------------------|--------|--------|--------| | `text` | Show | Show | Show | | `thought` | Hidden | Show | Show | | `tool_call` | Show* | Show | Show | | `tool_update` | Show* | Show | Show | | `plan` | Show | Show | Show | | `usage` | Hidden | Show | Show | | `error` | Show | Show | Show | | `attachment` | Show | Show | Show | | `system_message` | Show | Show | Show | | `session_end` | Show | Show | Show | | `mode_change` | Show | Show | Show | | `config_update` | Show | Show | Show | | `model_update` | Show | Show | Show | | `user_replay` | Show | Show | Show | | `resource` | Show | Show | Show | | `resource_link` | Show | Show | Show | \* `tool_call` has noise filtering: `ls` is hidden (except high), directory reads are hidden (except high), `glob` is collapsed on low. --- ## 2. ToolCall Formatting ### 2.1 Tool-Specific Formats (formatToolSummary โ medium/high) | Tool | Format | Example | |--------------|-----------------------------------------------|----------------------------------------------| | `read` | `๐ Read {filePath}{(N lines)}` | `๐ Read src/main.ts (50 lines)` | | `edit` | `โ๏ธ Edit {filePath}` | `โ๏ธ Edit src/main.ts` | | `write` | `๐ Write {filePath}` | `๐ Write src/new-file.ts` | | `bash` | `โถ๏ธ Run: {command}` | `โถ๏ธ Run: pnpm test` | | `grep` | `๐ Grep "{pattern}" in {path}` | `๐ Grep "TODO" in src/` | | `glob` | `๐ Glob {pattern}` | `๐ Glob **/*.test.ts` | | `agent` | `๐ง Agent: {description}` | `๐ง Agent: Find message formatting code` | | `webfetch` | `๐ Fetch {url}` | `๐ Fetch https://example.com/api` | | `websearch` | `๐ Search "{query}"` | `๐ Search "vitest mock guide"` | | _(default)_ | `๐ง {name}` | `๐ง CustomTool` | > `command` truncated at 60 chars. `description`, `url`, `query` also truncated at 60 chars. ### 2.2 Tool-Specific Formats (formatToolTitle โ low) | Tool | Format | Example | |--------------|---------------------------------|--------------------------------| | `read` | `{filePath}` | `src/main.ts` | | `edit` | `{filePath}` | `src/main.ts` | | `write` | `{filePath}` | `src/new-file.ts` | | `bash` | `{command}` | `pnpm test` | | `grep` | `"{pattern}" in {path}` | `"TODO" in src/` | | `glob` | `{pattern}` | `**/*.test.ts` | | `agent` | `{description}` | `Find message formatting code` | | `webfetch` | `{url}` | `https://example.com/api` | | `websearch` | `{query}` | `vitest mock guide` | | _(default)_ | `{name}` | `CustomTool` | ### 2.3 Icon Resolution (resolveToolIcon) Priority: `status` icon > `displayKind`/`kind` icon > `๐ง` default. **Status Icons:** | Status | Icon | |---------------|------| | `pending` | โณ | | `in_progress` | ๐ | | `completed` | โ | | `failed` | โ | | `cancelled` | ๐ซ | | `running` | ๐ | | `done` | โ | | `error` | โ | **Kind Icons:** | Kind | Icon | |------------|------| | `read` | ๐ | | `edit` | โ๏ธ | | `write` | โ๏ธ | | `delete` | ๐๏ธ | | `execute` | โถ๏ธ | | `command` | โถ๏ธ | | `bash` | โถ๏ธ | | `search` | ๐ | | `web` | ๐ | | `fetch` | ๐ | | `agent` | ๐ง | | `think` | ๐ง | | `install` | ๐ฆ | | `move` | ๐ฆ | | `other` | ๐ ๏ธ | ### 2.4 Noise Filtering | Rule | Action | Effect | |--------------------------------|------------|------------------------------------| | Tool name is `ls` | `hide` | Hidden on low/medium | | Read on directory (path ends `/`) | `hide` | Hidden on low/medium | | Tool name is `glob` | `hide` | Hidden on low/medium | | Tool name is `grep` | `hide` | Hidden on low/medium | --- ## 3. Plan Formatting **Source data:** ```typescript { type: "plan", entries: PlanEntry[] } // PlanEntry = { content: string; status: "pending" | "in_progress" | "completed"; priority } ``` > **Note:** Plan is now rendered inline within the **Consolidated Tool Card** (see Section 9), positioned between completed and running tools. It is no longer a standalone message. ### Per verbosity: | Verbosity | Output | |-----------|--------------------------------------------| | **Low** | Full list with status icons | | **Medium**| Full list with status icons | | **High** | Full list with status icons | > Regardless of verbosity, plan always shows all entries in full (no summary collapse). **Example:** ``` ๐ Plan โ 1. Set up project structure โ 2. Create database schema ๐ 3. Implement API endpoints โฌ 4. Write tests โฌ 5. Deploy to staging ``` **Plan status icons:** | Status | Base/Discord | Telegram | |---------------|-------------|----------| | `completed` | โ | โ | | `in_progress` | ๐ | ๐ | | `pending` | โฌ | โฌ | > Note: `PlanEntry.priority` exists in the type but is **not rendered** anywhere. --- ## 4. Usage Formatting **Source data:** ```typescript { type: "usage", metadata: { tokensUsed, contextSize, cost } } ``` | Verbosity | Output | |-----------|---------------------------------------------------------| | **Low** | Hidden | | **Medium**| `๐ 12.5K tokens ยท $0.05` | | **High** | `๐ 12.5K / 200K tokens` + progress bar + `๐ฐ $0.05` | **High verbosity example:** ``` ๐ 12,500 / 200,000 tokens โโโโโโโโโโโโโโโโโโโโ 6% ๐ฐ $0.05 ``` > Shows โ ๏ธ instead of ๐ when usage >= 85% (Discord/Telegram). --- ## 5. Other Message Types | Type | Format | |------------------|-------------------------------------------------| | `text` | Raw text (plain/markdown/html per platform) | | `thought` | Hidden on low. Shown on medium/high. | | `error` | `โ Error: {text}` | | `system_message` | Raw text | | `session_end` | `Done ({reason})` | | `mode_change` | `๐ Mode: {modeId}` | | `config_update` | `โ๏ธ Config updated` | | `model_update` | `๐ค Model: {modelId}` | | `resource` | `๐ Resource: {name} ({uri})` | | `resource_link` | `๐ {name}: {uri}` | | `notification` | `{emoji} {sessionName}\n{summary}` | **Notification emojis:** | Type | Icon | |-------------------|------| | `completed` | โ | | `error` | โ | | `permission` | ๐ | | `input_required` | ๐ฌ | | `budget_warning` | โ ๏ธ | | _(default)_ | โน๏ธ | --- ## 6. Platform-Specific Differences ### 6.1 Discord (Markdown) ``` {icon} **{label}** [View filename](file_url) [View diff โ filename](diff_url) // High only: **Input:** ```json {rawInput} ``` **Output:** ``` {content} ``` ``` - Max content: 500 chars (input/output in high mode) - Max message: 1800 chars per chunk (splitMessage) - Viewer links always shown ### 6.2 Telegram (HTML) ```html {icon} {escaped_label} ๐ View filename ๐ View diff โ filename Input:
{escaped_input}
Output:
{escaped_content}
```
- Max content: 3800 chars (input/output in high mode)
- Max message: 3800 chars per chunk (splitMessage)
- HTML escaping applied (`&`, `<`, `>`)
- Markdown-to-HTML conversion for links, bold, italic, code
### 6.3 Slack (Block Kit)
| Type | Block Type | Format |
|---------------|------------|-----------------------------------------------|
| `text` | `section` | mrkdwn text (markdown converted) |
| `thought` | `context` | `๐ญ _{text}_` (500 char limit) |
| `tool_call` | `context` | `` ๐ง `{name}` `` + input JSON code block |
| `tool_update` | `context` | `{icon} \`{name}\` โ {status}` |
| `plan` | `divider` + `section` | `๐ *Plan*\n{text}` |
| `usage` | `context` | `๐ in: X ยท out: Y ยท $Z` |
| `error` | `section` | `โ ๏ธ *Error:* {text}` |
| `session_end` | `divider` + `context` | `โ
Session ended โ {reason}` |
> **Known issue:** Slack Plan uses `message.text` (empty string) instead of `metadata.entries`. Plan content will be blank.
---
## 7. Data Flow
```
AgentEvent (ACP subprocess)
โ
MessageTransformer.transform() โ OutgoingMessage { type, text, metadata }
โ
ToolCardState (consolidation buffer) โ buffers tool_call + tool_update events
โ
ToolCardRenderer.render() โ single consolidated embed per prompt turn
โ
MessagingAdapter.sendMessage()
โ
shouldDisplay(content, verbosity) โ noise filter + HIDDEN_ON_LOW check
โ
dispatchMessage(content, verbosity) โ switch(content.type)
โ
handleXxx() โ platform-specific handler
โ
renderer.renderXxx() / formatXxx() โ RenderedMessage { body, format }
โ
Platform send (Telegram HTML, Discord MD, Slack Blocks)
```
> **Consolidated Tool Card**: Single auto-updating embed/message per prompt turn replaces per-tool messages + standalone PlanCard. Card becomes immutable on `session_end`.
---
## 8. Files Reference
| File | Role |
|------|------|
| `src/core/types.ts` | AgentEvent, OutgoingMessage, PlanEntry types |
| `src/core/message-transformer.ts` | AgentEvent โ OutgoingMessage mapping |
| `src/core/adapter-primitives/format-types.ts` | Icons, ToolCallMeta, ViewerLinks types |
| `src/core/adapter-primitives/message-formatter.ts` | formatToolSummary, formatToolTitle, resolveToolIcon, evaluateNoise |
| `src/core/adapter-primitives/format-utils.ts` | progressBar, formatTokens, truncateContent, splitMessage |
| `src/core/adapter-primitives/messaging-adapter.ts` | Message dispatch, visibility, noise filtering |
| `src/core/adapter-primitives/rendering/renderer.ts` | BaseRenderer (plain text defaults) |
| `src/core/adapter-primitives/primitives/tool-card-state.ts` | ToolCard shared state, debounce logic (500ms + immediate first render) |
| `src/plugins/discord/formatting.ts` | Discord markdown formatting |
| `src/plugins/telegram/formatting.ts` | Telegram HTML formatting |
| `src/plugins/slack/formatter.ts` | Slack Block Kit formatting |
---
## 9. Consolidated Tool Card
### Overview
The Consolidated Tool Card is a single auto-updating embed/message per prompt turn that replaces both:
- Per-tool messages (individual `tool_call`/`tool_update` messages)
- Standalone PlanCard (now rendered inline)
**Behavior:**
- One embed per session per prompt turn
- Auto-updates as tools run (debounced at 500ms; immediate first render)
- Becomes immutable on `session_end` event
- Renders sequentially: completed tools โ running tools โ plan โ usage footer
- Verbosity controls noise filtering: low/medium hide noise tools, high shows all
### Structure
**Header:**
```
๐ง Tools (3/5 completed)
```
**Completed Tools Section:**
```
โ
Read src/main.ts (50 lines)
โ
Grep "TODO" in src/
```
**Running Tools Section:**
```
๐ Edit src/main.ts
```
**Plan Section** (inline, always full entries):
```
๐ Plan
โ
1. Set up project structure
โ
2. Create database schema
๐ 3. Implement API endpoints
โฌ 4. Write tests
```
**Usage Footer:**
```
๐ 12.5K tokens ยท $0.05
```
### Noise Filtering
Same rules as Section 2.4 apply:
- `ls` tool: hidden on low/medium
- Directory reads: hidden on low/medium
- `glob` tool: hidden on low/medium
- `grep` tool: hidden on low/medium
On **high** verbosity, all tools show (no filtering).
### Update Strategy
- **Debounce:** 500ms between renders (batches rapid tool events)
- **First render:** Immediate (not debounced)
- **Immutability:** On `session_end`, card stops updating and becomes read-only
- **Card lifecycle:** Created on first `tool_call`, destroyed with session