pi-background-tasks 2.1.4 → 2.3.0

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.4`
-- 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: 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.
 

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:307`
-- 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:468`
+- 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`
 

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.4",
+  "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,

package/src/core/delegate/launch.ts

@@ -17,6 +17,7 @@ import {
   DELEGATE_TOOL_NAME,
   DelegateError,
   type DelegateCapability,
+  type DelegateExtensionMode,
   type DelegateLimits,
   type DelegatePinnedRoute,
   type DelegateRoute,
@@ -87,7 +88,7 @@ export function resolveDelegateRoute(input: DelegateRouteResolutionInput): Deleg
           childCreated: false,
           remediation: [
             'Name a provider/model pair that appears in the current model registry.',
-            'Omit the route argument to use the parent session\'s current model.',
+            "Omit the route argument to use the parent session's current model.",
           ],
         },
       );
@@ -239,12 +240,23 @@ export function delegateToolsFor(capability: DelegateCapability): readonly strin
   });
 }
 
+function assertDelegateExtensionMode(mode: DelegateExtensionMode): void {
+  if (mode === 'isolated' || mode === 'ambient') return;
+  throw new DelegateError(`bg_delegate extension mode ${String(mode)} is not supported`, {
+    code: 'invalid_arguments',
+    childCreated: false,
+    remediation: ['Use extensionMode "isolated" or "ambient".'],
+  });
+}
+
 export interface DelegateChildArgvInput {
   route: DelegatePinnedRoute;
   capability: DelegateCapability;
+  extensionMode: DelegateExtensionMode;
   childSessionId: string;
   childSessionDir: string;
   childExtensionPath: string;
+  attributionExtensionPath?: string | undefined;
   systemPrompt: string;
 }
 
@@ -252,11 +264,15 @@ export interface DelegateChildArgvInput {
  * Build the child argv.
  *
  * The child gets its own `--session-id` and a task-owned `--session-dir`, so it
- * is structurally incapable of opening or mutating the parent session. Discovery
- * of ambient extensions, skills, prompt templates, themes, and context files is
- * disabled; only the package's own guard extension is loaded explicitly.
+ * is structurally incapable of opening or mutating the parent session. Skills,
+ * prompt templates, themes, and context files are always disabled. Extension
+ * discovery is disabled in isolated mode and deliberately enabled in ambient
+ * mode; ambient extensions execute arbitrary code and are not sandboxed by the
+ * model-visible tool allowlist. The package guard is always explicit; Anthropic
+ * routes first load the package attribution/sanitization extension.
  */
 export function buildDelegateChildArgv(input: DelegateChildArgvInput): string[] {
+  assertDelegateExtensionMode(input.extensionMode);
   const tools = delegateToolsFor(input.capability);
   for (const forbidden of DELEGATE_FORBIDDEN_TOOLS) {
     if (tools.includes(forbidden)) {
@@ -266,6 +282,20 @@ export function buildDelegateChildArgv(input: DelegateChildArgvInput): string[]
       );
     }
   }
+  const extensionPaths =
+    input.route.provider === 'anthropic'
+      ? [
+          input.attributionExtensionPath ??
+            (() => {
+              throw new DelegateError(
+                'Anthropic delegate launch requires the package attribution extension',
+                { code: 'delegate_isolation_unsupported', childCreated: false },
+              );
+            })(),
+          input.childExtensionPath,
+        ]
+      : [input.childExtensionPath];
+
   return [
     '--mode',
     'text',
@@ -279,13 +309,12 @@ export function buildDelegateChildArgv(input: DelegateChildArgvInput): string[]
     tools.join(','),
     '--exclude-tools',
     DELEGATE_FORBIDDEN_TOOLS.join(','),
-    '--no-extensions',
+    ...(input.extensionMode === 'isolated' ? ['--no-extensions'] : []),
     '--no-skills',
     '--no-prompt-templates',
     '--no-themes',
     '--no-context-files',
-    '--extension',
-    input.childExtensionPath,
+    ...extensionPaths.flatMap((path) => ['--extension', path]),
     '--provider',
     input.route.provider,
     '--model',
@@ -362,6 +391,7 @@ export interface DelegatePreflightInput {
   toolCallId: string | undefined;
   prompt: string;
   capability: DelegateCapability;
+  extensionMode: DelegateExtensionMode;
   route: DelegatePinnedRoute;
   limitOverrides: DelegateLimitOverrides;
   hookEvidence: DelegateHookContractEvidence;
@@ -411,10 +441,9 @@ export function buildDelegateChildPrompt(seedSerialized: string, directive: stri
  * one of these can refuse, and none of them has created a process, a session, or
  * an artifact by the time it does.
  */
-export function preflightDelegateLaunch(
-  input: DelegatePreflightInput,
-): DelegatePreflightResult {
+export function preflightDelegateLaunch(input: DelegatePreflightInput): DelegatePreflightResult {
   assertDelegateHookContract(input.hookEvidence);
+  assertDelegateExtensionMode(input.extensionMode);
   // Validates the capability and proves the tool set contains nothing forbidden.
   delegateToolsFor(input.capability);
   const limits = resolveDelegateLimits(input.route, input.limitOverrides);
@@ -427,10 +456,13 @@ export function preflightDelegateLaunch(
     toolCallId: input.toolCallId,
     directive: input.prompt,
     capability: input.capability,
+    extensionMode: input.extensionMode,
     route: input.route,
     limits,
   });
-  const childSystemPrompt = buildDelegateChildSystemPrompt('the task seed in your first user message');
+  const childSystemPrompt = buildDelegateChildSystemPrompt(
+    'the task seed in your first user message',
+  );
   const childPrompt = buildDelegateChildPrompt(seed.serialized, seed.seed.directive.text);
   const plan = planDelegateAdmission({
     route: input.route,
@@ -454,9 +486,7 @@ export function preflightDelegateLaunch(
 }
 
 /** Task-owned child session directory. Never the parent's session directory. */
-export async function ensureDelegateChildSessionDir(
-  artifactDirAbs: string,
-): Promise<string> {
+export async function ensureDelegateChildSessionDir(artifactDirAbs: string): Promise<string> {
   const dir = join(artifactDirAbs, 'child-session');
   await mkdir(dir, { recursive: true, mode: 0o700 });
   return dir;