zcode-acp-server 0.1.0 → 0.2.0

package/docs/ARCHITECTURE.md

@@ -25,18 +25,58 @@ zcode-acp-server (stdio JSON-RPC ACP)
 zcode app-server --stdio (line-delimited JSON)
 ```
 
+## ACP Handshake
+
+The `initialize` request (`server.ts`) negotiates the protocol version and
+declares the agent's shape to the editor:
+
+- **`protocolVersion`** — pinned to `PROTOCOL_VERSION` (currently 1).
+- **`agentInfo`** — name/title/version from `AGENT_INFO` in `utils.ts`.
+- **`agentCapabilities`** — `loadSession`, plus `sessionCapabilities.list /
+resume / fork`. The prompt capabilities (image/audio/embeddedContext) and
+  MCP capabilities are all off.
+- **`authMethods`** — a single agent-type entry (`zcode-credentials`). The
+  bridge reads the GLM API key itself from `~/.zcode/v2/config.json` and
+  forwards it to the ZCode subprocess via `ANTHROPIC_API_KEY`; the editor
+  never supplies credentials. Omitting the `type` field defaults to `"agent"`,
+  which the ACP registry's auth-check accepts as "agent self-handles auth".
+
+`initialize` does **not** spawn the backend, and neither does `session/new`:
+the backend is lazily created on the first backend RPC — for a fresh session
+that is the first `session/create` at its first use (prompt / config change /
+extension method). This keeps the handshake succeeding even in an environment
+without `~/.zcode/v2/config.json` (e.g. the registry CI runs `initialize` with
+an isolated `HOME`).
+
+Client capabilities advertised at `initialize` are recorded on the server
+(`clientCapabilities`) and drive later behaviour: `supportsElicitationForm()`
+gates form-based elicitation, and `supportsTerminalOutput()` gates Zed's Bash
+terminal UI.
+
 ## Core Data Flow
 
 ### 1. Session lifecycle
 
 ```
-session/new → session/create → register EventListener
+session/new → placeholder id (backend session NOT created yet)
+     |
+first use: prompt / set_config_option / extension method
+     |
+  session/create → register EventListener
      |
 prompt request → session/send → EventTranslator translates → dispatchEvent
      |                                  |
   end_turn / cancelled         session/update notification
 ```
 
+Sessions are materialized lazily (`ensureRealSession`): an editor startup that
+never sends a message leaves no empty session in the backend or the App's task
+index. The placeholder → backend-session mapping is persisted to
+`~/.zcode/v2/acp-lazy-sessions.json` (`src/lazy-sessions.ts`), so a `session/
+resume` / `session/load` of a placeholder from a previous bridge lifetime still
+resolves: with a recorded backend id the real session is resumed, without one a
+fresh (empty) session is materialized — never "Session not found".
+
 ### 2. Event stream subscription
 
 ```
@@ -52,11 +92,13 @@ pollEvent() consumes → EventTranslator.translate()
 ### 3. Dual-path event handling
 
 #### Real-time path (EventTranslator)
+
 - Listens to zcode `session/event` pushes
 - Translates each event to an ACP `session/update` in real time
 - Maintains `seenToolIds` to avoid duplicates
 
 #### Snapshot path (ProjectionDiffer)
+
 - On turn completion, builds a snapshot from `session/messages` + `session/read`
 - Diffs two snapshots to produce new events (PlanUpdate / TextDelta / ToolCallNew, etc.)
 - Used for turn-completion triage and stall recovery
@@ -82,6 +124,7 @@ Key: **`seenToolIds` synchronization**
 
 In `session.ts:629`, after the event path finishes processing, the state is
 synced to the differ:
+
 ```typescript
 for (const seenId of translator.seenToolIds) {
   differ.markToolSeen(seenId);
@@ -92,49 +135,64 @@ This ensures the snapshot diff does not re-emit tools already handled by the
 event path, preventing Bash terminal output from being overwritten by a
 content-less ToolCallNew.
 
+## Data & Privacy
+
+**No telemetry, no analytics, no third-party network calls.** The server is a
+local relay: prompts, code, and tool outputs pass through process memory on
+their way between the editor and the ZCode subprocess, but reach the GLM cloud
+API only because the ZCode backend itself sends them for inference.
+
+| Concern | Detail |
+| ------- | ------ |
+| Network | One outbound request in the whole codebase — `src/quota/client.ts` GET to the quota API, Bearer token only, no body |
+| Credentials | API key from `~/.zcode/v2/config.json` (authenticates the subprocess + quota request), never logged. OAuth handled by the ZCode subprocess, not this server |
+| Disk | No new files. Writes only to the existing `~/.zcode/v2/tasks-index.sqlite` — syncs sessions into the ZCode app's history & search (session title + first prompt) |
+| Logging | `log()`/`warn()` → stderr only for troubleshooting; even with `ZCODE_ACP_DEBUG=1`, no prompts/code/keys are logged |
+
 ## Module Responsibilities
 
 ### `backend/` — ZCode process communication
 
-| File | Responsibility |
-|------|------|
-| `client.ts` | Spawn/manage the zcode subprocess, reader-loop, request/response multiplexing, process watchdog |
-| `listener.ts` | EventStreamListener (subscribe/consume the event stream) and TurnMonitor (snapshot polling) |
-| `types.ts` | ZCode JSON-RPC message type definitions |
+| File          | Responsibility                                                                                  |
+| ------------- | ----------------------------------------------------------------------------------------------- |
+| `client.ts`   | Spawn/manage the zcode subprocess, reader-loop, request/response multiplexing, process watchdog |
+| `listener.ts` | EventStreamListener (subscribe/consume the event stream) and TurnMonitor (snapshot polling)     |
+| `types.ts`    | ZCode JSON-RPC message type definitions                                                         |
 
 ### `translators/` — Event translation
 
-| File | Responsibility |
-|------|------|
-| `event-translator.ts` | Translate zcode events to InternalEvent (real-time path) |
-| `projection-differ.ts` | Diff two snapshots to produce InternalEvent (snapshot path) |
-| `tool-helpers.ts` | Tool-related pure functions: title generation, output rendering, diff parsing, location extraction |
-| `types.ts` | InternalEvent union type and plan entry builders |
+| File                   | Responsibility                                                                                     |
+| ---------------------- | -------------------------------------------------------------------------------------------------- |
+| `event-translator.ts`  | Translate zcode events to InternalEvent (real-time path)                                           |
+| `projection-differ.ts` | Diff two snapshots to produce InternalEvent (snapshot path)                                        |
+| `tool-helpers.ts`      | Tool-related pure functions: title generation, output rendering, diff parsing, location extraction |
+| `types.ts`             | InternalEvent union type and plan entry builders                                                   |
 
 ### `handlers/` — ACP method handling
 
-| File | Responsibility |
-|------|------|
-| `session.ts` | session/new/list/resume/load/prompt/set_config_option/cancel |
-| `extensions.ts` | fork/rewind/rewindCascade/goal/compact/steer/cancelBackgroundTask/setModel/setMode/setThoughtLevel |
-| `dispatch.ts` | dispatchEvent single exit point: InternalEvent → ACP session/update |
+| File                 | Responsibility                                                                                               |
+| -------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `session.ts`         | session/new/list/resume/load/prompt/set_config_option/cancel                                                 |
+| `extensions.ts`      | fork/rewind/rewindCascade/goal/compact/steer/cancelBackgroundTask/setModel/setMode/setThoughtLevel           |
+| `dispatch.ts`        | dispatchEvent single exit point: InternalEvent → ACP session/update                                          |
+| `background-tasks.ts` | Session-scoped `BackgroundTaskListener` — forwards background sub-agent status (`session.updated` taskId) + completion-notification turns to the client OUTSIDE request handlers (lives across prompts) |
 | `server-requests.ts` | Handle zcode interaction/* requests (tool auth, ExitPlanMode, AskUserQuestion), protocol negotiation routing |
-| `io.ts` | ACP notification helpers (including `sendAvailableCommandsDeferred` deferred notification) |
-| `slash.ts` | Interception of `/`-prefixed commands (/compact /goal /fork /rewind /steer /model /mode /thought) |
+| `io.ts`              | ACP notification helpers (including `sendAvailableCommandsDeferred` deferred notification)                   |
+| `slash.ts`           | Interception of `/`-prefixed commands (/compact /goal /fork /rewind /steer /model /mode /thought)            |
 
 ### `interaction/` — Interaction bridging
 
-| File | Responsibility |
-|------|------|
+| File         | Responsibility                                                                                   |
+| ------------ | ------------------------------------------------------------------------------------------------ |
 | `adapter.ts` | Conversion adapter from zcode interaction requests to ACP (requestPermission + elicitation form) |
 
 ### `config/` — Configuration management
 
-| File | Responsibility |
-|------|------|
-| `options.ts` | configOptions / modes construction, set_config_option dispatch |
-| `runtime-model.ts` | runtimeModel overlay construction and application |
-| `model-cache.ts` | Model ID cache and usage initialization |
+| File               | Responsibility                                                 |
+| ------------------ | -------------------------------------------------------------- |
+| `options.ts`       | configOptions / modes construction, set_config_option dispatch |
+| `runtime-model.ts` | runtimeModel overlay construction and application              |
+| `model-cache.ts`   | Model ID cache and usage initialization                        |
 
 ## Key State Machines
 
@@ -222,12 +280,12 @@ mirroring the Python bridge's `_pending_post_notifs` queue +
 The session mode can change through four entry points, all of which must
 notify the editor UI:
 
-| Trigger | Path | Notifies UI |
-|------|------|:---:|
-| `session/setMode` request | `extensions.ts:setMode` | yes |
-| `session/set_config_option` (mode) | `session.ts:setConfigOptionHandler` → `emitConfigOptionUpdate` | yes |
-| `/mode` slash command | `slash.ts` → `emitConfigOptionUpdate` | yes |
-| In-turn `EnterPlanMode`/`ExitPlanMode` | reconciled at turn completion | yes |
+| Trigger                                | Path                                                           | Notifies UI |
+| -------------------------------------- | -------------------------------------------------------------- | :---------: |
+| `session/setMode` request              | `extensions.ts:setMode`                                        |     yes     |
+| `session/set_config_option` (mode)     | `session.ts:setConfigOptionHandler` → `emitConfigOptionUpdate` |     yes     |
+| `/mode` slash command                  | `slash.ts` → `emitConfigOptionUpdate`                          |     yes     |
+| In-turn `EnterPlanMode`/`ExitPlanMode` | reconciled at turn completion                                  |     yes     |
 
 The in-turn path bypasses the bridge entirely, so `prompt()` runs
 `emitModeIfChanged` (`session.ts`) at turn completion: it re-reads the
@@ -277,12 +335,12 @@ zcode process exits, so a normal shutdown leaves no lingering watchdog.
 
 ### Why a dual path?
 
-| Scenario | Real-time path | Snapshot path |
-|------|---------|----------|
-| Normal streaming | Low latency | Must wait for turn end |
-| Lost events | Loses data | Recovers from snapshot |
-| Deduplication | seenToolIds | seenMessageIds + markToolSeen() |
-| Turn-completion triage | Not triggered | PlanUpdate / usage_update |
+| Scenario               | Real-time path | Snapshot path                   |
+| ---------------------- | -------------- | ------------------------------- |
+| Normal streaming       | Low latency    | Must wait for turn end          |
+| Lost events            | Loses data     | Recovers from snapshot          |
+| Deduplication          | seenToolIds    | seenMessageIds + markToolSeen() |
+| Turn-completion triage | Not triggered  | PlanUpdate / usage_update       |
 
 ### Why no polling fallback?
 

package/docs/BACKLOG.md

@@ -0,0 +1,57 @@
+# Protocol Backlog
+
+Backend RPC methods and event types exposed by the ZCode CLI (`zcode app-server`)
+that are **not yet wired into the bridge**, tracked for potential future support.
+
+Last audited against **app-server 0.15.2** (bundled in ZCode desktop 3.4.2,
+2026-07-22). Method names were extracted from the bundled `zcode.cjs`.
+
+## Candidate methods (optional enhancements)
+
+These are available in the backend but have no ACP-side counterpart yet. Pick
+them up when a concrete ACP/editor need appears.
+
+| Method | Purpose | Current bridge behavior |
+|--------|---------|-------------------------|
+| `session/subagents` | Query the list of sub-agents for a session | Sub-agent info is parsed from the `Agent` tool result (`_meta.subagent`); sufficient for now |
+| `session/events` | Pull-mode event history (complement to `session/subscribe`) | Not used; could support event replay/gap-fill |
+| `session/usage` | Per-session token usage | Context bar uses `session.updated` usage payload instead |
+| `session/close` | Explicitly close a session (vs `session/stop` which ends a turn) | Not used; sessions close on process exit |
+
+### New event types (undocumented in PROTOCOL.md)
+
+| Event | Status field | Notes |
+|-------|--------------|-------|
+| `turn.steerQueued` | — | Emitted when a `session/steer` is queued behind a running turn. Enhances steer UI feedback |
+| `turn.steerDrained` | — | Emitted when queued steer instructions are drained into the turn |
+| `turn.terminal` | `status: success \| interrupted \| failed`, `resultType?`, `durationMs`, `...usage` | Terminal turn lifecycle event; currently the bridge relies on `turn.completed`/`turn.failed` |
+
+## Not planned (client/config layer)
+
+These methods belong to the desktop client or workspace configuration layer and
+have no ACP equivalent. Listed for completeness only — the bridge does not
+intend to surface them.
+
+`automation/create`, `automation/list`, `automation/delete` (scheduled tasks),
+`usage/stats`, `workspace/readState`, `workspace/upsertModelProvider`,
+`workspace/removeModelProvider`, `workspace/updateProviderRegistry`,
+`workspace/setDefaultModel`, `workspace/setDefaultThoughtLevel`,
+`workspace/setDefaultMode`, `workspace/generateText`, `mcp/list`,
+`plugins/list`, `plugins/setEnabled`, `plugins/overview`, `plugins/describe`,
+`plugins/marketplace/*`.
+
+## Verification method
+
+The bundled CLI is minified, so a literal `grep "session/rewind"` returns 0
+hits even when the method is fully supported — method names are split across
+variable references. To audit reliably:
+
+```sh
+cd /Applications/ZCode.app/Contents/Resources/glm
+# Full RPC enum: search for the method-dispatch table (Key:"ns/name" pairs)
+python3 -c "import re; ..."   # see commit that added this file
+# Word-level presence is more reliable for verifying a method still exists:
+grep -oiF "rewind" zcode.cjs | wc -l   # 357 → definitely present
+```
+
+Never conclude a method was removed from a single string-literal search.

package/docs/DEVELOPMENT.md

@@ -117,6 +117,11 @@ cat ~/.zcode/v2/config.json
 # confirm a provider is enabled and has models
 ```
 
+The bridge reads the GLM API key from this file and forwards it to the ZCode
+subprocess — no editor-side API key or environment variable is required. If
+`config.json` is missing or no provider is enabled, install and log into the
+ZCode desktop app so it writes a valid file.
+
 ### Test session/subscribe
 
 ```bash

package/docs/PROTOCOL.md

@@ -78,7 +78,10 @@ Messages are classified by the presence of `id` and `method`:
 
 ### `session/create`
 
-Create a new session.
+Create a new session. Note: the bridge defers this call until a session's
+first use — ACP `session/new` returns a local placeholder id and materializes
+the backend session (this RPC) on the first prompt / config change / extension
+method, so an editor startup that never sends a message leaves no session.
 
 **Request:**
 ```json
@@ -131,6 +134,13 @@ List all sessions.
 
 Resume an existing session.
 
+The sessionId may be a lazy `session/new` placeholder (the editor persists it
+and resumes it after a bridge restart). The bridge resolves it before the
+backend call: an in-memory or persisted (`acp-lazy-sessions.json`) mapping is
+followed to the real backend session — resuming it, or materializing a fresh
+empty one if the placeholder was never used. Real ids from `session/list` pass
+through unchanged.
+
 **Request:**
 ```json
 {
@@ -408,6 +418,53 @@ Session state update (usage, etc.).
 }
 ```
 
+### Steer lifecycle events
+
+When `session/steer` appends instructions to a running turn, the backend emits
+a pair of lifecycle events (available in app-server 0.15.2+). The bridge does
+not currently translate these — they are tracked as a future enhancement (see
+[`BACKLOG.md`](./BACKLOG.md)).
+
+```json
+{
+  "type": "turn.steerQueued",
+  "payload": {}
+}
+```
+
+```json
+{
+  "type": "turn.steerDrained",
+  "payload": {}
+}
+```
+
+### `turn.terminal`
+
+Terminal turn lifecycle event (app-server 0.15.2+). Carries a status plus
+usage. The bridge currently relies on `turn.completed`/`turn.failed` instead;
+documented here for completeness.
+
+```json
+{
+  "method": "session/event",
+  "params": {
+    "sessionId": "sess_abc123",
+    "seq": 49,
+    "type": "turn.terminal",
+    "payload": {
+      "kind": "turn.terminal",
+      "status": "success",
+      "resultType": "end_turn",
+      "durationMs": 12345,
+      "inputTokens": 1234,
+      "outputTokens": 567,
+      "totalTokens": 1801
+    }
+  }
+}
+```
+
 ## Interaction Protocol (Server -> Client)
 
 Requests that zcode actively sends to the bridge.
@@ -505,16 +562,34 @@ mechanisms based on client capabilities:
       "properties": {
         "q_0": {
           "type": "string",
-          "enum": ["auth.test.ts", "user.test.ts"],
-          "title": "Select the files to test"
+          "title": "Select the files to test",
+          "oneOf": [
+            { "const": "auth.test.ts", "title": "auth.test.ts" },
+            { "const": "user.test.ts", "title": "user.test.ts" },
+            { "const": "__skip__", "title": "Skip this question" }
+          ]
+        },
+        "q_0_other": {
+          "type": "string",
+          "title": "↳    or type a custom value (overrides the selection)"
         }
       },
-      "required": ["q_0"]
+      "required": []
     }
   }
 }
 ```
 
+ACP/MCP elicitation string fields are EITHER an enum (restricted dropdown) OR
+free text — the spec forbids a single field that is both. So each question is
+rendered as TWO fields: `q_<i>` (a `oneOf`/`anyOf` enum dropdown of the model's
+suggested answers, with a trailing "Skip this question" option whose `const` is
+the `__skip__` sentinel and whose `title` is the readable label) and
+`q_<i>_other` (a free-text companion). On submit, a non-empty `q_<i>_other`
+overrides the dropdown (single-select) or is appended to the picked values
+(multi-select); selecting "Skip this question" or leaving both blank skips just
+that question without cancelling the form.
+
 **elicitation response** (accept/decline/cancel):
 ```json
 {
@@ -523,6 +598,34 @@ mechanisms based on client capabilities:
 }
 ```
 
+**ExitPlanMode elicitation form** — single `feedback` text field; no
+approve/reject dropdown. The client's own submit button is the approve action;
+typing into the field is the reject action. Submitting with the field empty
+approves the plan; submitting with text rejects it and returns the text to
+zcode as the decline `reason` (so the agent sees the redirection when it
+re-plans). The cancel/decline button is a plain reject with no reason.
+```json
+{
+  "method": "elicitation/create",
+  "params": {
+    "mode": "form",
+    "sessionId": "sess_abc123",
+    "message": "Ready to code?\n\n1. Implement login\n2. Implement signup\n\nLeave the box empty and submit to approve; type feedback to reject and redirect.",
+    "requestedSchema": {
+      "type": "object",
+      "properties": {
+        "feedback": {
+          "type": "string",
+          "title": "Feedback",
+          "description": "Empty = approve the plan. Anything typed = reject and use this text as the redirection."
+        }
+      },
+      "required": []
+    }
+  }
+}
+```
+
 ## Extension Methods (0.14.8+)
 
 ### `session/fork`
@@ -640,10 +743,172 @@ Set the thought level.
 }
 ```
 
-## Version Compatibility
+## Background Tasks & Sub-Agents
+
+When the model dispatches a sub-agent via the `Agent` (or `Task`) tool, the
+backend keeps producing events on the **same session stream** — both while the
+sub-agent runs and after the main turn ends. The bridge forwards a curated
+subset to the ACP client:
+
+### Synchronous sub-agent (blocking)
+
+The `Agent` tool blocks until the sub-agent finishes. Its internal tool calls
+(`Read`, `Bash`, …) arrive as ordinary `tool.updated` events on the main stream
+and are forwarded as regular `tool_call` cards. The `Agent` card itself carries
+structured metadata in `_meta.subagent` (parsed from the result content):
+
+```json
+{
+  "sessionUpdate": "tool_call_update",
+  "toolCallId": "call_xxx",
+  "status": "completed",
+  "_meta": {
+    "claudeCode": { "toolName": "Agent" },
+    "subagent": {
+      "agentId": "agent_73c7c63d-...",
+      "tokens": 40904,
+      "toolUses": 1,
+      "durationMs": 10559
+    }
+  }
+}
+```
+
+### Background sub-agent (`run_in_background: true`)
+
+The `Agent` tool returns immediately with a launch acknowledgement (result
+content contains `agentId` + `output_file` + "working in the background"). The
+main turn then completes, but the backend continues to push the task's
+lifecycle on the same stream:
+
+**1. Status changes** — `session.updated` carries a `taskId` and `status`:
+
+```json
+{
+  "method": "session/event",
+  "params": {
+    "sessionId": "sess_abc123",
+    "seq": 16,
+    "type": "session.updated",
+    "payload": {
+      "taskId": "agent_88a44529-...",
+      "toolCallId": "call_orig",
+      "toolName": "Agent",
+      "status": "running",
+      "description": "Read README first heading",
+      "outputPath": "/.../output.txt",
+      "terminalId": "agent_88a44529-...",
+      "startedAt": "2026-07-18T09:06:45.929Z"
+    }
+  }
+}
+```
+
+The bridge's session-scoped `BackgroundTaskListener` turns these into a
+dedicated ACP tool card (`[background] <description>`) plus status updates:
+
+| Backend event | ACP notification |
+|---|---|
+| first `session.updated` (status `running`) | `tool_call` (new card, `kind:"other"`, `status:"in_progress"`) |
+| `session.updated` (status `completed`) | `tool_call_update` (`status:"completed"`) |
+
+`session.updated` events WITHOUT a `taskId` (e.g. usage updates) are ignored by
+the background listener — they remain owned by the turn loop.
+
+**2. Completion notification turn** — when the background task finishes, the
+backend auto-triggers a new turn whose `turn.started` carries
+`inputSource:"background_task"`:
+
+```json
+{
+  "type": "turn.started",
+  "payload": {
+    "inputSource": "background_task",
+    "inputVisibility": "model-only",
+    "input": "<task-notification>\n  <task-id>agent_...</task-id>\n  <status>completed</status-status>\n  ...\n</task-notification>",
+    "turnId": "turn_95197b25-..."
+  }
+}
+```
+
+The background listener forwards that turn's `model.streaming text_delta` as
+`agent_message_chunk` so the user sees the background result. The per-prompt
+turn loop **defers** this entire turn (drops its events) to avoid double-
+forwarding and to keep it from prematurely ending the user's real turn.
+
+### Background Bash (`run_in_background: true`)
+
+The `Bash` tool launched with `run_in_background: true` returns immediately
+with a launch acknowledgement (result content: "Command running in background
+with ID: exec_…"). Like the Agent sub-agent, the backend keeps pushing the
+task's lifecycle on the same stream via `session.updated` events that carry
+the originating `toolCallId`:
+
+```json
+{
+  "type": "session.updated",
+  "payload": {
+    "taskId": "exec_ac3a5053-...",
+    "toolCallId": "call_e282b4ec...",
+    "toolName": "Bash",
+    "status": "running",
+    "pid": 22410,
+    "outputPath": "/.../call_...-stdout.log",
+    "outputTail": "done\n"
+  }
+}
+```
+
+**Card reuse, not duplication.** Unlike an Agent sub-agent (which mints a fresh
+`bg_*` card), a background Bash task **reuses the launch card** — the very
+terminal card the dispatcher created when `Bash` was scheduled. This keeps the
+lifecycle on a single card instead of producing a duplicate `[background]` card
+that the editor would show alongside the closed launch card.
+
+The mechanism:
+
+1. **Launch turn** — the dispatcher tags the `ToolCallNew`/`ToolCallUpdate`
+   with `background: true` (threaded from the cached `input.run_in_background`
+   flag) and, on the launch `result`, **skips `terminal_exit`** so the launch
+   card stays `in_progress`. It seeds an empty marker in `terminalSentData`
+   for the `toolCallId` — this is the signal the background listener uses to
+   recognise "this is a tracked launch card".
+2. **Lifecycle (`session.updated`)** — the `BackgroundTaskListener` resolves
+   the `toolCallId`, sees it in `terminalSentData`, and routes status updates
+   back to the launch card. On `status:"completed"`, it emits the final
+   `outputTail` via `terminal_output` (iff launch text wasn't already streamed)
+   and closes the terminal UI with `terminal_exit` (exit code 0, or 1 on
+   `failed`), then clears the `terminalSentData` entry.
+3. **Fallback** — if the `session.updated` lacks a `toolCallId`, or the
+   `toolCallId` is unknown to `terminalSentData` (sub-agent case), the listener
+   falls back to minting a fresh `bg_*` card — the Agent sub-agent path above.
+
+| Backend event | ACP notification (background Bash) |
+|---|---|
+| first `session.updated` (status `running`) | `tool_call_update` on the launch card (`status:"in_progress"`) |
+| `session.updated` (status `completed`, with `outputTail`) | `terminal_output` (final output, if not already streamed) + `tool_call_update` with `terminal_exit` (`status:"completed"`) |
+| `session.updated` (status `failed`) | `tool_call_update` with `terminal_exit` (`status:"failed"`, exit_code 1) |
+
+`session/cancelBackgroundTask` for a background Bash task additionally emits
+`terminal_exit` with `_meta.backgroundTask.cancelled = true` so the terminal
+UI closes on cancellation.
+
+### `session/cancelBackgroundTask`
+
+Cancels a background task. The bridge additionally marks the corresponding ACP
+tool card as `failed` with `_meta.backgroundTask.cancelled = true`.
+
+
 
 | ZCode CLI version | session/subscribe | Extension methods | Notes |
 |---------------|-------------------|----------|------|
 | >= 0.15.0 | Supported | All supported | Full functionality |
 | >= 0.14.8 | Supported | Partially supported | workspace/* unavailable |
 | 0.14.5 ~ 0.14.7 | Not supported | Not supported | Incompatible with this project |
+
+## Additional backend methods (not wired into the bridge)
+
+The backend exposes more RPC methods than the bridge uses (sub-agent listing,
+event pull, session usage/close, automation, workspace config, MCP/plugins).
+These have no ACP-side counterpart yet. See [`BACKLOG.md`](./BACKLOG.md) for
+the full list and which are candidates for future support.