pi-background-tasks 2.1.3 → 2.3.0

package/docs/subsystems/attested-pi-runs.md

@@ -40,9 +40,9 @@ The logical argv always begins:
 pi --mode json --provider <provider> --model <model>
 ```
 
-Then optional `--thinking <thinking>`, then literal `extraPiArgs`, then the prompt as the final user prompt argument. Forbidden extra args are direct auth (`--api-key`, `--auth-file`), mode/print (`-p`, `--print`, `--mode`), and duplicate structured fields (`--provider`, `--model`, `--thinking`).
+For an Anthropic request, the package then adds `--extension <package-owned-anthropic-attribution>` before optional thinking. Next come optional `--thinking <thinking>`, literal `extraPiArgs`, and the prompt as the final user prompt argument. Forbidden extra args are direct auth (`--api-key`, `--auth-file`), mode/print (`-p`, `--print`, `--mode`), and duplicate structured fields (`--provider`, `--model`, `--thinking`). Missing attribution bytes refuse an Anthropic launch before task creation.
 
-The registry launches exactly one child through the resolved Pi executable with `shell:false`. The attestation records the stable logical argv (`['pi', ...]`), not platform-specific Windows Node/CLI shims. Attested tasks are created with generic background completion notification/wake disabled; terminal snapshots are still published through the task system.
+The registry launches exactly one child through the resolved Pi executable with `shell:false`. The attestation records the stable logical argv (`['pi', ...]`), including any package-owned attribution extension, not platform-specific Windows Node/CLI shims. Attested tasks are created with generic background completion notification/wake disabled; terminal snapshots are still published through the task system.
 
 ## Auth and environment boundary
 

package/docs/subsystems/child-launch-durability-and-safety.md

@@ -46,9 +46,9 @@ After atomic replace, POSIX-like platforms open and sync the parent directory to
 ## Process trust boundaries
 
 - Background shell tasks run the operator-provided shell command in the project cwd and are not sandboxed.
-- Delegate children are direct `pi` spawns, not shell commands. They use a task-owned session id and session dir, stripped parent session environment, disabled discovery, and an explicit child guard extension.
-- Fusion children are direct `pi --mode text` spawns with private metadata/tool-call audit extensions and workflow-specific tool policy.
-- Attested Pi tasks are direct `pi --mode json` spawns and produce evidence sidecars after successful parsing and durability.
+- Delegate children are direct `pi` spawns, not shell commands. They use a task-owned session id and session dir, stripped parent session environment, disabled discovery, and an explicit child guard extension; Anthropic delegates first load the package attribution extension.
+- Fusion children are direct `pi --mode text` spawns with private metadata/tool-call audit extensions and workflow-specific tool policy; Anthropic children first load the package attribution extension.
+- Attested Pi tasks are direct `pi --mode json` spawns and produce evidence sidecars after successful parsing and durability; Anthropic tasks receive the package attribution extension explicitly.
 
 Never blur parent and child authority: parent tools can start/inspect/kill tasks, but child tools must stay within their explicit argv tool set.
 

package/docs/subsystems/delegation.md

@@ -32,7 +32,7 @@ The design deliberately separates:
 
 ## Seed and context policy
 
-The seed schema is `pi-background-tasks.delegate-seed.v1`. It wraps the frozen `visible-conversation-ledger-v2` projection under delegate policy id `delegate-inspect-v1`; it never emits Fusion input schemas or claims Fusion provenance.
+The seed schema is `pi-background-tasks.delegate-seed.v2`. It wraps the frozen `visible-conversation-ledger-v2` projection under delegate policy id `delegate-inspect-v1`; it never emits Fusion input schemas or claims Fusion provenance. The exact selected `extension_mode` is hash-bound into the seed, and is also recorded in launch details, task facts, and `manifest.json`.
 
 Projection behavior:
 
@@ -62,16 +62,22 @@ The child launch:
 - separate random `--session-id`;
 - task-owned `--session-dir` under the artifact directory;
 - parent session/provider/model/reasoning env keys stripped;
-- only package-owned child guard extension explicitly loaded;
-- ambient extension/skill/template/theme/context discovery disabled.
+- skill/template/theme/context discovery always disabled;
+- extension discovery disabled by default in `extensionMode:"isolated"`;
+- extension discovery deliberately enabled only by `extensionMode:"ambient"`;
+- non-Anthropic children explicitly load the package-owned child guard in both modes;
+- Anthropic children explicitly load package attribution/sanitization first, then the child guard, in both modes.
 
-The only v1 capability is `inspect`. Allowed tools are exactly `read`, `grep`, `find`, `ls`, and `delegate_read_artifact`; forbidden tools deny shell, writes, background task controls, recursive delegation, attested Pi launch, and Fusion. The boundary is argv/tool-registry enforced.
+Ambient mode exists for providers registered by user/project Pi extensions. It omits only `--no-extensions`; it accepts no caller-supplied extension paths and performs no provider fallback or route substitution. Ambient discovery executes arbitrary trusted-location extension code in the child process. That code has Node process privileges and is not sandboxed by Pi's model-visible tool allowlist, so ambient mode deliberately weakens the inspect-only process-isolation guarantee. It must not be described as safe or equivalent to isolated mode.
+
+The only v1 capability is `inspect`. Allowed model-visible tools are exactly `read`, `grep`, `find`, `ls`, and `delegate_read_artifact`; forbidden tools deny shell, writes, background task controls, recursive delegation, attested Pi launch, and Fusion. This tool boundary remains argv/tool-registry enforced in both extension modes, but it is not a sandbox for ambient extension initialization or handlers. Missing Anthropic attribution bytes are a pre-artifact `delegate_isolation_unsupported` refusal; no un-attributed child or alternate route is launched.
 
 ## Route and budget
 
 Routes are pinned once:
 
 - omitted route → parent current model;
+- extension-only routes still must be visible in the parent registry and require explicit `extensionMode:"ambient"` so the fresh child can load their implementing extension;
 - explicit route → exact registry entry;
 - unavailable/unknown-capacity routes fail;
 - no substitution, fallback, or retry on a different route.
@@ -130,6 +136,8 @@ Default delivery inlines answers up to `48 KiB`; larger answers return artifact
 
 Current `autoDeliver` status: `bg_delegate` accepts and records `never | when_small | always` and includes it in launch facts/details. The registry's generic terminal notification currently does not evaluate delegate results or include answer text, so `bg_result` remains the retrieval path.
 
+`extensionMode` accepts only `isolated | ambient`, defaults to `isolated`, and is surfaced in receipt text and durable metadata. Ambient receipts include an explicit arbitrary-code/isolation warning.
+
 ## User-oriented failure taxonomy
 
 Admission / no child:

package/docs/subsystems/docs-freshness-gate.md

@@ -12,14 +12,14 @@ covers_sources: []
 This authored section defines the boundary: documentation facts are extracted from package metadata and TypeScript ASTs, then generated into docs and the manifest. Unsupported syntax fails the gate rather than falling back to regex or stale hand-maintained inventories. Public registrations must remain unconditional top-level direct calls or use the one validated local tool-wrapper shape; host/method aliases, computed access, nested or conditional registration, wrapper chaining/passing, constructor helpers, ambiguous public metadata, destructured Pi parameters, and repeated imported registrars are rejected.
 
 <!-- pi-docs:begin name="docs-freshness-gate" generator="scripts/docs/generate.mjs" -->
-- Canonical package version: `2.1.3`
-- Governed markdown docs: 40
-- Public surfaces extracted: 30
-- Governed production sources: 48
+- Canonical package version: `2.3.0`
+- Governed markdown docs: 42
+- Public surfaces extracted: 31
+- Governed production sources: 50
 - Tool contracts extracted: 11
-- Schema IDs extracted: 43
+- Schema IDs extracted: 44
 - Environment variable references extracted: 49
-- Behavioral attestation receipts not passing: 4
+- Behavioral attestation receipts not passing: 7
 - Receipt store: `docs/attestations.json`
 
 `npm run docs:verify` is read-only: it renders generated files twice in memory and compares them with committed bytes. `npm run docs:generate` is the only docs writer.

package/docs/subsystems/fusion.md

@@ -5,7 +5,7 @@ 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/anthropic-attribution.ts, src/core/fusion/artifacts.ts, src/core/fusion/budget.ts, src/core/fusion/child-protocol.ts, src/core/fusion/claude-cache.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/output-contract.ts, src/core/fusion/pi-child.ts, src/core/fusion/prompts.ts, src/core/fusion/result-package.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]
+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/claude-cache.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/output-contract.ts, src/core/fusion/pi-child.ts, src/core/fusion/prompts.ts, src/core/fusion/result-package.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
@@ -88,7 +88,7 @@ Inspect/research candidates write sealed tool-call audit logs. The log contains
 
 ## 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. Non-Anthropic children receive only the package-owned compact metadata/runtime-governor extension. Anthropic children receive, in fixed order, the package-owned Claude Code attribution provider, `@ravshansbox/pi-anthropic-sps`, and the runtime governor. The repo-local `spawn-anthropic-attribution` entrypoint re-exports that same package-owned implementation, so normal agent spawns and Fusion cannot drift into different OAuth/cache request shapes. Attribution adds the Claude Code OAuth session header, linked account/device/session metadata, model-policy beta headers, system identity, beta-resource transport, cache surfaces, and model-aware cache usage pricing. It reads `userID` and `oauthAccount.accountUuid` from `~/.claude.json` without writing the file and fails loudly when required attribution data is absent or malformed. The sanitizer then removes only known rejected prompt lines while preserving attribution and cache controls.
+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. Non-Anthropic children receive only the package-owned compact metadata/runtime-governor extension. Anthropic children receive, in fixed order, the package-wide attribution/sanitization extension and the runtime governor. The same attribution implementation is globally loaded for ordinary package sessions; Fusion supplies its public extension entrypoint explicitly because ambient discovery is disabled. Attribution adds the Claude Code OAuth session header, linked account/device/session metadata, model-policy beta headers, system identity, beta-resource transport, cache surfaces, and model-aware cache usage pricing. It reads `userID` and `oauthAccount.accountUuid` from `~/.claude.json` without writing the file and fails loudly when required attribution data is absent or malformed. Its internal sanitizer removes all reviewed exact-match rejected prompt lines while preserving unrelated text and cache controls; no external sanitizer package is resolved.
 
 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, the complete Pi `Usage` object (including Anthropic `cacheWrite1h` and provider-reported reasoning subsets), and a closed cache-policy observation. It governs every final `before_provider_request` payload after attribution and sanitization. For Anthropic routes, the child environment defaults `PI_CACHE_RETENTION` to `long` before provider serialization, so the attribution/Pi adapter creates system, final-tool, and final-conversation breakpoints with `ttl: "1h"`; inherited `PI_CACHE_RETENTION=short|none|long` remains explicit, and call-level `cacheRetention="none"` still wins for compaction. The final governor validates and normalizes those upstream-selected breakpoints, falls back to short when model compatibility rejects long retention, preserves no-marker compaction payloads, enforces Anthropic's four-breakpoint ceiling, and appends the subscription prompt-caching-scope beta idempotently. Its `effective_retention` field describes the final payload, not provider acceptance. Provider usage is preserved verbatim: `cacheWrite1h > 0` proves a one-hour write, but zero is inconclusive on subscription OAuth. Live normal-spawn and exact Fusion-child controls each observed a unique cache read after 370 idle seconds despite `cacheWrite1h = 0`; therefore payload observations prove request intent and `cacheRead` proves reuse, while neither zero telemetry nor a six-minute hit alone proves the full one-hour lifetime. Malformed controls or policy values abort before transport. Non-Anthropic payloads and child environments remain unchanged apart from the governor's existing JSON normalization.
 
@@ -110,6 +110,10 @@ When a candidate's first complete `stop` response exceeds 48 KiB, the private ch
 
 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`, manifest-bound `result.json`, `error.json`, and workflow-specific context/source-policy artifacts. `bg_result` verifies manifest state, fixed artifact references, byte lengths, SHA-256 values, UTF-8, run/workflow identity, and result details before returning merged bytes.
 
