pi-background-tasks 0.7.7 → 1.0.3

package/docs/subsystems/fusion.md

@@ -0,0 +1,121 @@
+---
+doc_id: subsystems/fusion
+audience: maintainer
+mode: mixed
+review_policy: behavioral
+stability: stable
+covers_surfaces: [renderer:fusion-result, workflow:investigate, workflow:reason, workflow:research, workflow:validate]
+covers_sources: [extensions/fusion-child.ts, src/core/fusion/artifacts.ts, src/core/fusion/budget.ts, src/core/fusion/child-protocol.ts, src/core/fusion/clean-context.ts, src/core/fusion/config.ts, src/core/fusion/context.ts, src/core/fusion/evaluation.ts, src/core/fusion/orchestrator.ts, src/core/fusion/pi-child.ts, src/core/fusion/prompts.ts, src/core/fusion/source-policy.ts, src/core/fusion/types.ts, src/core/fusion/web-fetch.ts, src/core/fusion/workflows.ts, src/fusion-child-extension.ts, src/fusion-extension.ts, src/ui/fusion-model-selector.ts]
+---
+# Fusion subsystem
+
+<!-- pi-docs:begin name="fusion-workflows" generator="scripts/docs/generate.mjs" -->
+| Workflow | Tool | Context | Candidate capability | Candidate tools | Evaluator/merger tools | Provenance |
+| --- | --- | --- | --- | --- | --- | --- |
+| `investigate` | `fusion_investigate` | `clean_task` | `inspect` | `read`, `grep`, `find`, `ls` | none | `src/core/fusion/workflows.ts:80` |
+| `reason` | `fusion_reason` | `session_projection` | `reason` | none | none | `src/core/fusion/workflows.ts:61` |
+| `research` | `fusion_research` | `clean_task` | `research` | `read`, `grep`, `find`, `ls`, `fusion_web_fetch` | none | `src/core/fusion/workflows.ts:99` |
+| `validate` | `fusion_validate` | `clean_task` | `inspect` | `read`, `grep`, `find`, `ls` | none | `src/core/fusion/workflows.ts:118` |
+<!-- pi-docs:end name="fusion-workflows" -->
+
+This document is the primary behavioral owner for Fusion's package-owned source files listed in frontmatter. Shared parent-context and token-budget modules are referenced here only as dependencies; their behavior is not owned by this document.
+
+## Public v1 surface
+
+Fusion v1 exposes exactly two commands and exactly four public tools:
+
+- `/fusion` — command shorthand for fixed-purpose `reason`.
+- `/fusion-models` — TUI-only global five-slot model selector.
+- `fusion_reason({prompt})`.
+- `fusion_investigate({objective, background, deliverable, scope?, constraints?})`.
+- `fusion_research({objective, background, deliverable, scope?, constraints?, sources})`.
+- `fusion_validate({objective, background, changeSummary, scope, acceptanceCriteria, verification, knownLimitations?, exclusions?})`.
+
+Every public tool schema is closed and has no public capability/mode switch. The retired `fusion_brainstorm` surface is never registered; session start removes it from active tools while preserving rendering of historical completed v4 result messages.
+
+## Commands
+
+`/fusion <prompt>` trims the command text and runs the reason workflow. `/fusion` with no arguments opens the multiline editor when UI is available; editor cancellation or blank edited text returns without child spawn. TUI mode wraps the run in a cancellable loader. Success sends a hidden `fusion-request` custom message and a visible `fusion-result` custom message containing the merger's exact text; the parent model is not asked to rewrite the result.
+
+`/fusion-models` requires TUI mode. It edits five slots (`Candidate 1`, `Candidate 2`, `Candidate 3`, `Evaluator`, `Merger`), allows duplicates, supports `$current`, shows unavailable configured choices, and persists `fusion-models.json` with schema `pi-background-tasks.fusion-models.v1`. Saves are lock-protected, atomic, and revision-safe: if the file changed after load, the selector reports a config conflict instead of overwriting concurrent work.
+
+## Context contracts
+
+Reason runs (`/fusion` and `fusion_reason`) receive session-projection canonical input (`pi-background-tasks.fusion-input.v5`). Visible user/assistant text is retained verbatim. Assistant thinking, tool calls, tool-result text, and tool-result images are not forwarded; they become deterministic omission receipts plus a local `context-omission-ledger.json`. User image blocks become marker text, and ledger-only image payloads never enter child prompts. Tool calls exclude the active Fusion leaf and sibling calls from the projected branch.
+
+Investigate, research, and validate receive clean-task canonical input: exactly `schema_version`, `workflow`, `cwd`, `request`, and `context`. Clean tasks carry no parent system prompt, no conversation projection, no parent transcript, and no omission ledger. Their request text is the canonical JSON serialization of the structured public arguments and is fully authoritative.
+
+## Workflow and stage policy
+
+All workflows use the same orchestrator shape:
+
+1. plan budget and write artifacts before any child exists;
+2. run three candidate children in parallel;
+3. anonymize candidate identities as A/B/C before evaluation;
+4. run a blind no-tool evaluator;
+5. run one no-tool evaluator-repair child only if the first evaluator JSON is invalid or schema-invalid;
+6. run a no-tool merger.
+
+Do not describe Fusion as unconditionally exactly five model calls. A completed run may use five or six child invocations, while preflight failures use zero; candidate failures, cancellation, spawn retry, output caps, or invalid repair alter observed attempts.
+
+Candidate tool policies are fixed by workflow:
+
+| Workflow | Candidate capability | Candidate tools |
+|---|---:|---|
+| reason | `reason` | none (`--no-tools`) |
+| investigate | `inspect` | `read`, `grep`, `find`, `ls` |
+| research | `research` | `read`, `grep`, `find`, `ls`, `fusion_web_fetch` |
+| validate | `inspect` | `read`, `grep`, `find`, `ls` |
+
+Evaluator, evaluator-repair, and merger always use capability `reason` and empty tool lists. Tool-enabled children run with built-in tools disabled and an explicit allowlist plus a denylist that includes shell/write/edit, Fusion recursion, and background/delegate tools.
+
+## Validation specifics
+
+`fusion_validate` enforces a strict public verification contract: `provided` requires non-empty evidence and no reason; `not_run` requires a reason and empty/omitted evidence. Reviewers return closed candidate-report JSON. The host assigns stable finding ids after anonymization, the evaluator must account for every source finding exactly once, and the host renders the final report from validated accounting after the merger. Validation is advisory and read-only: it never edits files, runs tests, gates a release, or replaces builds, linters, scanners, or human review.
+
+## Research specifics
+
+Research is targeted fetch, not search. The public caller declares exact non-duplicate public `http(s)` URLs and purposes. There is no browser, PDF reader, cache, search provider, page-recrawl loop, or domain allowlist.
+
+`fusion_web_fetch` is private to research children and has a closed `{url, extract?}` schema. It rejects credentials, non-http schemes, localhost/known-metadata names, and enumerated private/reserved address classes; vets all DNS answers against that classifier; pins the request to a vetted address; checks the response socket address; follows at most five re-vetted redirects; accepts only HTML/XHTML/plain text/Markdown; caps response bytes at 2 MiB and extracted output at 32 KiB; uses a 60 second deadline; strips script/style/noscript; and extracts text or Markdown. Source-policy admission also rejects literal Azure service address `168.63.129.16`, but the transport classifier does not currently special-case a public DNS/redirect target resolving to that address.
+
+Research intentionally combines read-only file tools and network fetch in one child. This supports source-backed synthesis but is security-sensitive: operators must not supply secret-bearing URLs or ask children to put private data in URL strings. The package blocks common SSRF targets and credential URLs, but its deny rules are not an exhaustive network sandbox; fetched content remains untrusted and caller-declared public URLs can still disclose access through remote logs/timing.
+
+Inspect/research candidates write sealed tool-call audit logs. The log contains schema version, ordinal, tool name, argument/result byte counts and SHA-256 digests, status, duration, and fetch provenance. Raw arguments, raw results, page content, and rejected raw URLs are not persisted. The parent requires the log and seal, verifies hashes/counts/ordinals/status, enforces the 8 MiB aggregate result-byte cap, and rejects non-allowlisted tools.
+
+## Child process isolation
+
+Fusion never calls direct completion APIs. It launches direct child `pi --mode text` processes and writes the prompt over stdin. Child argv includes `--no-session`, `--no-extensions`, `--no-skills`, `--no-prompt-templates`, `--no-themes`, and `--no-context-files`; explicit extensions still load, so the package-owned compact metadata extension is always supplied. Anthropic children additionally receive the `@ravshansbox/pi-anthropic-sps` sanitizer extension because discovery is disabled and Claude routes need Pi system-prompt sanitization.
+
+Child text mode writes the final full answer to stdout. The private child extension emits compact reasoning-free metadata frames to stderr for finalized assistant messages: provider/model, stop reason, text block byte counts and hashes, aggregate text hash, and the complete Pi `Usage` object. The parent reconstructs and validates stdout against the final metadata, requires final stop reason `stop` and non-final stop reason `toolUse`, verifies model identity, and preserves usage/cost exactly.
+
+Fusion child environments strip session/model/provider variables plus metered credential/base-url variables for OpenRouter, OpenAI, Anthropic, Azure OpenAI, and generic Pi API credentials before launch. Frontier model routes are admitted only when the registry reports subscription OAuth for trusted `anthropic` or `openai-codex` endpoints. There is no fallback, model substitution, endpoint override, or metered API-key route.
+
+## Budgets and output contracts
+
+Budget planning is per route and per stage. Every configured candidate, evaluator, and merger route must have a usable context window. The affine estimator from the shared token-budget layer accounts for byte classes plus a 512-token intercept; backed model-family calibrations are used only where applicable, unknown/unbacked providers are reported in artifacts/result details, and multibyte/dense ASCII diagnostics are preserved.
+
+`budget-plan.json` records route capacities, stage forecasts for candidate/evaluation/evaluation-repair/merge, conditional repair reservation, warnings, blockers, empty-request counterfactuals, and remediation. Fatal preflight blockers launch zero children. High utilization or worst-case reservation pressure is a warning when input still fits. Exact rendered prompt checks happen again immediately before candidate, evaluation, repair, and merge launches.
+
+Output contracts are checked after durable attempt recording: candidate responses up to 48 KiB JSON-rendered bytes, evaluator up to 64 KiB, merger/final report up to 64 KiB, diagnostics contract 8 KiB, child stdout cap 32 MiB, child stderr cap 4 MiB. Oversized child output fails loudly and preserves evidence; Fusion never clips or silently forwards truncated content.
+
+## Artifacts, usage, and lifecycle
+
+Run artifacts are private local evidence under `.pi/fusion/<session-id>-<pid>/<run-id>/`. They include `manifest.json`, `canonical-input.json`, `budget-plan.json`, per-attempt prompts/events/stderr/responses, optional partial responses for failed attempts, optional tool-call logs/seals, `blind-candidates.json`, `evaluation.json`, `merged.md`, `error.json`, and workflow-specific context/source-policy artifacts.
+
+Artifact writes use durable private temp-file/fsync/rename. Manifests enforce legal state transitions and record config, resolved models, fixed capabilities, context policy, tool policy, anonymous map, attempts, artifact refs, cumulative usage, and errors. Successful, failed, and cancelled observed attempts preserve complete Pi usage/cost components; public tool results clone the same `Usage` shape.
+
+Cancellation and shutdown are loud and durable when a run store exists. The extension tracks active runs, links external abort signals, aborts on session shutdown/reload, and waits for settlement. Child processes have a 30 minute wall timeout, 20 minute idle watchdog, SIGTERM grace, SIGKILL wait, process-group kill on POSIX, bounded stdout/stderr, and cleanup-error propagation.
+
+## Troubleshooting
+
+- `/fusion-models requires Pi TUI mode`: run from the TUI, not RPC/print/JSON.
+- `$current` unavailable or model unavailable: choose explicit available subscription routes with `/fusion-models`.
+- Frontier/API route rejected: use Pi Anthropic or Codex subscription OAuth, not OpenAI/OpenRouter/Azure/API-key routes.
+- `prompt_budget_exceeded_forecast`: inspect `budget-plan.json`; the error says whether shortening the request can help or whether session history/scope/model context window is the blocker.
+- `prompt_budget_exceeded_measured`: an exact rendered prompt exceeded capacity after upstream output was known; split the workflow or choose a larger-context subscription route.
+- `evaluation schema repair failed`: both evaluator attempts failed the closed JSON contract; inspect `evaluation.attempt-*.response.txt` and errors.
+- `tool-call log invalid`: inspect the candidate `*.tool-calls.jsonl` and `*.seal.json`; missing/partial/unsealed logs, non-allowlisted tools, hash/count mismatches, and over-budget tool output fail by design.
+- Research fetch failures are typed and do not retry via other URLs or extraction modes; verify the declared URL is public, reachable, supported content, and within caps.
+
+Related user docs: [`../commands/fusion.md`](../commands/fusion.md), [`../commands/fusion-models.md`](../commands/fusion-models.md), [`../tools/fusion_reason.md`](../tools/fusion_reason.md), [`../tools/fusion_investigate.md`](../tools/fusion_investigate.md), [`../tools/fusion_research.md`](../tools/fusion_research.md), [`../tools/fusion_validate.md`](../tools/fusion_validate.md).

