pi-background-tasks 0.7.7 → 1.0.3

package/docs/commands/bg.md

@@ -0,0 +1,90 @@
+---
+doc_id: commands/bg
+audience: user
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: [command:bg]
+covers_sources: []
+---
+# `/bg`
+
+<!-- pi-docs:begin name="command-contract-bg" generator="scripts/docs/generate.mjs" -->
+| Command | Description | Provenance |
+| --- | --- | --- |
+| `/bg` | Start a shell command as a tracked background task: /bg [--agent] [--name "Task name"] <command> | `src/extension.ts:506` |
+<!-- pi-docs:end name="command-contract-bg" -->
+
+Start a shell command as a tracked background task from the command line.
+
+## Synopsis
+
+
+`/bg [--agent|--llm-agent] [--script|--no-agent] [--name <name>|-n <name>] [--] <command>`
+
+`--name=<name>` and `-n=<name>` are also accepted. Quoted names are parsed by the extension before the remaining bytes become the shell command.
+
+## When to use
+
+Use `/bg` for user-driven long-running commands where you want a footer entry, output file, and display notification, but **not** an automatic agent follow-up turn. For agent-driven launches, prefer [`bg_run`](../tools/bg_run.md) because its default completion delivery wakes the agent.
+
+## Defaults
+
+- `isAgent`: `false`; set `--agent`/`--llm-agent` only when the command launches a Pi/LLM agent whose telemetry should be wrapped.
+- `--script`/`--no-agent`: forces `isAgent:false` after earlier flags.
+- `notifyOnCompletion`: `true`.
+- `triggerOnCompletion`: `false` for `/bg`, so completion is display-only by default.
+- Task name: explicit `--name` if present, otherwise derived from the command.
+
+## Lifecycle
+
+The command returns after the child process is spawned and reports task id, output path, and command. Terminal statuses are exactly `running`, `completed`, `failed`, or `killed`. A finished footer badge remains visible until that task's detail view is opened or [`/bg-clear`](bg-clear.md) marks unseen finished tasks seen.
+
+## Examples
+
+```text
+/bg --name "Docs build" npm run docs
+/bg --agent --name "Child Pi" pi -p "summarize this repo"
+/bg --name="Server" -- npm run dev -- --host 127.0.0.1
+```
+
+## Output/result
+
+Start notification:
+
+```text
+Started <task-name> (<task-id>)
+Output: .pi/tasks/<session>-<pid>/<task-id>.output
+Command: <command>
+```
+
+Completion is delivered as a durable `background-task-notification` custom message when notifications are enabled, but `/bg` sets `triggerOnCompletion:false` so it does not start a provider follow-up turn.
+
+## Errors
+
+- Empty command: `Background command is empty`.
+- Missing or unterminated `--name`: `requires a task name`.
+- Shell/spawn errors fail the task loudly and write failure metadata.
+- Unknown shell policy on Windows can reject the launch before a task is created.
+
+## Runtime artifacts
+
+Outputs and metadata are written under `.pi/tasks/<session-id>-<pid>/` as `<task-id>.output` and `<task-id>.json`. Model-visible log reads are bounded; the full output path is preserved in notices.
+
+## Safety boundaries
+
+Shell commands are **not sandboxed**. They run in the current project cwd through the platform shell selected by the runtime. `/bg` tracks and kills the child process/tree, but does not restrict filesystem, network, or subprocess behavior.
+
+## Related docs
+
+- [`bg_run`](../tools/bg_run.md)
+- [`/jobs`](jobs.md)
+- [`/logs`](logs.md)
+- [`/kill`](kill.md)
+- [`/bg-clear`](bg-clear.md)
+- [Background task runtime](../subsystems/background-task-runtime.md)
+- [Completion delivery](../concepts/completion-delivery.md)
+
+## Source ownership/reference
+
+Surface registration lives in `src/extension.ts`; argument parsing and lifecycle behavior are owned by [background-task-runtime](../subsystems/background-task-runtime.md).

package/docs/commands/fusion-models.md