+Failed and cancelled stored runs additionally write the canonical `pi-background-tasks.fusion-failure-summary.v1` `failure-summary.json` after `error.json` and the terminal manifest transition. The manifest binds that summary's exact basename, byte length, and SHA-256; the summary never hashes `manifest.json`. It is evidence metadata, not an answer: it contains a closed no-answer assertion, bounded terminal-error metadata, durable progress and usage, capped attempt metadata, manifest-bound evidence refs, classifications, remediation identifiers, and explicit omission counts. It contains no candidate/evaluator/merger response text, partial response text, tool-result payload, or fetched content. Completion never writes this artifact.
+
+Summary persistence is subordinate: Fusion writes terminal usage, error evidence, and the failed/cancelled manifest first, then attempts the summary exactly once from a fresh terminal manifest snapshot. A summary-write failure does not retry or suppress terminal publication; the failure channel records one bounded summary-unavailable note. A pre-store refusal has no summary, and an after-store/pre-registration refusal may leave its run directory without inventing a task index.
+
 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, including optional `cacheWrite1h` and `reasoning` subsets; same-session compression includes both provider turns in that one attempt's aggregate; public tool results clone the same `Usage` shape without counting either subset as additional tokens. Terminal failures enrich their stage-local cause from the durable manifest after usage persistence: candidate/evaluator/merger progress reports completed, failed, cancelled, and not-started child facts plus exact usage so far. A late evaluator or merger budget refusal never claims that no child anywhere in the run was created.
 
 For tool-enabled children, the private audit journal remains open across every low-level `agent_end`, because Pi may still retry, compact and retry, or process a queued continuation. Only terminal `agent_settled` can exclusively publish the complete hash/count/byte seal. Runtime-guard refusal latches process failure, makes that seal incomplete, and forces the result settlement to failed. The child emits one closed `pi-background-tasks.fusion-runtime-guard.v2` stderr frame for malformed provider payloads, malformed Claude cache policy, provider-request loops, or tool-call loops. The frame contains the refusal code, route, request/tool ordinals, bounded payload byte/hash evidence where applicable, and a bounded message; it never emits the payload itself. The parent validates this frame and reports typed `child_runtime_limit_exceeded`, `child_runtime_payload_invalid`, or `child_cache_policy_invalid` instead of accepting a later clean-looking result or reducing it to an unexplained exit code. Tool activity after finalization, duplicate settlement, pre-settlement shutdown, extension diagnostics, malformed/duplicate runtime-guard frames, and missing/failed/stale seals are fatal. This lifecycle requires Pi 0.81.1 or newer; older Pi lines do not expose the required terminal event and are not claimed as compatible.

