fix(runtime): contain detached background agent failures

README.md

@@ -117,8 +117,9 @@ Mermaid previews with source fallback for unsupported or oversized diagrams.
 **Inspection and navigation.** `/diff` browser for current Git changes and
 per-turn file changes; `/context` prompt-composition, cache and context-usage
 details; `/status` session, runtime, goal, MCP and workspace details;
-`/activity` and `/tasks` for active tools and background tasks; searchable
-transcript navigation with per-block expansion, selected-block copying and
+`/activity` and a task center for background status, output, agent conversations
+and recovery; searchable transcript navigation with per-block expansion,
+selected-block copying and
 `n`/`N` match traversal; persistent active-tool, background-task and open-plan
 activity between the transcript and editor.
 
@@ -246,14 +247,34 @@ picker to return to input selection, then `Esc` again to close rewind.
 /context                      inspect context usage and source composition
 /status                       inspect detailed runtime and session status
 /activity                     inspect every active tool and open task
-/tasks                        inspect or stop background tasks
+/tasks                        inspect and manage background tasks
+/tasks message <id> <text>    send guidance to a running background agent
+/tasks resume <id> [text]     resume a stopped or failed background agent
+/tasks stop <id>              stop a running background task
 /search <text>                search retained transcript blocks
 /search next|prev|clear       navigate or close transcript search
 /transcript latest            select the latest transcript block
 /transcript next|prev|close   navigate or leave transcript selection
 /copy                         copy the selected block, or the latest response
 ```
 
+The task center keeps autonomous task output out of the foreground transcript.
+The main conversation receives only compact completion, reply and failure
+notices; select the task to inspect its output and task-scoped activity. Agent
+tasks can receive messages while running, and the official runtime resumes a
+terminal agent from its saved child session when messaged. Bash tasks expose a
+reviewable rerun request because a stopped process cannot continue from an
+execution checkpoint. Saved final task output remains available after a TUI
+restart, with large files limited to their latest 64 KiB. Workflow tasks open
+their existing run panel and controls.
+
+Agent calls that finish within one second remain ordinary foreground tools so
+their result can feed the current response directly. Longer Agent calls move to
+the task center automatically, releasing the foreground turn while they keep
+running. Set `subagents.autoBackgroundMs` to a different positive duration, or
+to `0` to disable automatic backgrounding. An explicit
+`run_in_background: true` still backgrounds an Agent immediately.
+
 While the editor is empty, `Alt+Up` and `Alt+Down` navigate selected transcript
 blocks. `Ctrl+O` expands only the selected/search-matched block; without a
 selection it toggles all expandable content. During transcript search, `n` and

config.example.json

@@ -50,6 +50,9 @@
     "skill": true,
     "mcp": true
   },
+  "subagents": {
+    "autoBackgroundMs": 1000
+  },
   "memory": {
     "use": true,
     "write": true,

docs/CONFIGURATION.md

@@ -168,6 +168,24 @@ Project-level overrides are read from `zcode.json` or `.zcode/config.json` in
 the working directory. Running `/model` does not call the provider, so it is a
 safe configuration check before the first prompt.
 
+### Background agents
+
+Long-running Agent calls automatically detach from the foreground turn after
+one second and remain available through `/tasks`. Short Agent calls stay inline
+so the current response can use their result without a notification round trip.
+Configure the threshold in milliseconds:
+
+```json
+{
+  "subagents": {
+    "autoBackgroundMs": 1000
+  }
+}
+```
+
+Set the value to `0` to disable automatic backgrounding. Agent tool calls that
+use `run_in_background: true` detach immediately regardless of this threshold.
+
 ### Request retries and stalled streams
 
 The CLI leaves retry classification and execution to the official ZCode
@@ -193,6 +211,20 @@ older generated file still contains `600000`. Retryable timeouts, dropped
 streams, rate limits and server/network errors are retried and shown in the
 TUI. Authentication and invalid-request responses remain non-retryable.
 
+## Runtime diagnostics
+
+The interactive TUI captures runtime `stderr` so background diagnostics cannot
+overwrite terminal rendering. A non-zero runtime exit prints its status and the
+diagnostic path after the TUI stops. The active log is capped at 2 MB and rotated
+to `.1` on the next launch; both files use owner-only permissions.
+
+The default path is `~/.zcode/cli/tui-runtime.log`. Override it when collecting
+diagnostics in an isolated environment:
+
+```bash
+ZCODE_TUI_RUNTIME_LOG=/tmp/zcode-tui-runtime.log zcode
+```
+
 ## Theme
 
 Set `ui.theme` to `"auto"` (terminal detection), `"dark"`, or `"light"` in the

docs/DEVELOPMENT.md

@@ -40,7 +40,8 @@ config output, executes `/help`, switches to plan mode, exits, and checks that
 the launcher forwards terminal SIGHUP shutdown. The offline
 feature scenario also covers suspended login restoration, selectors, image
 attachments, nested Agent tools, Markdown, Mermaid, diffs, transcript
-navigation, context/status details, MCP actions, background tasks and the
+navigation, context/status details, MCP actions, task-scoped background output,
+terminal-agent recovery and the
 workflow panel. A pressure scenario verifies that steering, UTF-8 input and
 Ctrl+C cancellation remain responsive during rapid Bash progress output. The
 scenarios advance from observed terminal output instead of fixed timers and do