@@ -0,0 +1,70 @@
+---
+doc_id: commands/fusion-models
+audience: user
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: [command:fusion-models]
+covers_sources: []
+---
+# `/fusion-models`
+
+<!-- pi-docs:begin name="command-contract-fusion-models" generator="scripts/docs/generate.mjs" -->
+| Command | Description | Provenance |
+| --- | --- | --- |
+| `/fusion-models` | Open the five-slot global fusion model selector. | `src/fusion-extension.ts:914` |
+<!-- pi-docs:end name="command-contract-fusion-models" -->
+
+Open the global Fusion model selector.
+
+## Availability
+
+`/fusion-models` is **TUI-only**. RPC, JSON, print, and other non-TUI modes reject it; non-UI command contexts throw an error instead of relying on a no-op notification path.
+
+## Slots
+
+The selector edits exactly five global slots:
+
+1. `Candidate 1`
+2. `Candidate 2`
+3. `Candidate 3`
+4. `Evaluator`
+5. `Merger`
+
+Duplicate model selections are allowed. `$current` is the default for every slot and resolves at run time to Pi's current model; it is available only when a current model exists and is available to child Pi. Slash-containing model ids are stored as `provider/model-id` strings.
+
+## UI behavior
+
+The selector starts from the loaded config or the default all-`$current` config. It lists:
+
+- `$current` first, with the current provider/model in the description when known;
+- currently available registry models sorted by `provider/model`;
+- configured-but-unavailable selections, marked unavailable, so stale configs can still be seen and replaced.
+
+In the five-slot view, arrow keys move, Enter opens the model list, `r` resets the draft to defaults, `s` saves, and Esc or `q` cancels without saving. In the model-choice view, arrow keys move, typed text—including `q`—filters the list, Backspace edits the filter, Enter chooses and returns to the slots, and Esc returns to the slots without changing that slot.
+
+## Persistence and conflicts
+
+The config file is `fusion-models.json` in Pi's agent directory (`fusionModelConfigPath()`). Its schema is closed:
+
+```json
+{
+  "schema_version": "pi-background-tasks.fusion-models.v1",
+  "candidates": ["$current", "$current", "$current"],
+  "evaluator": "$current",
+  "merger": "$current"
+}
+```
+
+Loads reject invalid JSON, unknown keys, wrong schema version, blank selections, surrounding whitespace, unqualified configured selections, and candidate arrays that do not contain exactly three entries.
+
+Saves are durable and revision-safe: the parent captures the file revision hash on load, takes a lock next to the config, verifies the on-disk revision still matches, then atomically replaces the file. If another process changes the file first, the save fails with a config-conflict error shown inside the selector; it does not overwrite concurrent work. Lock acquisition times out loudly after 10 seconds.
+
+## Route admission
+
+At run time every slot is resolved through the available model registry. Frontier routes are accepted only through the Pi subscription OAuth path for `anthropic` or `openai-codex` and only on trusted subscription endpoints. Direct OpenAI/OpenRouter/Azure/frontier API-key routes, endpoint/header overrides of subscription auth, unavailable models, missing current model, and missing positive context windows fail before child creation. There is no fallback, model substitution, or tier bump.
+
+## Related
+
+- Command using the selected routes: [`fusion.md`](fusion.md)
+- Behavioral owner/troubleshooting: [`../subsystems/fusion.md`](../subsystems/fusion.md)

package/docs/commands/fusion.md