package/docs/tools/bg_delegate.md

@@ -11,14 +11,15 @@ covers_sources: []
 
 <!-- pi-docs:begin name="tool-contract-bg_delegate" generator="scripts/docs/generate.mjs" -->
 - Label: **Background Delegate**
-- Source: `src/delegate-extension.ts:292`
-- 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.
+- Source: `src/delegate-extension.ts:340`
+- 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. Extension discovery is isolated by default; ambient mode supports extension-registered providers but executes arbitrary discovered extension code. 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. |  |
+| `extensionMode` | no | `string` | Extension discovery: isolated \| ambient. Default isolated. Ambient is for extension-registered providers and executes arbitrary discovered extension code, weakening process isolation. |  |
 | `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. |  |
@@ -46,6 +47,10 @@ covers_sources: []
       "description": "Capability profile. Only \"inspect\" (read/search/list, no shell, no writes, no network, no recursion) is supported.",
       "type": "string"
     },
+    "extensionMode": {
+      "description": "Extension discovery: isolated | ambient. Default isolated. Ambient is for extension-registered providers and executes arbitrary discovered extension code, weakening process isolation.",
+      "type": "string"
+    },
     "maxToolCalls": {
       "description": "Maximum tool calls. Default 120.",
       "type": "number"
@@ -118,6 +123,7 @@ 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.
+- `extensionMode: "isolated" | "ambient"` — default `"isolated"`. Use `"ambient"` only when the pinned provider is implemented by an auto-discovered user/project extension. Ambient mode executes arbitrary discovered extension code and weakens process isolation.
 - `maxTurns: positive integer` — default `24`.
 - `maxToolCalls: positive integer` — default `120`.
 - `timeoutSeconds: positive integer` — default `1200`.
@@ -153,21 +159,27 @@ Route resolution is pin-only:
 - 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
+## Inspect-only tool boundary and extension modes
 
-The v1 capability is enforced by child argv and Pi's tool registry, not merely by prompt text:
+The v1 model-visible 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.
+- skills, prompt templates, themes, and context files remain disabled in both extension modes;
+- the package-owned delegate guard is loaded explicitly in both modes; Anthropic routes first load the package attribution/sanitization extension.
+
+`extensionMode:"isolated"` adds `--no-extensions` and is the default. Use it for built-in providers and whenever ambient provider code is unnecessary.
+
+`extensionMode:"ambient"` omits only `--no-extensions`, allowing Pi to discover trusted-location user/project extensions so a fresh child can resolve an extension-registered provider. It does **not** accept extension paths from the tool call, alter the pinned route, or provide fallback/substitution.
+
+Ambient extensions execute arbitrary code in the child process with Node privileges. The read-only tool allowlist constrains tools exposed to the model; it does not sandbox extension initialization or event handlers. Therefore ambient mode weakens the inspect-only process-isolation guarantee even though the model-visible tool registry remains inspect-only.
 
-There is no shell, edit/write, network tool, recursive delegation, Fusion, or ambient project resource loading in the child tool set.
+There is no shell, edit/write, network tool, recursive delegation, or Fusion in the child tool set. That claim applies to registered model tools, not to arbitrary code loaded by ambient extensions.
 
 ## 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.
+Public admission resolves the route, package-owned child guard, and—for Anthropic routes—the package attribution 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:
 
@@ -190,4 +202,4 @@ Inside the child, `delegate_read_artifact({artifact, offset, length})` reads an
 
 ## 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.
+`bg_delegate` returns a receipt with task id, route, child session id, artifact dir, seed hash/size, budget source, extension mode, limits, auto-deliver setting, and notification/wake settings. Ambient receipts include an explicit arbitrary-code/isolation warning. The mode is also hash-bound in `seed.json` and persisted in task facts and `manifest.json`. 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_result.md

@@ -11,7 +11,7 @@ covers_sources: []
 
 <!-- pi-docs:begin name="tool-contract-bg_result" generator="scripts/docs/generate.mjs" -->
 - Label: **Background Result**
-- Source: `src/delegate-extension.ts:453`
+- Source: `src/delegate-extension.ts:515`
 - Description: Retrieve a hash-verified result from a bg_delegate or background Fusion task. Never blocks: a running task returns a typed not-ready result. Oversized answers are never truncated.
 - Root schema: `object`; additionalProperties: `false`
 
@@ -94,6 +94,12 @@ The returned text is decoded from the same aggregate buffer that was hashed. Cor
 
 A completed Fusion task is accepted only when `manifest.json` is terminal `completed`, its `result.json` and `merged.md` fixed references match, both files match manifest-bound byte lengths and SHA-256 values, run/workflow/artifact identity matches the task, result details carry the current schema, usage is complete, and merged bytes are well-formed UTF-8. The first successful retrieval attaches complete Fusion usage exactly once; later retrievals omit usage to prevent double-counting.
 
+## Fusion failed/cancelled terminal view
+
+A failed or cancelled Fusion task returns successfully as an answer-free typed terminal view rather than exposing partial output or throwing a plain failure string. It always has `state:"failed" | "cancelled"`, `delivery:"none"`, and `answer:{present:false,reason:"run_did_not_commit"}`; a requested inline or artifact delivery cannot override this. It includes workflow/artifact location where known, bounded progress/failure/count metadata, and manifest-bound evidence references only. It never includes merged text, partial response text, answer bytes/hash, or delivered-answer usage, and it never claims Fusion usage for these views.
+
+For current runs, `summary_status:"verified"` means `failure-summary.json` was manifest-bound and its exact bytes/hash, UTF-8, closed schema, identity/state, no-answer assertion, and surfaced evidence refs were checked. Referenced stage-output bodies are never read; refs are honestly manifest-bound rather than freshly rehashed. `legacy_manifest_only` describes a validated historical terminal manifest with no summary and never backfills it. `integrity_failed` exposes no summary-derived metadata; `unavailable` exposes no untrusted refs. Failure rendering is bounded to the diagnostics-scale 8 KiB budget by deterministically dropping whole optional rows with exact omission counts, never cutting strings.
+
 ## Inline/artifact delivery and no truncation
 
 `bg_result` never truncates an answer.
@@ -116,6 +122,7 @@ Common delegate retrieval outcomes:
 - `seed_hash_mismatch`, `answer_hash_mismatch`, `child_result_invalid`, `child_result_encoding_invalid` — integrity or encoding failure.
 - `artifact_read_failed`, `artifact_spill_failed`, `artifact_error` — artifact I/O failure.
 - `result_too_large_for_inline` — explicit inline request exceeded the inline cap.
+- Fusion `summary_status:"integrity_failed"` — a terminal summary or its manifest binding failed verification; no summary metadata is trusted.
 
 Delegate errors include whether a child process was created, preserved artifact hints when known, and remediation text. Usage missing from the provider is reported as `unavailable`, not synthesized as zero. Fusion retrieval additionally fails on non-completed manifests, identity/schema drift, malformed usage/details, invalid UTF-8, or any manifest/result/merged hash or byte-length mismatch; failed/cancelled runs return their preserved terminal error rather than partial output.
 

package/docs/tools/bg_run.md

@@ -97,6 +97,8 @@ Legacy argument preparation can derive a missing `name` from `description` or `c
 
 Use for long-running tests, builds, servers, watchers, sleeps, and child agent work. Do not use normal foreground shell tools for commands expected to outlive the current turn.
 
