# 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