@dreb/coding-agent 2.34.3 → 2.36.0

package/docs/rpc.md

@@ -6,10 +6,10 @@ RPC mode enables headless operation of the coding agent via a JSON protocol over
 
 ### Running the agent child as a specific OS user
 
-When using the `RpcClient` from `@dreb/coding-agent`, `RpcClientOptions` accepts optional `uid` and `gid` fields. When set, they are forwarded directly to `child_process.spawn`, so the agent child (and every subprocess it spawns, including `bash`) runs under that OS user/group. When unset they are omitted entirely, leaving spawn behavior unchanged.
+When using the `RpcClient` from `@dreb/coding-agent/rpc`, `RpcClientOptions` accepts optional `uid` and `gid` fields. When set, they are forwarded directly to `child_process.spawn`, so the agent child (and every subprocess it spawns, including `bash`) runs under that OS user/group. When unset they are omitted entirely, leaving spawn behavior unchanged.
 
 ```ts
-import { RpcClient } from "@dreb/coding-agent";
+import { RpcClient } from "@dreb/coding-agent/rpc";
 
 // Parent must hold CAP_SETUID / CAP_SETGID (e.g. run as root) for this to succeed.
 const client = new RpcClient({ cwd: "/srv/users/alice", uid: 4001, gid: 4001 });
@@ -187,6 +187,10 @@ Response:
   "success": true,
   "data": {
     "model": {...},
+    "scopedModels": [
+      {"provider": "anthropic", "id": "claude-sonnet-4-5", "name": "Claude Sonnet 4.5", "reasoning": true, "thinkingLevel": "high"}
+    ],
+    "usingSubscription": false,
     "thinkingLevel": "medium",
     "isStreaming": false,
     "isCompacting": false,
@@ -197,12 +201,79 @@ Response:
     "sessionName": "my-feature-work",
     "autoCompactionEnabled": true,
     "messageCount": 5,
-    "pendingMessageCount": 0
+    "pendingMessageCount": 0,
+    "contextUsage": {
+      "tokens": 60000,
+      "contextWindow": 200000,
+      "percent": 30
+    }
   }
 }
 ```
 