+For an Anthropic child `pi`, keep normal extension discovery enabled. Do not pass `--no-extensions` unless the command also explicitly loads this package's `extensions/anthropic-attribution.ts` with `-e`/`--extension`.
+
 ## Defaults
 
 - `notifyOnCompletion`: `true`.
@@ -154,6 +156,8 @@ Creates `.pi/tasks/<session-id>-<pid>/<task-id>.output` and `.json`. If `isAgent
 
 The command runs through the platform shell and is not sandboxed. Use `isAgent:true` only to request Pi-agent telemetry wrapping; setting it does not make execution safer. Model-visible logs are bounded and point to the full output path.
 
+`bg_run` does not parse or repair arbitrary child `pi` argv. An Anthropic command that uses `--no-extensions` without explicitly loading the attribution extension bypasses the package's attribution/sanitization contract and is unsupported.
+
 ## Related docs
 
 - [Completion delivery](../concepts/completion-delivery.md)
@@ -162,6 +166,7 @@ The command runs through the platform shell and is not sandboxed. Use `isAgent:t
 - [`bg_kill`](bg_kill.md)
 - [`/bg`](../commands/bg.md)
 - [Background task runtime](../subsystems/background-task-runtime.md)
+- [Anthropic attribution](../subsystems/anthropic-attribution.md)
 
 ## Source ownership/reference
 