package/docs/subsystems/host-ui-and-telemetry.md

@@ -0,0 +1,83 @@
+---
+doc_id: subsystems/host-ui-and-telemetry
+audience: maintainer
+mode: authored
+review_policy: behavioral
+stability: stable
+covers_surfaces: []
+covers_sources: [extensions/background-tasks.ts, src/core/update-check.ts, src/extension.ts, src/ui/background-tasks-manager.ts]
+---
+# Host UI and telemetry
+
+This subsystem owns the extension entrypoint, command/tool registration, footer dock, task manager UI, completion renderer, and update-available footer notice. Task lifecycle internals are owned by [background-task-runtime](background-task-runtime.md).
+
+## Entrypoint and registration
+
+`extensions/background-tasks.ts` re-exports `src/extension.ts`. The extension registers:
+
+- commands: `/bg`, `/tasks`, `/bg-tasks`, `/bg-clear`, `/bg-update`, `/jobs`, `/logs`, `/kill`;
+- tools: `bg_run`, `bg_status`, `bg_logs`, `bg_kill` plus package-owned advanced tools documented elsewhere;
+- shortcuts: `shift+down` and `ctrl+alt+c`;
+- renderer: `background-task-notification`.
+
+## Footer status
+
+The footer widget is updated on task changes and once per second while a session is active. If there are no running tasks and no unseen finished tasks, the background-task footer is cleared unless an update segment is available.
+
+When visible, the footer label includes counts in this order:
+
+1. running,
+2. failed,
+3. stopped (`killed`),
+4. done (`completed`),
+5. entry hint (`focused` while the dock is open, otherwise `Shift↓`),
+6. `/bg-clear` hint when there are unseen finished tasks **and the dock is closed**,
+7. optional update segment.
+
+A finished badge is cleared when that task's detail view is opened, or when `/bg-clear` or its shortcut marks all currently unseen finished tasks as seen. Merely opening the list view or closing the dock does not clear badges.
+
+## Task manager UI
+
+`/tasks`, `/bg-tasks`, and `Shift+Down` open the same overlay. Non-interactive contexts receive an error notification directing users to `/jobs`, `/logs`, `bg_status`, or `bg_logs`.
+
+The list view supports selection, paging, stop, confirmed stop-all, history toggle, rerun, output path, and close. The detail view shows task identity, status, runtime, output path, description, task-owned model/context/tokens/tools when reported, command, error, and an output tail.
+
+Detail output semantics:
+
+- reads a UI-only tail buffer of 128 KiB;
+- refreshes every second only while following;
+- shows 12 output lines;
+- scrolling up pauses follow and freezes the buffer;
+- reaching the bottom or pressing `r` resumes follow;
+- missing output files and read failures are displayed in the detail box.
+
+## Completion rendering
+
+`background-task-notification` renders `[bg completed]`, `[bg failed]`, `[bg killed]`, or other status with task name, id, output path, and error. The notification content itself is produced by the runtime and may trigger a follow-up turn depending on task flags.
+
+## Update check
+
+The update check is one-shot per extension runtime, launched after `session_start` without blocking session startup. It is skipped for `PI_BG_DISABLE_UPDATE_CHECK=1`, `PI_OFFLINE=1`, or missing installed version. The npm registry URL defaults to `https://registry.npmjs.org` and can be overridden by `PI_BG_REGISTRY_URL`. Fetch is time-boxed by `DEFAULT_UPDATE_TIMEOUT_MS` (2000 ms) and every network/status/payload failure resolves to no update segment.
+
+When a newer semver is found, the footer segment is `⬆ v<latest> /bg-update`. `/bg-update` prints npm/git install instructions only; it never installs or self-updates.
+
+## Telemetry display
+
+The host UI displays telemetry only from task snapshots: context, model, token totals, and tool counts. When unavailable, detail rows say `not reported by this background task`. The UI never copies telemetry from the parent session into a task.
+
+## Shutdown
+
+On session shutdown, the extension marks the registry as shutting down, clears the status interval, kills running tasks with reason `Killed during Pi session shutdown/reload`, reports cleanup failures through the UI when possible, and closes the event service.
+
+## Related docs
+
+- [Shortcuts and dock](../reference/shortcuts-and-dock.md)
+- [`/tasks` and `/bg-tasks`](../commands/task-manager.md)
+- [`/bg-clear`](../commands/bg-clear.md)
+- [`/bg-update`](../commands/bg-update.md)
+- [Completion delivery](../concepts/completion-delivery.md)
+- [Background task runtime](background-task-runtime.md)
+
+## Source ownership/reference
+
+Primary source ownership for this document is `extensions/background-tasks.ts`, `src/extension.ts`, `src/core/update-check.ts`, and `src/ui/background-tasks-manager.ts`.