@@ -0,0 +1,69 @@
+---
+doc_id: commands/fusion
+audience: user
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: [command:fusion]
+covers_sources: []
+---
+# `/fusion`
+
+<!-- pi-docs:begin name="command-contract-fusion" generator="scripts/docs/generate.mjs" -->
+| Command | Description | Provenance |
+| --- | --- | --- |
+| `/fusion` | Run fixed-purpose Fusion reason (no candidate tools) and append the merged result directly. | `src/fusion-extension.ts:891` |
+<!-- pi-docs:end name="command-contract-fusion" -->
+
+Run the fixed-purpose Fusion **reason** workflow from the command line.
+
+## Synopsis
+
+`/fusion <prompt>`
+
+`/fusion` with no arguments opens Pi's multiline editor in UI-capable modes. If the editor is cancelled or the edited text is blank after trimming, Fusion returns without spawning children.
+
+## Current v1 behavior
+
+`/fusion` is shorthand for `fusion_reason({prompt})`:
+
+- the public workflow is always `reason`;
+- there is no capability or mode argument;
+- candidate children run without tools;
+- evaluator, conditional evaluator-repair, and merger children also run without tools;
+- the request is captured as a versioned visible-conversation projection, not as a raw transcript.
+
+The retired `fusion_brainstorm` public tool is not registered and is removed from active tools on session start. Historical completed v4 result messages can still render, but `/fusion` never reactivates the retired surface.
+
+## Conversation input
+
+Reason/session-projection input uses schema `pi-background-tasks.fusion-input.v5`. The child-facing input contains:
+
+- `request.text` with the exact command prompt;
+- request authority `directive_over_projected_conversation` for the command path;
+- the parent system prompt inside the versioned session-projection context;
+- visible user/assistant text entries preserved verbatim;
+- deterministic omission receipts for assistant thinking, tool calls, and text/image tool results.
+
+Omitted payload bytes are not summarized or previewed for the children. If a fact exists only inside omitted tool output, restate it in the prompt.
+
+## Result delivery
+
+After a successful run, `/fusion` appends two custom messages without asking the parent model to rewrite the answer:
+
+1. a hidden `fusion-request` record for the command request/run id;
+2. a visible `fusion-result` record whose content is the merger's exact text and whose details include run id, artifact directory, model summary, usage/cost, evaluator-attempt count, and budget metadata.
+
+In TUI mode `/fusion` uses a cancellable loader. Cancelling aborts the active child process tree and records a cancelled run when a run directory exists.
+
+## Calls and failure shape
+
+A successful run uses three candidate children, one blind evaluator, and one merger. If the first evaluator response is invalid JSON or violates the closed evaluation schema, Fusion performs exactly one evaluator-repair attempt before failing or continuing. Therefore a successful run may have five or six child invocations; preflight failures launch zero children, and candidate/evaluator/merge failures stop the workflow rather than substituting another model.
+
+Failures are reported as `Fusion failed: ...`; tool/stage errors include the artifact directory when one exists. Prompt-budget forecast failures happen before child creation. Child cancellation, timeout, output caps, model-route admission failures, invalid evaluator JSON after repair, invalid compact child metadata, and invalid tool-call audits are loud failures.
+
+## Related
+
+- Tool equivalent: [`../tools/fusion_reason.md`](../tools/fusion_reason.md)
+- Model selector: [`fusion-models.md`](fusion-models.md)
+- Behavioral owner/troubleshooting: [`../subsystems/fusion.md`](../subsystems/fusion.md)

package/docs/commands/jobs.md

@@ -0,0 +1,74 @@
+---
+doc_id: commands/jobs
+audience: user
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: [command:jobs]
+covers_sources: []
+---
+# `/jobs`
+
+<!-- pi-docs:begin name="command-contract-jobs" generator="scripts/docs/generate.mjs" -->
+| Command | Description | Provenance |
+| --- | --- | --- |
+| `/jobs` | List running and recent background tasks | `src/extension.ts:594` |
+<!-- pi-docs:end name="command-contract-jobs" -->
+
+List running and recent background tasks.
+
+## Synopsis
+
+
+`/jobs`
+
+## When to use
+
+Use `/jobs` for a point-in-time textual snapshot when the interactive task manager is unavailable or unnecessary.
+
+## Defaults
+
+No arguments. It lists all tasks currently retained by this extension runtime: running tasks plus recent finished tasks not pruned from the in-memory registry.
+
+## Lifecycle
+
+Tasks have exactly these statuses: `running`, `completed`, `failed`, `killed`. Finished tasks are kept as recent history up to the runtime's recent-task retention limit; running tasks are preserved when pruning old finished tasks.
+
+## Examples
+
+```text
+/jobs
+```
+
+## Output/result
+
+If no tasks exist:
+
+```text
+No background tasks in this Pi extension runtime.
+```
+
+Otherwise each task line includes status icon, id, status, age, optional exit code, optional pid, task-owned telemetry summaries when reported, display name, optional error, and a following `output: <path>` line.
+
+## Errors
+
+No task-resolution errors; it formats the current registry contents.
+
+## Runtime artifacts
+
+`/jobs` reads in-memory task snapshots. It points at `.pi/tasks/<session-id>-<pid>/<task-id>.output` but does not read output bytes.
+
+## Safety boundaries
+
+Read-only inspection. It does not wait, poll, kill, or modify tasks.
+
+## Related docs
+
+- [`/logs`](logs.md)
+- [`/kill`](kill.md)
+- [`bg_status`](../tools/bg_status.md)
+- [Background task runtime](../subsystems/background-task-runtime.md)
+
+## Source ownership/reference
+
+Surface registration lives in `src/extension.ts`; snapshot formatting is owned by [background-task-runtime](../subsystems/background-task-runtime.md).

package/docs/commands/kill.md