package/extensions/anthropic-attribution.ts

@@ -0,0 +1 @@
+export { default } from '../src/core/anthropic-attribution.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-background-tasks",
-  "version": "2.1.3",
+  "version": "2.3.0",
   "description": "Pi extension for durable background shell tasks, read-only delegated agents, local attested Pi runs, and fixed-purpose Fusion workflows through child Pi processes.",
   "type": "module",
   "license": "ISC",
@@ -42,6 +42,7 @@
     "TEST_PLAN.md",
     "PUBLISHING.md",
     "LICENSE",
+    "THIRD_PARTY_NOTICES.md",
     "docs/",
     "BACKGROUND-TASKS-INSTRUCTIONS.md",
     "logo.png"
@@ -65,6 +66,7 @@
     "lint": "cd ../.. && npm run quality:ts:lint",
     "format:check": "cd ../.. && npm run quality:ts:format",
     "test:compat": "tsx scripts/test-compat.ts",
+    "test:pnpm-pack": "node scripts/test-pnpm-pack-install.mjs",
     "test:hook-contract": "tsx --test --test-concurrency=1 tests/scripted-provider/pi-hook-contract.test.ts",
     "docs:generate": "node scripts/docs/generate.mjs",
     "docs:verify": "node scripts/docs/verify.mjs",