-The `model` field is a full [Model](#model) object or `null`. The `sessionName` field is the display name set via `set_session_name`, or omitted if not set.
+The `model` field is a full [Model](#model) object or `null`. `scopedModels` is the runtime model scope (from settings `enabledModels` / CLI `--models`) in the same order used by model cycling; it is an empty array when no scope is active. `usingSubscription` is true when the active model is using OAuth subscription credentials, matching the TUI footer's `(sub)` cost indicator. The `sessionName` field is the display name set via `set_session_name` or auto-naming, or omitted if not set.
+
+`contextUsage` carries the same numbers the TUI footer shows, computed by the session itself — clients must render these rather than deriving their own estimate. `tokens` and `percent` are `null` when usage is unknown (right after compaction, before the next LLM response). The whole field is omitted when no model is set or the model has no context window.
+
+#### get_resources
+
+Get loaded resource metadata for the current session. This returns paths/names/descriptions only — it does not include context file contents, prompt bodies, skill bodies, or system prompt text.
+
+```json
+{"type": "get_resources"}
+```
+
+Response:
+```json
+{
+  "type": "response",
+  "command": "get_resources",
+  "success": true,
+  "data": {
+    "contextFiles": [{"path": "/repo/AGENTS.md"}],
+    "skills": [{"name": "review-code", "description": "Review code"}],
+    "extensions": [{"name": "my-extension", "path": "/repo/.dreb/extensions/my-extension.ts"}],
+    "promptTemplates": [{"name": "plan", "description": "Create an implementation plan"}],
+    "systemPromptPresent": true
+  }
+}
+```
+
+#### get_git_branch
+
+Get the current git branch for the session cwd. Returns `null` outside a git repository and `"detached"` for detached HEAD.
+
+```json
+{"type": "get_git_branch"}
+```
+
+Response:
+```json
+{
+  "type": "response",
+  "command": "get_git_branch",
+  "success": true,
+  "data": {"branch": "feature/dashboard"}
+}
+```
+
+#### get_daily_cost
+
+Get the same-day aggregate cost across all session files. The RPC process scans once on first call so the first response is current, then returns the cached value (refreshed periodically by the tracker).
+
+```json
+{"type": "get_daily_cost"}
+```
+
+Response:
+```json
+{
+  "type": "response",
+  "command": "get_daily_cost",
+  "success": true,
+  "data": {"cost": 1.23}
+}
+```
 
 #### get_messages
 
@@ -244,6 +315,29 @@ Response contains the full [Model](#model) object:
 }
 ```
 
+#### resolve_model
+
+Resolve a model pattern using the same matching rules as the interactive `/model` command, without switching the current session. Returns `null` if no model matches; a warning may be included when the match required fallback behavior.
+
+```json
+{"type": "resolve_model", "pattern": "sonnet"}
+```
+
+Response:
+```json
+{
+  "type": "response",
+  "command": "resolve_model",
+  "success": true,
+  "data": {"model": {...}, "warning": "matched provider/model-id"}
+}
+```
+
+If no model matches:
+```json
+{"type": "response", "command": "resolve_model", "success": true, "data": null}
+```
+
 #### cycle_model
 
 Cycle to the next available model. Returns `null` data if only one model available.
@@ -288,6 +382,46 @@ Response contains an array of full [Model](#model) objects:
 }
 ```
 
+### Buddy
+
+Buddy commands run inside the agent process so provider credentials never leave the RPC child. They are exposed for clients that choose to render the terminal companion; most non-terminal clients can ignore them.
+
+#### buddy_hatch
+
+Create or load the current buddy state.
+
+```json
+{"type": "buddy_hatch"}
+```
+
+Response:
+```json
+{
+  "type": "response",
+  "command": "buddy_hatch",
+  "success": true,
+  "data": {"state": {...}}
+}
+```
+
+#### buddy_reroll
+
+Reroll buddy appearance/state.
+
+```json
+{"type": "buddy_reroll"}
+```
+
+Response:
+```json
+{
+  "type": "response",
+  "command": "buddy_reroll",
+  "success": true,
+  "data": {"state": {...}}
+}
+```
+
 ### Thinking
 
 #### set_thinking_level
@@ -361,6 +495,32 @@ Response:
 {"type": "response", "command": "set_follow_up_mode", "success": true}
 ```
 
+#### get_pending_messages
+
+Return queued steering and follow-up messages without clearing them. `steering` and `followUp` are the text-only compatibility view; `steeringMessages` and `followUpMessages` include inline image attachments for clients that need to restore queued multimodal turns.
+
+```json
+{"type": "get_pending_messages"}
+```
+
+Response:
+```json
+{"type": "response", "command": "get_pending_messages", "success": true, "data": {"steering": ["steer text"], "followUp": ["follow-up text"], "steeringMessages": [{"text": "steer text", "images": [{"type": "image", "data": "...", "mimeType": "image/png"}]}], "followUpMessages": [{"text": "follow-up text"}]}}
+```
+
+#### clear_pending_messages
+
+Clear queued steering and follow-up messages, returning the cleared payloads. This mirrors the TUI restore-to-editor flow; multimodal clients should use `steeringMessages`/`followUpMessages` so inline images are not lost.
+
+```json
+{"type": "clear_pending_messages"}
+```
+
+Response:
+```json
+{"type": "response", "command": "clear_pending_messages", "success": true, "data": {"steering": ["steer text"], "followUp": ["follow-up text"], "steeringMessages": [{"text": "steer text", "images": [{"type": "image", "data": "...", "mimeType": "image/png"}]}], "followUpMessages": [{"text": "follow-up text"}]}}
+```
+
 ### Compaction
 
 #### compact
@@ -404,6 +564,19 @@ Response:
 {"type": "response", "command": "set_auto_compaction", "success": true}
 ```
 
+#### abort_compaction
+
+Abort an in-progress manual or automatic compaction.
+
+```json
+{"type": "abort_compaction"}
+```
+
+Response:
+```json
+{"type": "response", "command": "abort_compaction", "success": true}
+```
+
 ### Retry
 
 #### set_auto_retry
@@ -621,6 +794,39 @@ If an extension cancelled the switch:
 {"type": "response", "command": "switch_session", "success": true, "data": {"cancelled": true}}
 ```
 
+#### delete_session
+
+Delete a session file. Deletion tries trash first and falls back to unlink. The currently active session cannot be deleted.
+
+```json
+{"type": "delete_session", "sessionPath": "/path/to/session.jsonl"}
+```
+
+Response:
+```json
+{"type": "response", "command": "delete_session", "success": true, "data": {"method": "trash"}}
+```
+
+If attempting to delete the currently active session:
+```json
+{
+  "type": "response",
+  "command": "delete_session",
+  "success": false,
+  "error": "Cannot delete the currently active session"
+}
+```
+
+The path uses the same unrestricted, cross-project addressing as [`switch_session`](#switch_session): it is `resolve()`d (collapsing `.`/`..`/relative segments) and then checked against the active session. There is **no** sessions-directory containment guard — this is a trusted local channel, and any frontend exposing it (e.g. the web dashboard) is expected to enforce its own authorization. Deletion is refused only for the currently active session, non-`.jsonl` paths, and nonexistent files:
+```json
+{
+  "type": "response",
+  "command": "delete_session",
+  "success": false,
+  "error": "Not a session file (expected .jsonl): /tmp/evil.txt"
+}
+```
+
 #### fork
 
 Create a new fork from a previous user message. Can be cancelled by a `session_before_fork` extension event handler. Returns the text of the message being forked from.
@@ -709,7 +915,7 @@ Response:
 }
 ```
 
-The current session name is available via `get_state` in the `sessionName` field.
+The current session name is available via `get_state` in the `sessionName` field. Successful renames also emit a `session_name_changed` event.
 
 ### Commands
 
@@ -795,6 +1001,386 @@ Each session has:
 - `messageCount`: Number of messages in the session
 - `firstMessage`: First user message text (for preview)
 
+#### list_all_sessions
+
+List sessions across all projects. Returns sessions sorted by most recently modified first. May be slow with many sessions. If the underlying listing fails (an I/O error reading the sessions store), the command responds `success: false` rather than a silently-empty list — so a client can distinguish "no sessions" from "listing failed."
+
+```json
+{"type": "list_all_sessions"}
+```
+
+Response:
+```json
+{
+  "type": "response",
+  "command": "list_all_sessions",
+  "success": true,
+  "data": {
+    "sessions": [
+      {
+        "path": "/home/user/.dreb/agent/sessions/--home-user-project--/2024-01-15T10-30-00_abc123.jsonl",
+        "id": "abc123-def456-...",
+        "cwd": "/home/user/project",
+        "name": "feature-work",
+        "created": "2024-01-15T10:30:00.000Z",
+        "modified": "2024-01-15T11:45:00.000Z",
+        "messageCount": 12,
+        "firstMessage": "Help me refactor the auth module"
+      }
+    ]
+  }
+}
+```
+
+Each session has the same fields as `list_sessions`.
+
+### Background Agents
+
+#### list_background_agents
+
+List background subagents tracked by this process's registry — running and recently completed (finished entries are pruned after ~5 minutes). `sessionDir` is known from launch; `sessionFile` appears once the child process exits. Live transcripts are delivered via `background_agent_event` events (see Events), not by reading these paths.
+
+```json
+{"type": "list_background_agents"}
+```
+
+Response:
+```json
+{
+  "type": "response",
+  "command": "list_background_agents",
+  "success": true,
+  "data": {
+    "agents": [
+      {
+        "agentId": "a1b2c3d4e5f6",
+        "agentType": "Explore",
+        "taskSummary": "Explore task 1/2",
+        "startedAt": "2026-07-07T12:00:00.000Z",
+        "status": "running",
+        "sessionDir": "/home/user/.dreb/agent/subagent-sessions/a1b2c3d4e5f6",
+        "cwd": "/home/user/project"
+      }
+    ]
+  }
+}
+```
+
+#### list_agent_types
+
+List discoverable subagent types for the current session working directory. This includes package-bundled agents, user-level agents, and project-level agents in `.dreb/agents/*.md`. Results are sorted by `name`.
+
+```json
+{"type": "list_agent_types"}
+```
+
+Response:
+```json
+{
+  "type": "response",
+  "command": "list_agent_types",
+  "success": true,
+  "data": {
+    "agentTypes": [
+      {
+        "name": "code-reviewer",
+        "description": "Reviews code changes for correctness, idiomatic patterns, and maintainability"
+      },
+      {
+        "name": "Explore",
+        "description": "Codebase and web exploration — find files, search code, search the web, answer questions. Read-only."
+      }
+    ]
+  }
+}
+```
+
+Each agent type has:
+- `name`: Agent type name to use as an `agentModels` key.
+- `description`: Human-readable description from the agent frontmatter.
+
+### Session Tree
+
+Sessions are append-only trees: editing/retrying a message or navigating back creates a branch rather than discarding entries. These commands expose tree inspection and navigation — the scriptable equivalent of the TUI's `/tree` selector.
+
+#### get_tree
+
+Get the session tree as a serializable DTO, plus the current leaf position.
+
+```json
+{"type": "get_tree"}
+```
+
+Response:
+```json
+{
+  "type": "response",
+  "command": "get_tree",
+  "success": true,
+  "data": {
+    "roots": [
+      {
+        "id": "a1b2c3d4",
+        "parentId": null,
+        "type": "message",
+        "role": "user",
+        "preview": "Help me refactor the auth module",
+        "timestamp": "2024-01-15T10:30:00.000Z",
+        "label": "start",
+        "children": [
+          {
+            "id": "e5f6a7b8",
+            "parentId": "a1b2c3d4",
+            "type": "message",
+            "role": "assistant",
+            "preview": "Sure — let's look at the middleware first.",
+            "timestamp": "2024-01-15T10:30:05.000Z",
+            "children": []
+          }
+        ]
+      }
+    ],
+    "leafId": "e5f6a7b8"
+  }
+}
+```
+
+Each node has:
+- `id`: Entry id (use with `navigate_tree`, `fork`)
+- `parentId`: Parent entry id, or `null` for a root. Orphaned roots keep their original non-null `parentId` (referencing an entry not in the tree) — prefer `children` for hierarchy
+- `type`: Entry type (`message`, `compaction`, `branch_summary`, `model_change`, `thinking_level_change`, `custom`, `custom_message`, `label`, `session_info`)
+- `role`: Message role, present only for `type: "message"` entries (`user`, `assistant`, `toolResult`, `bashExecution`)
+- `preview`: Short single-line content preview (whitespace-collapsed, max 200 chars). Non-text entries use bracketed forms like `[compaction: 50k tokens]`, `[branch summary]: ...`, `[model: claude-sonnet-4]`, `[bash]: npm test`
+- `timestamp`: ISO timestamp of the entry
+- `label`: Resolved user label, if any
+- `children`: Child nodes, oldest first
+
+`leafId` is the id of the current leaf entry (`null` for an empty session) — the "you are here" marker for a tree UI. The DTO is stable and deliberately does **not** include full message payloads; use `get_messages` for content after navigation.
+
+A well-formed session has exactly one root; orphaned entries (broken parent chains) also surface as roots.
+
+#### navigate_tree
+
+Navigate the current session to a different tree node, optionally summarizing the abandoned branch. Unlike `fork` (which creates a new session file), navigation stays within the same session file.
+
+```json
+{"type": "navigate_tree", "targetId": "a1b2c3d4"}
+```
+
+With branch summarization:
+```json
+{
+  "type": "navigate_tree",
+  "targetId": "a1b2c3d4",
+  "summarize": true,
+  "customInstructions": "Focus on decisions made",
+  "replaceInstructions": false,
+  "label": "before-refactor"
+}
+```
+
+Options (all optional, passed through verbatim to the core navigation — the TUI's interactive summarize prompt is not replicated):
+- `summarize`: Generate an LLM summary of the branch being abandoned and attach it at the navigation target. Requires a model and API key.
+- `customInstructions`: Extra instructions for the summarizer.
+- `replaceInstructions`: If `true`, `customInstructions` replaces the default summarizer prompt instead of augmenting it.
+- `label`: Label to attach to the branch summary entry (or to the target entry when not summarizing).
+
+Response:
+```json
+{
+  "type": "response",
+  "command": "navigate_tree",
+  "success": true,
+  "data": {"cancelled": false, "editorText": "Help me refactor the auth module"}
+}
+```
+
+- `cancelled`: `true` if an extension (`session_before_tree`) cancelled the navigation or summarization was aborted.
+- `editorText`: Present when navigating to a `user` (or `custom_message`) entry — the text of that message. The leaf moves to the entry's *parent* so the message can be re-edited and resubmitted; a client should pre-fill its input with this text (this is what the TUI does). Navigating to any other entry type moves the leaf to the entry itself and returns no `editorText`.
+
+After a successful `navigate_tree`, `get_state` and `get_messages` reflect the post-navigation session state.
+
+Errors are explicit `success: false` responses:
+```json
+{
+  "type": "response",
+  "command": "navigate_tree",
+  "success": false,
+  "error": "Entry zzz not found"
+}
+```
+
+- Unknown `targetId`: `Entry <id> not found`
+- Agent currently streaming: `Cannot navigate the session tree while the agent is streaming. Abort or wait for idle first.`
+- Branch summarization or compaction in progress: `Cannot navigate the session tree while summarization or compaction is in progress. Wait for idle first.`
+- `summarize: true` with no model available: `No model available for summarization`
+
+Note: with `summarize: true` the command is LLM-bound and can take a while. `RpcClient.navigateTree` uses a 5-minute client timeout (overridable via its client-side `timeoutMs` option, which is not sent over the wire); raw-protocol clients should budget accordingly. There is no scriptable abort for an in-flight branch summarization over RPC. A client-side timeout does not stop the server: a timed-out `navigate_tree` may still complete server-side and move the leaf — after a timeout, resync with `get_tree`/`get_state` instead of assuming the navigation failed.
+
+### Settings
+
+Persistent default settings, backed by the settings file (see [settings.md](settings.md)). These are distinct from live session state:
+
+- **Persistent defaults** (`get_settings` / `set_settings`): the values stored in `settings.json` that seed fresh runtimes — default provider/model, default thinking level, queue modes, compaction/retry/image/context/skill/thinking-display/transport toggles, and per-agent model fallback lists. Writing them does **not** change the running session.
+- **Runtime state** (`get_state` / `set_model` / `set_thinking_level` / `set_steering_mode` / `set_follow_up_mode` / `set_auto_compaction` / `set_auto_retry`): the state of the live session. Note that the runtime setters also persist their values as new defaults as a side effect.
+
+A dashboard settings tab typically reads both: `get_state` for what's active now, `get_settings` for what the next startup will use.
+
+#### get_settings
+
+Get the persistent default settings (merged global + project view).
+
+```json
+{"type": "get_settings"}
+```
+
+Response:
+```json
+{
+  "type": "response",
+  "command": "get_settings",
+  "success": true,
+  "data": {
+    "defaultProvider": "anthropic",
+    "defaultModel": "claude-sonnet-4-5",
+    "defaultThinkingLevel": "high",
+    "steeringMode": "one-at-a-time",
+    "followUpMode": "one-at-a-time",
+    "compactionEnabled": true,
+    "retryEnabled": true,
+    "imageAutoResize": true,
+    "blockImages": false,
+    "enableSkillCommands": true,
+    "autoLoadNestedContext": true,
+    "transport": "sse",
+    "hideThinkingBlock": false,
+    "agentModels": {
+      "Explore": ["anthropic/sonnet", "openai/gpt-5"]
+    }
+  }
+}
+```
+
+`defaultProvider`, `defaultModel`, and `defaultThinkingLevel` are absent if never set. `agentModels` is the merged global + project view; project entries win per agent name.
+
+#### set_settings
+
+Update persistent default settings. Takes a partial payload — only the supplied keys change. The whole payload is validated before anything is applied: on any invalid field, nothing changes and the response is an explicit error. Writes target the global settings file (same scope as every runtime setter).
+
+```json
+{"type": "set_settings", "settings": {"defaultThinkingLevel": "low", "retryEnabled": false}}
+```
+
+Setting the default model (both keys required together, validated against available models — the provider must have credentials configured, same rule as `set_model`):
+
+```json
+{"type": "set_settings", "settings": {"defaultProvider": "anthropic", "defaultModel": "claude-sonnet-4-5"}}
+```
+
+Setting per-agent model fallback lists:
+
+```json
+{
+  "type": "set_settings",
+  "settings": {
+    "agentModels": {
+      "Explore": ["anthropic/sonnet", "openai/gpt-5"],
+      "code-reviewer": []
+    }
+  }
+}
+```
+
+For `agentModels`, a non-empty array writes the global fallback list for that agent. An empty array removes the global entry, so that agent uses its agent-definition default unless a project-level override exists.
+
+Response is the full settings snapshot after the write (same shape as `get_settings`), plus `warnings` when the write was accepted but a project-level override shadows part of it:
+
+```json
+{
+  "type": "response",
+  "command": "set_settings",
+  "success": true,
+  "data": {
+    "defaultProvider": "anthropic",
+    "defaultModel": "claude-sonnet-4-5",
+    "defaultThinkingLevel": "low",
+    "steeringMode": "one-at-a-time",
+    "followUpMode": "one-at-a-time",
+    "compactionEnabled": true,
+    "retryEnabled": false,
+    "imageAutoResize": true,
+    "blockImages": false,
+    "enableSkillCommands": true,
+    "autoLoadNestedContext": true,
+    "transport": "sse",
+    "hideThinkingBlock": false,
+    "agentModels": {}
+  }
+}
+```
+
+Project-shadow warning example (the global write still lands, but the returned merged `agentModels.Explore` remains the project value until `.dreb/settings.json` is edited):
+
+```json
+{
+  "type": "response",
+  "command": "set_settings",
+  "success": true,
+  "data": {
+    "steeringMode": "one-at-a-time",
+    "followUpMode": "one-at-a-time",
+    "compactionEnabled": true,
+    "retryEnabled": true,
+    "imageAutoResize": true,
+    "blockImages": false,
+    "enableSkillCommands": true,
+    "autoLoadNestedContext": true,
+    "transport": "sse",
+    "hideThinkingBlock": false,
+    "agentModels": {
+      "Explore": ["project/model"]
+    },
+    "warnings": [
+      "A project-level agentModels override for \"Explore\" (.dreb/settings.json) takes precedence — this change to global settings will have no effect. Edit the project settings file to change it."
+    ]
+  }
+}
+```
+
+Valid keys and values:
+
+| Key | Values |
+|-----|--------|
+| `defaultProvider` + `defaultModel` | Must be supplied together; must match a model from `get_available_models` |
+| `defaultThinkingLevel` | `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"` (validated against the full set — a stored default is not tied to the current model's capabilities) |
+| `steeringMode` | `"all"`, `"one-at-a-time"` |
+| `followUpMode` | `"all"`, `"one-at-a-time"` |
+| `compactionEnabled` | boolean |
+| `retryEnabled` | boolean |
+| `imageAutoResize` | boolean |
+| `blockImages` | boolean |
+| `enableSkillCommands` | boolean |
+| `autoLoadNestedContext` | boolean |
+| `transport` | `"sse"`, `"websocket"`, `"auto"` |
+| `hideThinkingBlock` | boolean |
+| `agentModels` | Plain object mapping agent names to arrays of non-empty model id strings; empty arrays remove the global entry for that agent |
+
+Errors are explicit `success: false` responses (nothing is applied on any of them):
+
+- Missing/empty payload: `set_settings requires at least one setting to change`
+- Unknown key: `Unknown settings key(s): ...`
+- Invalid enum value: `Invalid defaultThinkingLevel: "extreme". Valid values: off, minimal, low, medium, high, xhigh`
+- Invalid transport: `Invalid transport: "http". Valid values: sse, websocket, auto`
+- Non-boolean toggle: `Invalid retryEnabled: "yes". Must be a boolean`
+- Invalid `agentModels` object: `Invalid agentModels: must be a plain object mapping agent names to model fallback arrays`
+- Invalid `agentModels` entry (the offending agent key is named): `Invalid agentModels["Explore"]: expected an array of non-empty strings`
+- Provider without model (or vice versa): `defaultProvider and defaultModel must be set together`
+- Unavailable model: `Model not found: provider/model-id`
+- Corrupt settings file: `Cannot write settings: the global settings file failed to load (fix or remove the corrupt settings.json first)` — without this guard the write would silently no-op
+- Write failure (I/O error): `Failed to persist settings: ...`
+
+Unlike `set_thinking_level` (which silently clamps to the current model's capabilities), `set_settings` rejects invalid values loudly — a dashboard needs the error, not a silent correction.
+
 ### Version
 
 #### get_version
@@ -833,12 +1419,24 @@ Events are streamed to stdout as JSON lines during agent operation. Events do NO
 | `tool_execution_start` | Tool begins execution |
 | `tool_execution_update` | Tool execution progress (streaming output) |
 | `tool_execution_end` | Tool completes |
+| `stream_retry` | Stream dropped mid-turn; retrying (partial output discarded) |
+| `length_retry` | Response hit the token limit; retrying with a larger budget |
 | `auto_compaction_start` | Auto-compaction begins |
 | `auto_compaction_end` | Auto-compaction completes |
 | `auto_retry_start` | Auto-retry begins (after transient error) |
 | `auto_retry_end` | Auto-retry completes (success or final failure) |
+| `background_agent_start` | Background subagent launched (includes `sessionDir`) |
+| `background_agent_end` | Background subagent finished (includes `sessionFile` when known) |
+| `background_agent_event` | Relayed event from a background subagent's own stream |
+| `parent_paused_for_background_agents` | Parent paused waiting on background agents |
+| `session_name_changed` | Session display name changed (manual rename, extension rename, or auto-title) |
+| `tasks_update` | Session task list replaced (see the `tasks_update` tool) |
+| `suggest_next` | Agent suggested a next command |
 | `extension_error` | Extension threw an error |
 
+Treat the event union as open — dispatch on `type` and ignore unknown values
+rather than validating against a closed list; new event types may be added.
+
 ### agent_start
 
 Emitted when the agent begins processing a prompt. Includes the resolved model.
@@ -1032,6 +1630,55 @@ On final failure (max retries exceeded):
 }
 ```
 
+### background_agent_start / background_agent_end / background_agent_event
+
+Lifecycle and live-observability events for background subagents (the `subagent` tool's background mode).
+
+`background_agent_start` fires at launch. `sessionDir` is the directory the child will write its session JSONL into (per-launch, known before spawn):
+
+```json
+{
+  "type": "background_agent_start",
+  "agentId": "a1b2c3d4e5f6",
+  "agentType": "Explore",
+  "taskSummary": "Explore task 1/2",
+  "sessionDir": "/home/user/.dreb/agent/subagent-sessions/a1b2c3d4e5f6"
+}
+```
+
+`background_agent_end` fires after the result is delivered to the parent agent. `sessionFile` is the child's session JSONL path when one was written:
+
+```json
+{
+  "type": "background_agent_end",
+  "agentId": "a1b2c3d4e5f6",
+  "agentType": "Explore",
+  "success": true,
+  "sessionFile": "/home/user/.dreb/agent/subagent-sessions/a1b2c3d4e5f6/2026-07-07T12-00-00-000Z_uuid.jsonl"
+}
+```
+
+`background_agent_event` relays every JSONL event the child process emits (the same event union documented here, plus the initial session header), verbatim, tagged with the child's `agentId`. This is the live-transcript transport for observers like the dashboard — no session-file tailing needed. Streaming children emit `message_update` deltas at high frequency; consumers that fan events out further (e.g. over a network) should batch or throttle:
+
+```json
+{
+  "type": "background_agent_event",
+  "agentId": "a1b2c3d4e5f6",
+  "event": {"type": "tool_execution_start", "toolName": "read", "args": {"path": "src/index.ts"}}
+}
+```
+
+`parent_paused_for_background_agents` fires when the parent agent pauses because its background-agent turn guardrail was hit while agents are still running:
+
+```json
+{
+  "type": "parent_paused_for_background_agents",
+  "runningAgentCount": 2,
+  "turnsUsed": 10,
+  "turnLimit": 10
+}
+```
+
 ### extension_error
 
 Emitted when an extension throws an error.