@@ -0,0 +1,82 @@
+---
+doc_id: commands/kill
+audience: user
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: [command:kill]
+covers_sources: []
+---
+# `/kill`
+
+<!-- pi-docs:begin name="command-contract-kill" generator="scripts/docs/generate.mjs" -->
+| Command | Description | Provenance |
+| --- | --- | --- |
+| `/kill` | Stop a running background task: /kill <id> | `src/extension.ts:638` |
+<!-- pi-docs:end name="command-contract-kill" -->
+
+Stop a running background task.
+
+## Synopsis
+
+
+`/kill <task-id-or-prefix>`
+
+## When to use
+
+Use `/kill` when a tracked background task is no longer needed or is hung. Use [`bg_kill`](../tools/bg_kill.md) for the same operation from an agent tool call.
+
+## Defaults
+
+No defaults beyond task id/prefix resolution. Prefixes must be unambiguous.
+
+## Lifecycle
+
+Only `running` tasks can be killed. A successful user kill sets terminal status `killed` and records the task output path. Trying to kill a `completed`, `failed`, or already `killed` task fails loudly.
+
+## Examples
+
+```text
+/kill b12345678
+/kill b1234
+```
+
+## Output/result
+
+```text
+Killed <task-name> (<task-id>). Output: .pi/tasks/.../<task-id>.output
+```
+
+## Errors
+
+- Missing id: `Task ID is required`.
+- Unknown id/prefix: `Unknown background task ID: <id>`.
+- Ambiguous prefix: lists matching task ids.
+- Non-running task: `Task <id> is <status>, not running`.
+- Kill failure: platform-specific loud error.
+
+Errors are shown as `Background kill error: ...`.
+
+## Runtime artifacts
+
+The task's output file and metadata remain in `.pi/tasks/...`. Termination notices and errors may be appended to the output and metadata.
+
+## Safety boundaries
+
+Process termination differs by platform:
+
+- POSIX first targets the detached process group with `SIGTERM`, falls back to the child handle, and escalates to `SIGKILL` after the grace window.
+- Windows uses `taskkill.exe /PID <pid> /T`, then `/F` after the grace window. Force failure is surfaced loudly because descendant processes may have leaked.
+
+Shell commands are not sandboxed; killing controls only tracked process handles/trees.
+
+## Related docs
+
+- [`bg_kill`](../tools/bg_kill.md)
+- [`/jobs`](jobs.md)
+- [`/logs`](logs.md)
+- [Background task runtime](../subsystems/background-task-runtime.md)
+
+## Source ownership/reference
+
+Surface registration lives in `src/extension.ts`; process termination is owned by [background-task-runtime](../subsystems/background-task-runtime.md).

package/docs/commands/logs.md

@@ -0,0 +1,90 @@
+---
+doc_id: commands/logs
+audience: user
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: [command:logs]
+covers_sources: []
+---
+# `/logs`
+
+<!-- pi-docs:begin name="command-contract-logs" generator="scripts/docs/generate.mjs" -->
+| Command | Description | Provenance |
+| --- | --- | --- |
+| `/logs` | Show bounded output from a background task: /logs <id> [maxBytes] | `src/extension.ts:607` |
+<!-- pi-docs:end name="command-contract-logs" -->
+
+Show bounded output from a background task.
+
+## Synopsis
+
+
+`/logs <task-id-or-prefix> [maxBytes]`
+
+Slash-command logs always read the tail.
+
+## When to use
+
+Use `/logs` when you need task output in the host UI. For agent tool calls, use [`bg_logs`](../tools/bg_logs.md) and avoid repeated calls as a waiting loop.
+
+## Defaults
+
+- `maxBytes`: defaults to the model-safe log cap, currently up to 50 KiB.
+- Values are normalized to an integer in `[1, MAX_LOG_BYTES]`; invalid numbers use the default.
+- `tail`: always `true` for `/logs`.
+
+## Lifecycle
+
+`/logs` is a point-in-time read of the output file. It does not subscribe, follow, or poll. Running tasks may produce more output after the read.
+
+## Examples
+
+```text
+/logs b12345678
+/logs b1234 2000
+```
+
+## Output/result
+
+The notification contains output text. If truncated, a notice is prepended for tail reads:
+
+```text
+[Showing tail <bytes-read> of <total>; <omitted> omitted. Full output: .pi/tasks/.../<task-id>.output]
+```
+
+If not truncated, the result ends with:
+
+```text
+[Full output: .pi/tasks/.../<task-id>.output]
+```
+
+The full output path is preserved even when model-visible bytes are bounded.
+
+## Errors
+
+- Missing id: `Task ID is required`.
+- Unknown id/prefix: `Unknown background task ID: <id>`.
+- Ambiguous prefix: lists matching task ids.
+- Missing output file: `Output file does not exist for <id>: <path>`.
+
+Errors are shown as `Background logs error: ...`.
+
+## Runtime artifacts
+
+Reads `.pi/tasks/<session-id>-<pid>/<task-id>.output`; does not modify output or metadata.
+
+## Safety boundaries
+
+Read-only bounded inspection. It is not a polling primitive and should not be used merely to wait for completion.
+
+## Related docs
+
+- [`bg_logs`](../tools/bg_logs.md)
+- [`/jobs`](jobs.md)
+- [`/kill`](kill.md)
+- [Background task runtime](../subsystems/background-task-runtime.md)
+
+## Source ownership/reference
+
+Surface registration lives in `src/extension.ts`; bounded log reading is owned by [background-task-runtime](../subsystems/background-task-runtime.md).