@@ -79,6 +81,7 @@
   "pi": {
     "image": "https://raw.githubusercontent.com/ismailsaleekh/pi-background-tasks/main/logo.png",
     "extensions": [
+      "./extensions/anthropic-attribution.ts",
       "./extensions/background-tasks.ts"
     ]
   },
@@ -101,7 +104,6 @@
     "node": ">=22.19.0"
   },
   "dependencies": {
-    "@ravshansbox/pi-anthropic-sps": "https://codeload.github.com/ravshansbox/pi-anthropic-sps/tar.gz/17409b5615f0ec0625776bc5434f92f2c55e3fd0",
     "turndown": "7.2.4"
   }
 }

package/src/core/anthropic-attribution-path.ts

@@ -0,0 +1,26 @@
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Resolve the package-owned global Anthropic attribution extension.
+ *
+ * Package-owned child Pi processes disable ambient extension discovery, so they
+ * must explicitly load this public extension entrypoint. Keeping path resolution
+ * in one module prevents Fusion, delegation, and attested runs from deriving
+ * different package paths.
+ */
+export function resolveAnthropicAttributionExtensionPath(
+  moduleUrl = import.meta.url,
+  pathExists: (path: string) => boolean = existsSync,
+): string {
+  const modulePath = fileURLToPath(moduleUrl);
+  const extension = modulePath.endsWith('.ts')
+    ? 'anthropic-attribution.ts'
+    : 'anthropic-attribution.js';
+  const candidate = resolve(dirname(modulePath), '../../extensions', extension);
+  if (!pathExists(candidate)) {
+    throw new Error(`Anthropic attribution extension is missing: ${candidate}`);
+  }
+  return candidate;
+}

package/src/core/{fusion/anthropic-attribution.ts → anthropic-attribution.ts}

@@ -64,13 +64,17 @@ const AUDIT_ENV = 'PIPELINE_ANTHROPIC_ATTRIBUTION_AUDIT_PATH';
 const CACHE_RETENTION_ENV = 'PI_CACHE_RETENTION';
 export const ANTHROPIC_CACHE_RETENTION_ENTRY = 'pipeline-anthropic-cache-retention';
 const ANTHROPIC_CACHE_RETENTION_SCHEMA = 'pipeline.anthropic_cache_retention.v1';
+export const ANTHROPIC_ATTRIBUTION_CLAIM_CHANNEL = 'pi-anthropic-attribution:claim:v1';
+const ANTHROPIC_ATTRIBUTION_CLAIM_SCHEMA = 'pi-anthropic-attribution.claim.v1';
 const NATIVE_ATTESTATION_PLACEHOLDER = '00000';
 const ANTHROPIC_CACHE_CONTROL_BREAKPOINT_LIMIT = 4;
 