package/docs/tools/bg_delegate.md

@@ -0,0 +1,193 @@
+---
+doc_id: tools/bg_delegate
+audience: agent
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: [tool:bg_delegate]
+covers_sources: []
+---
+# `bg_delegate`
+
+<!-- pi-docs:begin name="tool-contract-bg_delegate" generator="scripts/docs/generate.mjs" -->
+- Label: **Background Delegate**
+- Source: `src/delegate-extension.ts:265`
+- Description: Launch one background Pi agent seeded with a frozen projection of the current conversation, then return a launch receipt immediately. The child has its own session, a route pinned at launch that is never substituted, and read-only tools. Retrieve its verified answer with bg_result.
+- Root schema: `object`; additionalProperties: `false`
+
+| Field | Required | Type | Description | Constraints |
+| --- | --- | --- | --- | --- |
+| `autoDeliver` | no | `string` | Whether the completion notification carries the answer: never \| when_small \| always. Default never; retrieve with bg_result. |  |
+| `capability` | no | `string` | Capability profile. Only "inspect" (read/search/list, no shell, no writes, no network, no recursion) is supported. |  |
+| `maxToolCalls` | no | `number` | Maximum tool calls. Default 120. |  |
+| `maxTurns` | no | `number` | Maximum agent turns. Default 24. |  |
+| `name` | yes | `string` | Short human-readable task name shown in the bg footer dock. Use 2-6 words. |  |
+| `notifyOnCompletion` | no | `boolean` | Deliver the durable terminal notification. Default true. |  |
+| `prompt` | yes | `string` | Authoritative instruction for the delegate. The projected conversation is supporting background only. |  |
+| `route` | no | `object` | Explicit route. Defaults to the current model. | additionalProperties: false |
+| `route.model` | yes | `string` | Exact provider-local model id to pin. |  |
+| `route.provider` | yes | `string` | Exact provider name to pin. |  |
+| `timeoutSeconds` | no | `number` | Wall-clock timeout. Default 1200. |  |
+| `triggerOnCompletion` | no | `boolean` | Let that notification start a follow-up turn. Default true. |  |
+
+<details>
+<summary>Normalized TypeBox contract</summary>
+
+
+```json
+{
+  "additionalProperties": false,
+  "properties": {
+    "autoDeliver": {
+      "description": "Whether the completion notification carries the answer: never | when_small | always. Default never; retrieve with bg_result.",
+      "type": "string"
+    },
+    "capability": {
+      "description": "Capability profile. Only \"inspect\" (read/search/list, no shell, no writes, no network, no recursion) is supported.",
+      "type": "string"
+    },
+    "maxToolCalls": {
+      "description": "Maximum tool calls. Default 120.",
+      "type": "number"
+    },
+    "maxTurns": {
+      "description": "Maximum agent turns. Default 24.",
+      "type": "number"
+    },
+    "name": {
+      "description": "Short human-readable task name shown in the bg footer dock. Use 2-6 words.",
+      "type": "string"
+    },
+    "notifyOnCompletion": {
+      "description": "Deliver the durable terminal notification. Default true.",
+      "type": "boolean"
+    },
+    "prompt": {
+      "description": "Authoritative instruction for the delegate. The projected conversation is supporting background only.",
+      "type": "string"
+    },
+    "route": {
+      "additionalProperties": false,
+      "description": "Explicit route. Defaults to the current model.",
+      "properties": {
+        "model": {
+          "description": "Exact provider-local model id to pin.",
+          "type": "string"
+        },
+        "provider": {
+          "description": "Exact provider name to pin.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "model",
+        "provider"
+      ],
+      "type": "object"
+    },
+    "timeoutSeconds": {
+      "description": "Wall-clock timeout. Default 1200.",
+      "type": "number"
+    },
+    "triggerOnCompletion": {
+      "description": "Let that notification start a follow-up turn. Default true.",
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "name",
+    "prompt"
+  ],
+  "type": "object"
+}
+```
+
+</details>
+<!-- pi-docs:end name="tool-contract-bg_delegate" -->
+
+`bg_delegate` launches one background Pi child for one read-only investigation and returns a launch receipt immediately. Retrieve the answer later with [`bg_result`](bg_result.md).
+
+## Public arguments
+
+Required:
+
+- `name: string` — non-empty after trimming. Used for task display.
+- `prompt: string` — non-blank after trimming. The exact string is preserved as `directive.text` and is authoritative.
+
+Optional:
+
+- `route: {provider: string, model: string}` — exact route pin. If omitted, the parent session's current `ctx.model.provider` and `ctx.model.id` are used.
+- `capability: "inspect"` — default `"inspect"`; this is the only v1 capability.
+- `maxTurns: positive integer` — default `24`.
+- `maxToolCalls: positive integer` — default `120`.
+- `timeoutSeconds: positive integer` — default `1200`.
+- `autoDeliver: "never" | "when_small" | "always"` — default `"never"`. Current runtime records and reports this setting in launch/task facts; retrieval remains through `bg_result`. The generic terminal notification path does not currently inline delegate answers.
+- `notifyOnCompletion: boolean` — default `true`.
+- `triggerOnCompletion: boolean` — default `true`; only meaningful when notification is enabled.
+
+The TypeBox schema is closed (`additionalProperties: false`), and preparation validates required/enum/integer fields before launch.
+
+## What the child sees
+
+The child receives a frozen delegate seed built from `visible-conversation-ledger-v2`:
+
+- user text: verbatim;
+- assistant text: verbatim;
+- user images: marker text only, not raw bytes;
+- assistant thinking, tool-call arguments, tool-result text/images: omitted from visible context and recorded in a hash-accounted omission ledger;
+- unknown block types: loud projection failure;
+- the assistant message containing the active `bg_delegate` call is excluded as a whole, so sibling tool calls in that same message are also excluded.
+
+The prompt/directive has explicit authority over projected history. Projected history is supporting, untrusted context. Facts that existed only in omitted parent tool output are not available to the child; restate them in `prompt`.
+
+## Isolation and route guarantees
+
+The child does not share the parent session. Launch argv gives it a random `--session-id` (`delegate-<32 hex>`) and a task-owned `--session-dir` under the delegate artifact directory.
+
+Route resolution is pin-only:
+
+- omitted `route` pins the parent current model;
+- explicit `route` must exactly exist in the current model registry;
+- no unavailable route is substituted;
+- no fallback list or retry-on-other-model exists;
+- routes with no declared context window are refused before child creation;
+- the child records provider/model attestations for assistant messages, and a mismatch prevents a successful result commit.
+
+## Inspect-only tool boundary
+
+The v1 capability is enforced by child argv and Pi's tool registry, not merely by prompt text:
+
+- enabled tools: `read`, `grep`, `find`, `ls`, `delegate_read_artifact`;
+- `--no-builtin-tools` is used with the explicit allowlist;
+- forbidden tools include shell/write/background/delegate/Fusion surfaces (`bash`, `edit`, `write`, `bg_run`, `bg_delegate`, `bg_result`, `bg_run_pi_attested`, Fusion tools, etc.);
+- ambient discovery is disabled with `--no-extensions`, `--no-skills`, `--no-prompt-templates`, `--no-themes`, `--no-context-files`;
+- only the package-owned delegate child extension is loaded explicitly.
+
+There is no shell, edit/write, network tool, recursive delegation, Fusion, or ambient project resource loading in the child tool set.
+
+## Admission, budgets, and artifacts
+
+Public admission resolves the route and package-owned child guard extension before entering `preflightDelegateLaunch()`. Within that preflight, the hook contract is checked before capability/limit/seed/budget admission. Every refusal still occurs before child process, child session directory, or artifact root creation, leaving zero child processes and zero delegate artifacts; callers should not depend on a single absolute error-precedence order across route, guard-extension, and hook checks.
+
+Budgets and limits:
+
+- route capacity is the declared context window minus reserves: `16,384` output, `8,192` framing, `4,096` safety tokens;
+- minimum usable input is `8,192` tokens;
+- launch admission measures the child system prompt plus the exact child prompt bytes that carry the seed;
+- runtime context is measured before each model call;
+- per-tool-result transcript cap: `64 KiB`;
+- aggregate tool-output cap: `64 MiB`;
+- answer capture cap value in the seed: `4 MiB`; current child code carries this limit but does not separately enforce it before packaging;
+- timeout defaults to `1200s`.
+
+Artifacts are under `.pi/delegate/<session-id>-<pid>/<task-id>/` and include `seed.json`, `child-prompt.txt`, `context-omission-ledger.json`, `budget-plan.json`, `manifest.json`, `child-session/`, `spill/`, and later `result.json` / `outcome.json` when produced. Child stdout/stderr are captured through the background task output path; the delegate artifact constants include child stream filenames, but current launch/finalize code does not mirror streams into those delegate files.
+
+## Spilled tool output
+
+Oversized child tool results are written in full to `spill/...` artifacts and replaced in the transcript by receipts carrying path, byte length, SHA-256, tool name, call id, turn sequence, and source call index. The raw oversized payload is not forwarded as a fallback and is not truncated.
+
+Inside the child, `delegate_read_artifact({artifact, offset, length})` reads an exact byte range. It refuses path escape, negative/non-integer offsets, non-positive lengths, and reads past EOF rather than returning a short/clamped range.
+
+## Completion
+
+`bg_delegate` returns a receipt with task id, route, child session id, artifact dir, seed hash/size, budget source, limits, auto-deliver setting, and notification/wake settings. With default notification settings, the parent receives the generic durable `background-task-notification` after terminal state and may then call `bg_result`. Do not poll solely to wait.