package/docs/commands/task-manager.md

@@ -0,0 +1,109 @@
+---
+doc_id: commands/task-manager
+audience: user
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: [command:bg-tasks, command:tasks]
+covers_sources: []
+---
+# `/tasks` and `/bg-tasks`
+
+<!-- pi-docs:begin name="command-contract-tasks-bg-tasks" generator="scripts/docs/generate.mjs" -->
+| Command | Description | Provenance |
+| --- | --- | --- |
+| `/tasks` | Open the Claude-like background task manager UI | `src/extension.ts:532` |
+| `/bg-tasks` | Open the background task manager UI | `src/extension.ts:540` |
+<!-- pi-docs:end name="command-contract-tasks-bg-tasks" -->
+
+Open the interactive background task manager. `/tasks` and `/bg-tasks` are aliases.
+
+## Synopsis
+
+
+`/tasks [exact-task-id]`
+
+`/bg-tasks [exact-task-id]`
+
+## When to use
+
+Use the task manager when you want the host UI: select tasks, inspect a live output tail, stop one or all running tasks, rerun a task, copy/show an output path, or review recent finished task history.
+
+## Defaults
+
+- No argument opens the list view.
+- An exact task id opens detail view for that task and marks it seen in the footer. Unlike `/logs`, `/kill`, and the task tools, this optional UI argument is not prefix-resolved.
+- If there are no running tasks but finished history exists, the list opens in history mode.
+
+## Lifecycle
+
+The manager is an overlay dock. Opening it sets the footer hint to `focused` and temporarily hides the `/bg-clear` hint; closing returns the footer to the normal `Shift↓` hint. Opening a finished task's detail view marks that task seen. Merely opening the list or closing the dock does **not** clear other finished badges; use [`/bg-clear`](bg-clear.md) to clear them together.
+
+List view sorts tasks as running, failed, killed, then completed; within a status, newest terminal/start time appears first. Status labels shown in the UI are `running`, `error` for `failed`, `stopped` for `killed`, and `done` for `completed`.
+
+## Examples
+
+```text
+/tasks
+/bg-tasks b1234
+```
+
+## Output/result
+
+This command opens UI only. In non-interactive mode, it emits an error notification:
+
+```text
+Background task manager requires an interactive Pi UI. Use /jobs, /logs, or the bg_status/bg_logs tools in non-interactive mode.
+```
+
+## Controls
+
+List view:
+
+- `↑`/`↓`: select.
+- `PgUp`/`PgDn`: page selection.
+- `Enter`/`→`: open output detail.
+- `k`: stop selected running task.
+- `a`, `A`, or `K`: stop all running tasks; press again to confirm.
+- `h`: show/hide history.
+- `R`: rerun selected task with notification enabled and wake disabled.
+- `c`/`C`: show output path.
+- `Esc`, `q`, `Q`, `x`, `X`: close.
+
+Detail view:
+
+- `←`: return to list.
+- `↑`/`↓`/`PgUp`/`PgDn`: scroll output.
+- `r`: refresh and resume following tail.
+- `k`: stop running task.
+- `R`: rerun task.
+- `c`/`C`: show output path.
+- close keys are the same as list view.
+
+## Detail output tail semantics
+
+The detail view reads a UI-only tail buffer of 128 KiB once per second while following. It displays 12 output lines. Scrolling up pauses live following and freezes the buffer so the view stays stable. Scrolling/pageing back to the bottom resumes follow mode; `r` also resumes follow and refreshes. This UI tail is larger than the model-facing log cap and is separate from [`bg_logs`](../tools/bg_logs.md).
+
+## Errors
+
+Stop, stop-all, rerun, and output-read failures are reported inside the dock as action messages. A missing output file appears as `Output file not found: <path>`.
+
+## Runtime artifacts
+
+The manager reads task snapshots and output files from the current extension runtime. It does not reattach to detached historical OS processes after Pi shutdown/reload.
+
+## Safety boundaries
+
+Stopping uses the same runtime kill path as [`/kill`](kill.md) and [`bg_kill`](../tools/bg_kill.md). Shell commands are not sandboxed; the manager only controls tracked tasks.
+
+## Related docs
+
+- [Shortcuts and dock](../reference/shortcuts-and-dock.md)
+- [`/jobs`](jobs.md)
+- [`/logs`](logs.md)
+- [`/kill`](kill.md)
+- [Host UI and telemetry](../subsystems/host-ui-and-telemetry.md)
+
+## Source ownership/reference
+
+Surface registration and dock wiring live in `src/extension.ts`; UI behavior is implemented in `src/ui/background-tasks-manager.ts` and owned by [host-ui-and-telemetry](../subsystems/host-ui-and-telemetry.md).