-// Source: ravshansbox/pi-anthropic-sps. Keep exact-match semantics so the
-// repo-local attribution shim is idempotent with the global sanitizer.
+// Sanitization behavior derived from the MIT-licensed ravshansbox/pi-anthropic-sps
+// extension at commit 17409b5615f0ec0625776bc5434f92f2c55e3fd0. Keep exact-match
+// semantics and all known Pi prompt variants; unrelated system text is preserved.
 const ANTHROPIC_SYSTEM_PROMPT_BAD_LINES = new Set([
   '- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md)',
+  '- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md), environment variables (docs/environment-variables.md)',
   '- When working on pi topics, read the docs and examples, and follow .md cross-references before implementing',
 ]);
 
@@ -329,7 +333,13 @@ interface PiCommandConfigLike {
   readonly handler: (args: string, ctx: PiContextLike) => Promise<void> | void;
 }
 
+interface PiEventBusLike {
+  emit(channel: string, data: unknown): void;
+  on(channel: string, handler: (data: unknown) => void): () => void;
+}
+
 export interface PiExtensionHost extends PiProviderRegistrationHost {
+  readonly events: PiEventBusLike;
   on(
     eventName: 'session_start' | 'session_shutdown' | 'session_tree' | 'before_agent_start',
     handler: (event: unknown, ctx: PiContextLike) => void,
@@ -1867,11 +1877,54 @@ function cacheRetentionLabel(retention: CacheRetention): string {
   }
 }
 
+interface AnthropicAttributionClaimProbe {
+  readonly schema_version: typeof ANTHROPIC_ATTRIBUTION_CLAIM_SCHEMA;
+  readonly acknowledge: () => void;
+}
+
+function isAnthropicAttributionClaimProbe(value: unknown): value is AnthropicAttributionClaimProbe {
+  return (
+    isPlainObject(value) &&
+    value['schema_version'] === ANTHROPIC_ATTRIBUTION_CLAIM_SCHEMA &&
+    typeof value['acknowledge'] === 'function'
+  );
+}
+
+/**
+ * Prevent two independently installed copies from registering duplicate provider
+ * hooks and `/claude-cache` commands in one Pi runtime. Pi loads extension factories
+ * sequentially and its EventBus dispatches listeners synchronously, so an existing
+ * owner acknowledges this probe before emit() returns. The winning extension only
+ * publishes ownership after every registration below succeeds; a factory that throws
+ * cannot strand a false claim that suppresses a healthy later copy.
+ */
 export default function spawnAnthropicAttribution(pi: PiExtensionHost): void {
+  const acknowledgements: true[] = [];
+  const probe: AnthropicAttributionClaimProbe = {
+    schema_version: ANTHROPIC_ATTRIBUTION_CLAIM_SCHEMA,
+    acknowledge: () => {
+      acknowledgements.push(true);
+    },
+  };
+  pi.events.emit(ANTHROPIC_ATTRIBUTION_CLAIM_CHANNEL, probe);
+  if (acknowledgements.length > 0) return;
+
   let sessionCacheRetention: Exclude<CacheRetention, 'none'> | undefined;
   const getSessionOverride = (): Exclude<CacheRetention, 'none'> | undefined =>
     sessionCacheRetention;
 
+  // Registration is global but route-scoped by provider name. Keeping it at
+  // factory scope avoids lifecycle-dependent provider availability; the custom
+  // transport derives session/model headers from the attributed payload.
+  pi.registerProvider('anthropic', {
+    api: 'anthropic-messages',
+    streamSimple: (model, context, options) =>
+      streamAnthropicViaBetaMessages(model, context, {
+        ...(options ?? {}),
+        cacheRetention: resolveCacheRetentionPreference(options, getSessionOverride()),
+      }),
+  });
+
   pi.registerCommand('claude-cache', {
     description: 'Show or set Claude cache retention for this session (short, long, default)',
     handler: (args, ctx) => {
@@ -1902,7 +1955,6 @@ export default function spawnAnthropicAttribution(pi: PiExtensionHost): void {
 
   pi.on('session_start', (_event, ctx) => {
     sessionCacheRetention = restoreAnthropicSessionCacheRetention(ctx.sessionManager.getBranch());
-    registerAnthropicAttributionProvider(pi, ctx, getSessionOverride);
   });
 
   pi.on('session_shutdown', () => {
@@ -1913,13 +1965,8 @@ export default function spawnAnthropicAttribution(pi: PiExtensionHost): void {
     sessionCacheRetention = restoreAnthropicSessionCacheRetention(ctx.sessionManager.getBranch());
   });
 
-  pi.on('before_agent_start', (_event, ctx) => {
-    registerAnthropicAttributionProvider(pi, ctx, getSessionOverride);
-  });
-
   pi.on('before_provider_request', (event, ctx) => {
     if (!isAnthropicContext(ctx)) return undefined;
-    registerAnthropicAttributionProvider(pi, ctx, getSessionOverride);
     return rewriteAnthropicRequestPayload({
       payload: event.payload,
       ctx,
@@ -1927,4 +1974,10 @@ export default function spawnAnthropicAttribution(pi: PiExtensionHost): void {
       headerRegistered: true,
     });
   });
+
+  // Publish ownership last. Extension loading is sequential, so later independent
+  // copies probe this responder and become inert instead of registering duplicates.
+  pi.events.on(ANTHROPIC_ATTRIBUTION_CLAIM_CHANNEL, (value) => {
+    if (isAnthropicAttributionClaimProbe(value)) value.acknowledge();
+  });
 }

package/src/core/attested-pi-run.ts

@@ -150,9 +150,18 @@ export function attestedPiChildEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
   return out;
 }
 
-export function buildAttestedPiArgv(input: StructuredPiLaunchRequest): string[] {
+export function buildAttestedPiArgv(
+  input: StructuredPiLaunchRequest,
+  attributionExtensionPath?: string,
+): string[] {
   validateStructuredPiLaunchRequest(input);
   const args = ['pi', '--mode', 'json', '--provider', input.provider, '--model', input.model];
+  if (input.provider === 'anthropic') {
+    if (!attributionExtensionPath?.trim()) {
+      throw new Error('Anthropic attested Pi tasks require the package attribution extension');
+    }
+    args.push('--extension', attributionExtensionPath);
+  }
   if (input.thinking?.trim()) args.push('--thinking', input.thinking.trim());
   args.push(...(input.extraPiArgs ?? []), input.prompt);
   return args;

package/src/core/common.ts

@@ -3,7 +3,7 @@ import { open } from 'node:fs/promises';
 import { extname, isAbsolute, join, win32 } from 'node:path';
 import { DEFAULT_MAX_BYTES } from '@earendil-works/pi-coding-agent';
 import type { BackgroundTaskChildProcess } from './registry.js';
-import type { DelegateBudgetRouteSource } from './delegate/types.js';
+import type { DelegateBudgetRouteSource, DelegateExtensionMode } from './delegate/types.js';
 import type { FusionResultDetails, FusionUsage, FusionWorkflowId } from './fusion/types.js';
 
 export const TASK_STATUS_VALUES = ['running', 'completed', 'failed', 'killed'] as const;
@@ -87,6 +87,7 @@ export interface DelegateTaskFacts {
   childSessionId: string;
   route: { provider: string; model: string; qualifiedId: string };
   budget: DelegateBudgetRouteSource;
+  extensionMode: DelegateExtensionMode;
   autoDeliver: 'never' | 'when_small' | 'always';
   /** Set once the run reaches a terminal state and its result has been evaluated. */
   outcome?: DelegateTaskOutcome | undefined;

package/src/core/delegate/artifacts.ts

@@ -8,6 +8,7 @@ import {
   DELEGATE_MANIFEST_SCHEMA_VERSION,
   DELEGATE_RECEIPT_SCHEMA_VERSION,
   DelegateError,
+  type DelegateExtensionMode,
   type DelegateLimits,
   type DelegatePinnedRoute,
   type DelegateSpillReceipt,
@@ -67,6 +68,7 @@ export interface DelegateManifestV1 {
   cwd: string;
   child_session_id: string;
   child_session_dir: string;
+  extension_mode: DelegateExtensionMode;
   route: DelegatePinnedRoute;
   limits: DelegateLimits;
   seed_sha256: string;
@@ -111,6 +113,7 @@ export interface CreateDelegateArtifactStoreOptions {
   sessionId?: string | undefined;
   childSessionId: string;
   childSessionDir: string;
+  extensionMode: DelegateExtensionMode;
   route: DelegatePinnedRoute;
   limits: DelegateLimits;
   seedSha256: string;
@@ -175,6 +178,7 @@ export class DelegateArtifactStore {
       cwd: options.cwd,
       child_session_id: options.childSessionId,
       child_session_dir: options.childSessionDir,
+      extension_mode: options.extensionMode,
       route: options.route,
       limits: options.limits,
       seed_sha256: options.seedSha256,