Show in-progress tool calls

docs/api/rest.md

@@ -314,7 +314,7 @@ Behavior notes:
   - `CHAT_CODEX_SSH_PRIVATE_KEY_B64=<base64-private-key>` (optional fallback when a volume mount is not practical)
   - `CHAT_CODEX_EXEC_TIMEOUT_MS=600000` (optional)
   - `CHAT_SHELL_EXEC_TIMEOUT_MS=120000` (optional)
-- When a tool call is executed, backend stores a chat `Message` with `role: "tool"` and tool metadata (`metadata.kind = "tool_call"`). Streaming requests persist each completed tool call as its SSE `tool_call` event is emitted, then store the assistant output when the completion finishes.
+- When a tool call is executed, backend stores a chat `Message` with `role: "tool"` and tool metadata (`metadata.kind = "tool_call"`). Streaming requests emit an initiated SSE `tool_call` event before execution, then persist each completed or failed tool call as its terminal SSE `tool_call` event is emitted, then store the assistant output when the completion finishes.
 - `anthropic` currently runs without server-managed tool calls.
 
 ## Searches

docs/api/streaming-chat.md

@@ -91,6 +91,8 @@ Event order:
 3. Zero or more `delta`
 4. Exactly one terminal event: `done` or `error`
 
+Each tool invocation can emit multiple `tool_call` events with the same `toolCallId`. The backend emits `status: "initiated"` before the tool starts executing, then emits `status: "completed"` or `status: "failed"` when execution finishes. Clients should upsert by `toolCallId` instead of appending each event.
+
 ### `meta`
 
 ```json
@@ -115,6 +117,19 @@ For `persist: false` streams, `chatId` and `callId` are `null`.
 
 ### `tool_call`
 
+```json
+{
+  "toolCallId": "call_123",
+  "name": "web_search",
+  "status": "initiated",
+  "summary": "Searching web for 'latest CPI release'.",
+  "args": { "query": "latest CPI release" },
+  "startedAt": "2026-03-02T10:00:00.000Z"
+}
+```
+
+Terminal tool-call event:
+
 ```json
 {
   "toolCallId": "call_123",
@@ -125,11 +140,12 @@ For `persist: false` streams, `chatId` and `callId` are `null`.
   "startedAt": "2026-03-02T10:00:00.000Z",
   "completedAt": "2026-03-02T10:00:00.820Z",
   "durationMs": 820,
-  "error": null,
   "resultPreview": "{\"ok\":true,...}"
 }
 ```
 
+`status` is one of `initiated`, `completed`, or `failed`. `completedAt` and `durationMs` are only present on terminal events. `error` is present on failed terminal events; `resultPreview` is present on terminal events when available.
+
 ### `done`
 
 ```json
@@ -178,7 +194,8 @@ Backend database remains source of truth.
 
 For persisted streams:
 - Client may optimistically render accumulated `delta` text.
-- Backend persists each completed tool call as a `tool` message before emitting its `tool_call` SSE event, so chat detail refreshes can show completed tool calls while the assistant response is still running.
+- Backend emits initiated tool-call events without persisting them.
+- Backend persists each completed or failed tool call as a `tool` message before emitting its terminal `tool_call` SSE event, so chat detail refreshes can show completed tool calls while the assistant response is still running.
 
 On successful persisted completion:
 - Backend persists assistant `Message` and updates `LlmCall` usage/latency in a transaction.