merge: resolve main conflicts for agent-capabilities PR

Author: Killea

README.md

@@ -525,20 +525,45 @@ AgentChatBus therefore exposes **underscore-style** tool names (e.g. `thread_cre
 
 | Tool | Required Args | Description |
 |---|---|---|
-| `thread_create` | `topic` | Create a new conversation thread. Returns `thread_id`. |
+| `thread_create` | `topic` | Create a new conversation thread. Optional `template` to apply defaults (system prompt, metadata). Returns `thread_id`. |
 | `thread_list` | — | List threads. Optional `status` filter. |
 | `thread_get` | `thread_id` | Get full details of one thread. |
 | `thread_delete` | `thread_id`, `confirm=true` | Permanently delete a thread and all messages (irreversible). |
 
 > **Note**: Thread state management (`set_state`, `close`, `archive`) are available via **REST API** (`/api/threads/{id}/state`, `/api/threads/{id}/close`, `/api/threads/{id}/archive`), not MCP tools.
 
+### Thread Templates
+
+Thread templates provide reusable presets for thread creation. Four built-in templates are included:
+
+| Template ID | Name | Purpose |
+|---|---|---|
+| `code-review` | Code Review | Structured review focused on correctness, security, and style |
+| `security-audit` | Security Audit | Security-focused review with severity ratings |
+| `architecture` | Architecture Discussion | Design trade-offs and system structure evaluation |
+| `brainstorm` | Brainstorm | Free-form ideation, all ideas welcome |
+
+| Tool | Required Args | Description |
+|---|---|---|
+| `template_list` | — | List all available templates (built-in + custom). |
+| `template_get` | `template_id` | Get details of a specific template. |
+| `template_create` | `id`, `name` | Create a custom template. Optional `description`, `system_prompt`, `default_metadata`. |
+
+**Using a template when creating a thread:**
+
+```json
+{ "topic": "My Review Session", "template": "code-review" }
+```
+
+The template's `system_prompt` and `default_metadata` are applied as defaults. Any caller-provided values override the template defaults.
+
 ### Messaging
 
 | Tool | Required Args | Description |
 |---|---|---|
-| `msg_post` | `thread_id`, `author`, `content` | Post a message. Returns `{msg_id, seq}`. Triggers SSE push. |
+| `msg_post` | `thread_id`, `author`, `content` | Post a message. Returns `{msg_id, seq}`. Optional `metadata` with structured keys (`handoff_target`, `stop_reason`, `attachments`). Triggers SSE push. |
 | `msg_list` | `thread_id` | Fetch messages. Optional `after_seq`, `limit`, `include_system_prompt`, and `return_format`. |
-| `msg_wait` | `thread_id`, `after_seq` | **Block** until a new message arrives. Optional `timeout_ms`, `agent_id`, `token`, and `return_format`. |
+| `msg_wait` | `thread_id`, `after_seq` | **Block** until a new message arrives. Optional `timeout_ms`, `agent_id`, `token`, `return_format`, and `for_agent`. |
 
 #### `return_format` (legacy JSON vs native blocks)
 
@@ -553,6 +578,19 @@ AgentChatBus therefore exposes **underscore-style** tool names (e.g. `thread_cre
   - Returns a single `TextContent` block whose `.text` is a JSON-encoded array of messages.
   - Use this if you have older scripts that do `json.loads(tool_result[0].text)`.
 
+#### Structured `metadata` keys
+
+`msg_post` accepts an optional `metadata` object with the following recognized keys:
+
+| Key | Type | Description |
+|---|---|---|
+| `handoff_target` | `string` | Agent ID that should handle this message next. Triggers a `msg.handoff` SSE event. Response includes `handoff_target` for discoverability. |
+| `stop_reason` | `string` | Why the posting agent is ending its turn. Values: `convergence`, `timeout`, `error`, `complete`, `impasse`. Triggers a `msg.stop` SSE event. |
+| `attachments` | `array` | File or image attachments (see below). |
+| `mentions` | `array` | Agent IDs mentioned in the message (web UI format). |
+
+**`for_agent` in `msg_wait`**: pass `for_agent: "<agent_id>"` to receive only messages where `metadata.handoff_target` matches. Useful for directed handoff patterns in multi-agent workflows.
+
 ##### Attachment format (images)
 
 To attach images, pass `metadata` to `msg_post`:
@@ -638,7 +676,11 @@ The server also exposes a plain REST API used by the web console and simulation
 | Method | Path | Description |
 |---|---|---|
 | `GET` | `/api/threads` | List threads (optional `?status=` filter and `?include_archived=` boolean) |
-| `POST` | `/api/threads` | Create thread `{ "topic": "...", "metadata": {...}, "system_prompt": "..." }` |
+| `POST` | `/api/threads` | Create thread `{ "topic": "...", "metadata": {...}, "system_prompt": "...", "template": "code-review" }` |
+| `GET` | `/api/templates` | List all thread templates (built-in + custom) |
+| `GET` | `/api/templates/{id}` | Get template details (404 if not found) |
+| `POST` | `/api/templates` | Create custom template `{ "id": "...", "name": "...", "description": "...", "system_prompt": "..." }` |
+| `DELETE` | `/api/templates/{id}` | Delete custom template (403 if built-in, 404 if not found) |
 | `GET` | `/api/threads/{id}/messages` | List messages (`?after_seq=0&limit=200&include_system_prompt=false`) |
 | `POST` | `/api/threads/{id}/messages` | Post message `{ "author", "role", "content", "metadata": {...}, "mentions": [...] }` |
 | `POST` | `/api/threads/{id}/state` | Change state `{ "state": "discuss\|implement\|review\|done" }` |