package/docs/concepts/completion-delivery.md

@@ -0,0 +1,66 @@
+---
+doc_id: concepts/completion-delivery
+audience: agent
+mode: authored
+review_policy: contract
+stability: stable
+covers_surfaces: [renderer:background-task-notification]
+covers_sources: []
+---
+# Completion delivery
+
+Background tasks can finish silently, notify the terminal, or notify and wake the agent. The flags are task-owned.
+
+## Delivery modes
+
+| `notifyOnCompletion` | `triggerOnCompletion` | Actual mode |
+|---|---:|---|
+| `true` | `true` | Durable terminal notification and automatic follow-up turn. Default for [`bg_run`](../tools/bg_run.md). |
+| `true` | `false` | Durable terminal notification only; no provider follow-up. Default for [`/bg`](../commands/bg.md). |
+| `false` | `true` | Manual monitoring; `triggerOnCompletion` has no effect without a notification. |
+| `false` | `false` | Manual monitoring. |
+
+## Critical behavior
+
+- `/bg` is display-only by default: it sets `notifyOnCompletion:true` and `triggerOnCompletion:false`.
+- `bg_run` defaults to durable notification plus follow-up turn: `notifyOnCompletion:true` and `triggerOnCompletion:true`.
+- `bg_status` and `bg_logs` are point-in-time inspection tools, not polling primitives.
+- A received `<background-task-notification>` is metadata-backed terminal-status truth. The output stream has finished/closed, but ordinary `.output` bytes are not explicitly fsynced. Do not call `bg_status` only to reconfirm status; call `bg_logs` only if output bytes are needed.
+
+## Notification payload
+
+When enabled and not during shutdown, terminal completion sends a custom message with:
+
+- `<task-id>`
+- `<task-name>`
+- `<status>` (`completed`, `failed`, or `killed`)
+- optional `<exit-code>`
+- optional `<error>`
+- `<output-file>`
+- `<summary>`
+- `<guidance>` that says terminal state and output metadata are durable and not to reconfirm with `bg_status`.
+
+The structured details contain the task snapshot, including delivery flags and `notified` state.
+
+## Agent guidance
+
+After default `bg_run`, continue only independent useful work. If there is no such work, briefly acknowledge and end the turn; the follow-up notification will wake the agent. Do not sleep, poll `bg_status`, or repeatedly read `bg_logs` merely to wait.
+
+If either completion flag was intentionally disabled, manual inspection is allowed when deliberate, but still avoid tight polling.
+
+## Failures and suppression
+
+If notification send fails, the task resets `notified:false` and logs the error; it does not silently pretend delivery happened. During Pi session shutdown/reload, notifications are suppressed while running tasks are killed.
+
+## Related docs
+
+- [`bg_run`](../tools/bg_run.md)
+- [`bg_status`](../tools/bg_status.md)
+- [`bg_logs`](../tools/bg_logs.md)
+- [`/bg`](../commands/bg.md)
+- [Background task runtime](../subsystems/background-task-runtime.md)
+- [Host UI and telemetry](../subsystems/host-ui-and-telemetry.md)
+
+## Source ownership/reference
+
+Delivery receipt text is derived by runtime helpers and sent by extension registration; primary behavioral ownership is split between [background-task-runtime](../subsystems/background-task-runtime.md) and [host-ui-and-telemetry](../subsystems/host-ui-and-telemetry.md).