package/docs/tools/bg_kill.md

@@ -0,0 +1,114 @@
+---
+doc_id: tools/bg_kill
+audience: agent
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: [tool:bg_kill]
+covers_sources: []
+---
+# `bg_kill`
+
+<!-- pi-docs:begin name="tool-contract-bg_kill" generator="scripts/docs/generate.mjs" -->
+- Label: **Background Kill**
+- Source: `src/extension.ts:897`
+- Description: Stop a running background task by ID. Fails loudly if the task is unknown or already finished.
+- Root schema: `object`
+
+| Field | Required | Type | Description | Constraints |
+| --- | --- | --- | --- | --- |
+| `taskId` | yes | `string` | Task ID or unambiguous prefix to stop |  |
+
+<details>
+<summary>Normalized TypeBox contract</summary>
+
+
+```json
+{
+  "properties": {
+    "taskId": {
+      "description": "Task ID or unambiguous prefix to stop",
+      "type": "string"
+    }
+  },
+  "required": [
+    "taskId"
+  ],
+  "type": "object"
+}
+```
+
+</details>
+<!-- pi-docs:end name="tool-contract-bg_kill" -->
+
+Stop a running background task by id.
+
+## Schema
+
+
+Required fields:
+
+- `taskId: string` — exact task id or unambiguous prefix.
+
+## When to use
+
+Use when the user asks to stop a background task or when a `bg_run` command is no longer needed.
+
+## Defaults
+
+No defaults. The task must be running.
+
+## Lifecycle
+
+A successful kill sets the task terminal status to `killed`. Killing a completed, failed, or already killed task rejects loudly.
+
+## Examples
+
+```json
+{"taskId":"b12345678"}
+```
+
+```json
+{"taskId":"b1234"}
+```
+
+## Output/result
+
+Text result:
+
+```text
+Killed background task <name> (<id>). Output: .pi/tasks/.../<id>.output
+```
+
+Structured details:
+
+```ts
+{ task: BgTaskSnapshot, message: string }
+```
+
+## Errors
+
+- Missing/empty 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`.
+- Platform-specific process termination failures are loud.
+
+## Runtime artifacts
+
+Output and metadata remain under `.pi/tasks/...`. Termination diagnostics may be written into the output file and `error` metadata.
+
+## Safety boundaries
+
+Task control only. POSIX and Windows process-tree semantics differ; Windows force failures report that descendants may have leaked. Shell commands are not sandboxed.
+
+## Related docs
+
+- [`/kill`](../commands/kill.md)
+- [`bg_status`](bg_status.md)
+- [`bg_logs`](bg_logs.md)
+- [Background task runtime](../subsystems/background-task-runtime.md)
+
+## Source ownership/reference
+
+Tool registration lives in `src/extension.ts`; task stopping is owned by [background-task-runtime](../subsystems/background-task-runtime.md).

package/docs/tools/bg_logs.md

@@ -0,0 +1,133 @@
+---
+doc_id: tools/bg_logs
+audience: agent
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: [tool:bg_logs]
+covers_sources: []
+---
+# `bg_logs`
+
+<!-- pi-docs:begin name="tool-contract-bg_logs" generator="scripts/docs/generate.mjs" -->
+- Label: **Background Logs**
+- Source: `src/extension.ts:852`
+- Description: Read bounded output from a background task for deliberate inspection; this is not a waiting primitive. Output is capped at 50.0KB for model safety and points to the full output file when truncated.
+- Root schema: `object`
+
+| Field | Required | Type | Description | Constraints |
+| --- | --- | --- | --- | --- |
+| `maxBytes` | no | `number` | Maximum bytes to return, capped at 50.0KB. Default: 50.0KB. |  |
+| `tail` | no | `boolean` | Read the tail of the log when true, head when false. Default: true. |  |
+| `taskId` | yes | `string` | Task ID or unambiguous prefix |  |
+
+<details>
+<summary>Normalized TypeBox contract</summary>
+
+
+```json
+{
+  "properties": {
+    "maxBytes": {
+      "description": "Maximum bytes to return, capped at 50.0KB. Default: 50.0KB.",
+      "type": "number"
+    },
+    "tail": {
+      "description": "Read the tail of the log when true, head when false. Default: true.",
+      "type": "boolean"
+    },
+    "taskId": {
+      "description": "Task ID or unambiguous prefix",
+      "type": "string"
+    }
+  },
+  "required": [
+    "taskId"
+  ],
+  "type": "object"
+}
+```
+
+</details>
+<!-- pi-docs:end name="tool-contract-bg_logs" -->
+
+Read bounded output from a background task.
+
+## Schema
+
+
+Required fields:
+
+- `taskId: string` — exact task id or unambiguous prefix.
+
+Optional fields:
+
+- `maxBytes: number` — normalized to `[1, MAX_LOG_BYTES]`, with a current cap of up to 50 KiB.
+- `tail: boolean` — `true` reads the tail; `false` reads the head. Default `true`.
+
+## When to use
+
+Use only when output bytes are needed: after a terminal notification and you need details, when the user asks for logs, when automatic completion was disabled, or when diagnosing a concrete hang.
+
+Do **not** repeatedly call `bg_logs` to wait for completion while a notification is pending.
+
+## Defaults
+
+- `maxBytes`: default bounded log size, currently up to 50 KiB.
+- `tail`: `true`.
+
+## Lifecycle
+
+`bg_logs` is a point-in-time file read. Running tasks may append more output later; the tool does not follow or subscribe.
+
+## Examples
+
+```json
+{"taskId":"b12345678"}
+```
+
+```json
+{"taskId":"b1234","maxBytes":4096,"tail":false}
+```
+
+## Output/result
+
+Text content is the selected output slice plus a full-output notice. If truncated:
+
+- tail reads prepend `[Showing tail ... Full output: <path>]`,
+- head reads append `[Showing head ... Full output: <path>]`.
+
+If not truncated, the result appends `[Full output: <path>]`. Structured details:
+
+```ts
+{ task: BgTaskSnapshot, path: string, bytesRead: number, truncated: boolean, tail: boolean }
+```
+
+The `path` is the full output path relative to the task cwd, preserved for opening the complete file.
+
+## Errors
+
+- Missing/empty 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>`.
+
+## Runtime artifacts
+
+Reads `.pi/tasks/<session-id>-<pid>/<task-id>.output`; does not modify output or metadata.
+
+## Safety boundaries
+
+Read-only, bounded, model-safe inspection. It is not a polling primitive. For the larger interactive tail buffer, use the [`/tasks`](../commands/task-manager.md) detail view.
+
+## Related docs
+
+- [`/logs`](../commands/logs.md)
+- [`bg_status`](bg_status.md)
+- [`bg_run`](bg_run.md)
+- [Completion delivery](../concepts/completion-delivery.md)
+- [Background task runtime](../subsystems/background-task-runtime.md)
+
+## Source ownership/reference
+
+Tool registration lives in `src/extension.ts`; bounded log reads are owned by [background-task-runtime](../subsystems/background-task-runtime.md).