pi-background-tasks 2.1.4 → 2.3.0

package/docs/manifest.json

@@ -27,16 +27,27 @@
       "state": "pass"
     },
     {
-      "authored_body_sha256": "sha256:4d3d0ba1534c8ea5368e201fbf8fc7d52f2fbb353262d4af1ead263548547356",
+      "authored_body_sha256": "sha256:72c53dcc104f9b5efa57e38bcb21a4c3c620d5caf1571af82348f94dcafbe941",
+      "covers_sources": [
+        "extensions/anthropic-attribution.ts",
+        "src/core/anthropic-attribution-path.ts",
+        "src/core/anthropic-attribution.ts"
+      ],
+      "doc_id": "subsystems/anthropic-attribution",
+      "rel": "docs/subsystems/anthropic-attribution.md",
+      "required": true,
+      "state": "missing"
+    },
+    {
+      "authored_body_sha256": "sha256:0840d793b8c18869f9a3bb8a72beeb602824ed1a580161f3456126af8af9b459",
       "covers_sources": [
         "src/core/attested-pi-run.ts"
       ],
       "doc_id": "subsystems/attested-pi-runs",
-      "notes": "Reviewed attested Pi event parsing, last-reported stopReason semantics, OAuth route observation, argv/environment safeguards, git authority, hashes, failure handling, and atomic sidecar durability.",
       "rel": "docs/subsystems/attested-pi-runs.md",
       "required": true,
       "reviewer": "gpt-5.5-final-attested-safety-reviewer",
-      "state": "pass"
+      "state": "stale-authored-prose"
     },
     {
       "authored_body_sha256": "sha256:253948c8b1f4dd339b0c1eeabd6e8addf584fe208a0f71c3a7f094921ff4547f",
@@ -52,20 +63,19 @@
       "state": "stale-authored-prose"
     },
     {
-      "authored_body_sha256": "sha256:d5a27cd6a1f78820fe6a39996f8c64c5924efaf2dba99ea44415c1e770dc45bb",
+      "authored_body_sha256": "sha256:40ee5dac92b9e873d6a9f71a59c03ff1ccd44d6717a13d3be18f74b19e68326e",
       "covers_sources": [
         "src/core/durable-fs.ts",
         "src/core/pi-launch.ts"
       ],
       "doc_id": "subsystems/child-launch-durability-and-safety",
-      "notes": "Reviewed durable file replacement and child launch sources, including file fsync, POSIX directory sync, Windows limitation, ordinary versus attested output wording, and loud launch/durability failures.",
       "rel": "docs/subsystems/child-launch-durability-and-safety.md",
       "required": true,
       "reviewer": "gpt-5.5-final-attested-safety-reviewer",
-      "state": "pass"
+      "state": "stale-authored-prose"
     },
     {
-      "authored_body_sha256": "sha256:60b6235d33b9c7df1b1494c0c071862aee059074ce58058c103f9a71d5d9e7d8",
+      "authored_body_sha256": "sha256:bc319ce7e62d2592c71476f950947c8ff011fb74e7f2093b0169f77d59980f18",
       "covers_sources": [
         "extensions/delegate-child.ts",
         "src/core/delegate/artifacts.ts",
@@ -87,10 +97,9 @@
       "state": "stale-authored-prose"
     },
     {
-      "authored_body_sha256": "sha256:e7cbe5b10fd56a28e6d23511db5500ee05b000be507fd50ac035d9757e0e2083",
+      "authored_body_sha256": "sha256:b6238bacecf46139dab1d6a8622783db76d913f0ce727205151b65b7cb210481",
       "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",
@@ -198,6 +207,17 @@
       "review_policy": "contract",
       "stability": "stable"
     },
+    "commands/claude-cache": {
+      "audience": "user",
+      "covers_sources": [],
+      "covers_surfaces": [
+        "command:claude-cache"
+      ],
+      "mode": "mixed",
+      "rel": "docs/commands/claude-cache.md",
+      "review_policy": "contract",
+      "stability": "evolving"
+    },
     "commands/fusion": {
       "audience": "user",
       "covers_sources": [],
@@ -364,6 +384,19 @@
       "review_policy": "contract",
       "stability": "stable"
     },
+    "subsystems/anthropic-attribution": {
+      "audience": "maintainer",
+      "covers_sources": [
+        "extensions/anthropic-attribution.ts",
+        "src/core/anthropic-attribution-path.ts",
+        "src/core/anthropic-attribution.ts"
+      ],
+      "covers_surfaces": [],
+      "mode": "authored",
+      "rel": "docs/subsystems/anthropic-attribution.md",
+      "review_policy": "behavioral",
+      "stability": "evolving"
+    },
     "subsystems/attested-pi-runs": {
       "audience": "maintainer",
       "covers_sources": [
@@ -435,7 +468,6 @@
       "audience": "maintainer",
       "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",
@@ -624,6 +656,12 @@
       "name": "command-contract-bg-update",
       "rel": "docs/commands/bg-update.md"
     },
+    {
+      "doc_id": "commands/claude-cache",
+      "generator": "scripts/docs/generate.mjs",
+      "name": "command-contract-claude-cache",
+      "rel": "docs/commands/claude-cache.md"
+    },
     {
       "doc_id": "commands/fusion",
       "generator": "scripts/docs/generate.mjs",
@@ -775,7 +813,10 @@
     "engines": {
       "node": ">=22.19.0"
     },
-    "entrypoint": "./extensions/background-tasks.ts",
+    "entrypoints": [
+      "./extensions/anthropic-attribution.ts",
+      "./extensions/background-tasks.ts"
+    ],
     "files": [
       "BACKGROUND-TASKS-INSTRUCTIONS.md",
       "LICENSE",
@@ -783,6 +824,7 @@
       "README.md",
       "TESTING.md",
       "TEST_PLAN.md",
+      "THIRD_PARTY_NOTICES.md",
       "docs/",
       "extensions/",
       "logo.png",
@@ -791,13 +833,14 @@
     "image": "https://raw.githubusercontent.com/ismailsaleekh/pi-background-tasks/main/logo.png",
     "name": "pi-background-tasks",
     "type": "module",
-    "version": "2.1.4"
+    "version": "2.3.0"
   },
   "public_surface_ids": [
     "command:bg",
     "command:bg-clear",
     "command:bg-tasks",
     "command:bg-update",
+    "command:claude-cache",
     "command:fusion",
     "command:fusion-models",
     "command:jobs",
@@ -855,6 +898,13 @@
         "name": "bg-update",
         "source": "src/extension.ts:567"
       },
+      {
+        "description": "Show or set Claude cache retention for this session (short, long, default)",
+        "id": "command:claude-cache",
+        "kind": "command",
+        "name": "claude-cache",
+        "source": "src/core/anthropic-attribution.ts:1928"
+      },
       {
         "description": "Start fixed-purpose Fusion reason in the background and return immediately.",
         "id": "command:fusion",
@@ -950,7 +1000,7 @@
     ],
     "tool": [
       {
-        "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.",
+        "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.",
         "id": "tool:bg_delegate",
         "kind": "tool",
         "label": "Background Delegate",
@@ -958,7 +1008,9 @@
         "promptGuidelines": [
           "Use bg_delegate when work should continue in the background and the worker needs what you already know: it is seeded with a projection of this conversation.",
           "The prompt is authoritative. State exactly what you want investigated and what the answer should contain.",
-          "The delegate is inspect-only: it can read, search, and list files, but cannot run shell commands, edit or write files, use the network, or delegate further.",
+          "The delegate is inspect-only at the model-visible tool boundary: it can read, search, and list files, but cannot run shell commands, edit or write files, use the network, or delegate further.",
+          "Extension discovery is isolated by default. Use extensionMode:\"ambient\" only when the pinned provider is registered by an ambient user/project extension.",
+          "Ambient mode executes arbitrary discovered extension code in the child process. Tool allowlists do not sandbox extension code, so ambient mode weakens inspect-only process isolation.",
           "Facts that exist only inside omitted tool output are not available to the delegate. Restate such findings in the prompt.",
           "bg_delegate returns immediately. Do not poll; retrieve the answer with bg_result after the terminal notification arrives."
         ],
@@ -974,6 +1026,10 @@
               "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"
@@ -1028,7 +1084,7 @@
           ],
           "type": "object"
         },
-        "source": "src/delegate-extension.ts:307"
+        "source": "src/delegate-extension.ts:340"
       },
       {
         "description": "Stop a running background task by ID. Fails loudly if the task is unknown or already finished.",
@@ -1116,7 +1172,7 @@
           ],
           "type": "object"
         },
-        "source": "src/delegate-extension.ts:468"
+        "source": "src/delegate-extension.ts:515"
       },
       {
         "description": "Start a named long-running shell command in the background and return immediately with a task ID and output path. By default, completed, failed, or killed terminal state is delivered automatically as <background-task-notification> and starts a follow-up agent turn; do not sleep or poll merely to wait. Output is written to .pi/tasks and model-visible logs are bounded to 50.0KB.",
@@ -1608,6 +1664,9 @@
   },
   "schema_version": "pi-background-tasks.docs-manifest.v2",
   "source_to_docs": {
+    "extensions/anthropic-attribution.ts": [
+      "subsystems/anthropic-attribution"
+    ],
     "extensions/background-tasks.ts": [
       "subsystems/host-ui-and-telemetry"
     ],
@@ -1617,6 +1676,12 @@
     "extensions/fusion-child.ts": [
       "subsystems/fusion"
     ],
+    "src/core/anthropic-attribution-path.ts": [
+      "subsystems/anthropic-attribution"
+    ],
+    "src/core/anthropic-attribution.ts": [
+      "subsystems/anthropic-attribution"
+    ],
     "src/core/attested-pi-run.ts": [
       "subsystems/attested-pi-runs"
     ],
@@ -1665,9 +1730,6 @@
     "src/core/extension-api.ts": [
       "api/eventbus-v1"
     ],
-    "src/core/fusion/anthropic-attribution.ts": [
-      "subsystems/fusion"
-    ],
     "src/core/fusion/artifacts.ts": [
       "subsystems/fusion"
     ],
@@ -1766,6 +1828,9 @@
     "command:bg-update": [
       "commands/bg-update"
     ],
+    "command:claude-cache": [
+      "commands/claude-cache"
+    ],
     "command:fusion": [
       "commands/fusion"
     ],

package/docs/operations/configuration.md

@@ -59,6 +59,20 @@ Bounded logs are for context safety; they point to the full local output file wh
 
 Telemetry wrapping is best-effort and task-owned. Missing telemetry is reported as unavailable, never as zero. Under Windows `cmd`, safe interception is unavailable and the command is left unchanged.
 
+## Global Anthropic attribution and caching
+
+Normal package installation loads the package-owned Anthropic attribution/sanitization extension before the background-task extension. Non-Anthropic sessions are unchanged. Anthropic sessions require Pi's subscription OAuth route; the provider refuses metered Anthropic credentials and reads `userID` plus `oauthAccount.accountUuid` from `~/.claude.json` without writing it.
+
+| Variable/command | Effect |
+|---|---|
+| `PI_CACHE_RETENTION=long` | Default to one-hour Anthropic cache breakpoints where the model supports them. This is the package default when unset. |
+| `PI_CACHE_RETENTION=short` | Default to ordinary ephemeral cache breakpoints without a one-hour TTL. |
+| `PI_CACHE_RETENTION=none` | Do not add default cache breakpoints. Explicit call-level policy remains authoritative. |
+| `/claude-cache status` | Show the effective cache-retention policy for the current session. |
+| `/claude-cache short\|long\|default` | Store or clear a branch-local session override. |
+
+Invalid retention values and malformed persisted overrides fail loudly. The extension also removes only the three reviewed exact-match Pi system-prompt lines rejected by Anthropic; it has no external sanitizer dependency. See [Anthropic attribution](../subsystems/anthropic-attribution.md) and [`/claude-cache`](../commands/claude-cache.md).
+
 ## Fusion model configuration
 
 Fusion model slots are stored globally under the Pi agent directory as:
@@ -77,7 +91,7 @@ Use `/fusion-models` in TUI mode to configure five slots:
 
 Missing config means all five slots are `$current`. Config entries are qualified `provider/model` selections or `$current`; malformed config, stale explicit models, unavailable current models, and concurrent selector conflicts fail loudly before child inference.
 
-Fusion accepts frontier-model routes only through Pi Anthropic or Codex subscription OAuth where `ModelRegistry.isUsingOAuth` confirms the route. Metered frontier API-key/base-URL paths are rejected before child creation, and relevant metered environment variables are stripped from Fusion children. Anthropic children additionally use the package-owned Claude Code attribution provider shared with the repo-local `spawn-anthropic-attribution` entrypoint. It reads `userID` and `oauthAccount.accountUuid` from `~/.claude.json` read-only; missing or malformed attribution data fails loudly before Anthropic transport. Its subscription request policy is 200K, so Fusion clamps Anthropic budget capacity to 200K even when Pi's model catalog advertises a larger context.
+Fusion accepts frontier-model routes only through Pi Anthropic or Codex subscription OAuth where `ModelRegistry.isUsingOAuth` confirms the route. Metered frontier API-key/base-URL paths are rejected before child creation, and relevant metered environment variables are stripped from Fusion children. Anthropic children explicitly load the same package-owned global attribution/sanitization extension because Fusion disables ambient extension discovery. Missing or malformed attribution data fails loudly before Anthropic transport. Its subscription request policy is 200K, so Fusion clamps Anthropic budget capacity to 200K even when Pi's model catalog advertises a larger context.
 
 ## Fusion Claude prompt caching
 

package/docs/operations/releasing.md

@@ -34,6 +34,8 @@ npm run test:hook-contract
 npm run smoke
 npm run smoke:large-context
 npm run pack:dry-run
+# With pnpm 11.18.0 on PATH:
+npm run test:pnpm-pack
 npm run docs:verify
 npm run payload:check
 # On a tag ref only: GITHUB_REF_TYPE=tag GITHUB_REF_NAME=v$VERSION npm run release:check-version
@@ -49,11 +51,12 @@ Live evidence (`npx tsx scripts/delegate-live-run.ts`) is release-time and perfo
 
 Use `npm pack --dry-run --json` output as the payload source of truth. Verify at minimum:
 
-- `extensions/background-tasks.ts` is included as the Pi entrypoint;
-- runtime `src/` files needed by the entrypoint are included;
-- `docs/`, `README.md`, `TESTING.md`, `TEST_PLAN.md`, `PUBLISHING.md`, `BACKGROUND-TASKS-INSTRUCTIONS.md`, root `logo.png`, and `LICENSE` are included per current `package.json.files`;
+- `extensions/anthropic-attribution.ts` and `extensions/background-tasks.ts` are included as the ordered Pi entrypoints;
+- runtime `src/` files needed by both entrypoints are included;
+- `docs/`, `README.md`, `TESTING.md`, `TEST_PLAN.md`, `PUBLISHING.md`, `BACKGROUND-TASKS-INSTRUCTIONS.md`, `THIRD_PARTY_NOTICES.md`, root `logo.png`, and `LICENSE` are included per current `package.json.files`;
 - tests, scripts, node_modules, local `.pi/` artifacts, generated evidence not meant for runtime, and nested tarballs are excluded;
 - TypeBox remains a Pi-provided peer and no private/nested runtime TypeBox copy is bundled;
+- production dependencies use registry versions only; no exotic URL/git/file subdependency is shipped;
 - docs/assets/gateway/logo inclusion matches `package.json.files` exactly.
 
 ## Tag certification vs npm publishing

package/docs/read-before-edit.md

@@ -15,9 +15,12 @@ Every production file under `src/**` and `extensions/**` has exactly one primary
 
 | Source | Primary behavioral owner |
 | --- | --- |
+| `extensions/anthropic-attribution.ts` | [subsystems/anthropic-attribution](./subsystems/anthropic-attribution.md) |
 | `extensions/background-tasks.ts` | [subsystems/host-ui-and-telemetry](./subsystems/host-ui-and-telemetry.md) |
 | `extensions/delegate-child.ts` | [subsystems/delegation](./subsystems/delegation.md) |
 | `extensions/fusion-child.ts` | [subsystems/fusion](./subsystems/fusion.md) |
+| `src/core/anthropic-attribution-path.ts` | [subsystems/anthropic-attribution](./subsystems/anthropic-attribution.md) |
+| `src/core/anthropic-attribution.ts` | [subsystems/anthropic-attribution](./subsystems/anthropic-attribution.md) |
 | `src/core/attested-pi-run.ts` | [subsystems/attested-pi-runs](./subsystems/attested-pi-runs.md) |
 | `src/core/common.ts` | [subsystems/background-task-runtime](./subsystems/background-task-runtime.md) |
 | `src/core/context/parent-snapshot.ts` | [concepts/context-projection-and-budgeting](./concepts/context-projection-and-budgeting.md) |
@@ -34,7 +37,6 @@ Every production file under `src/**` and `extensions/**` has exactly one primary
 | `src/core/delegate/types.ts` | [subsystems/delegation](./subsystems/delegation.md) |
 | `src/core/durable-fs.ts` | [subsystems/child-launch-durability-and-safety](./subsystems/child-launch-durability-and-safety.md) |
 | `src/core/extension-api.ts` | [api/eventbus-v1](./api/eventbus-v1.md) |
-| `src/core/fusion/anthropic-attribution.ts` | [subsystems/fusion](./subsystems/fusion.md) |
 | `src/core/fusion/artifacts.ts` | [subsystems/fusion](./subsystems/fusion.md) |
 | `src/core/fusion/budget.ts` | [subsystems/fusion](./subsystems/fusion.md) |
 | `src/core/fusion/child-protocol.ts` | [subsystems/fusion](./subsystems/fusion.md) |
@@ -70,6 +72,7 @@ Every production file under `src/**` and `extensions/**` has exactly one primary
 - `command:bg-clear`
 - `command:bg-tasks`
 - `command:bg-update`
+- `command:claude-cache`
 - `command:fusion`
 - `command:fusion-models`
 - `command:jobs`

package/docs/reference/runtime-contracts.md

@@ -26,43 +26,43 @@ This generated registry lists production environment-variable references, runtim
 | `AZURE_OPENAI_DEPLOYMENT_NAME_MAP` | remove | `src/core/fusion/pi-child.ts:98` |
 | `AZURE_OPENAI_ENDPOINT` | remove | `src/core/fusion/pi-child.ts:98` |
 | `AZURE_OPENAI_RESOURCE_NAME` | remove | `src/core/fusion/pi-child.ts:98` |
-| `ComSpec` | read | `src/core/common.ts:725`<br>`src/core/common.ts:736` |
+| `ComSpec` | read | `src/core/common.ts:726`<br>`src/core/common.ts:737` |
 | `OPENAI_API_KEY` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:98` |
 | `OPENAI_BASE_URL` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:98` |
 | `OPENROUTER_API_KEY` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:98` |
 | `OPENROUTER_BASE_URL` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:98` |
-| `path` | read | `src/core/common.ts:680` |
-| `Path` | read | `src/core/common.ts:680` |
-| `PATH` | read | `src/core/common.ts:680` |
+| `path` | read | `src/core/common.ts:681` |
+| `Path` | read | `src/core/common.ts:681` |
+| `PATH` | read | `src/core/common.ts:681` |
 | `PI_API_BASE_URL` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:98` |
 | `PI_API_KEY` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:98` |
 | `PI_AUTH_FILE` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:98` |
-| `PI_BG_DELEGATE_ARTIFACT_DIR` | read, write | `src/core/delegate/launch.ts:324`<br>`src/delegate-child-extension.ts:276` |
-| `PI_BG_DELEGATE_LAUNCH_NONCE` | read, write | `src/core/delegate/launch.ts:328`<br>`src/delegate-child-extension.ts:280` |
-| `PI_BG_DELEGATE_SEED_PATH` | read, write | `src/core/delegate/launch.ts:325`<br>`src/delegate-child-extension.ts:277` |
-| `PI_BG_DELEGATE_SEED_SHA256` | read, write | `src/core/delegate/launch.ts:326`<br>`src/delegate-child-extension.ts:278` |
-| `PI_BG_DELEGATE_TASK_ID` | read, write | `src/core/delegate/launch.ts:327`<br>`src/delegate-child-extension.ts:279` |
-| `PI_BG_DISABLE_PI_TELEMETRY` | read | `src/core/registry.ts:194` |
+| `PI_BG_DELEGATE_ARTIFACT_DIR` | read, write | `src/core/delegate/launch.ts:353`<br>`src/delegate-child-extension.ts:279` |
+| `PI_BG_DELEGATE_LAUNCH_NONCE` | read, write | `src/core/delegate/launch.ts:357`<br>`src/delegate-child-extension.ts:283` |
+| `PI_BG_DELEGATE_SEED_PATH` | read, write | `src/core/delegate/launch.ts:354`<br>`src/delegate-child-extension.ts:280` |
+| `PI_BG_DELEGATE_SEED_SHA256` | read, write | `src/core/delegate/launch.ts:355`<br>`src/delegate-child-extension.ts:281` |
+| `PI_BG_DELEGATE_TASK_ID` | read, write | `src/core/delegate/launch.ts:356`<br>`src/delegate-child-extension.ts:282` |
+| `PI_BG_DISABLE_PI_TELEMETRY` | read | `src/core/registry.ts:195` |
 | `PI_BG_DISABLE_UPDATE_CHECK` | read | `src/extension.ts:455` |
-| `PI_BG_MAX_OUTPUT_BYTES` | read | `src/core/registry.ts:68` |
+| `PI_BG_MAX_OUTPUT_BYTES` | read | `src/core/registry.ts:69` |
 | `PI_BG_REGISTRY_URL` | read | `src/extension.ts:464` |
-| `PI_BG_SHELL` | read | `src/core/common.ts:721` |
-| `PI_BG_SHELL_PATH` | read | `src/core/common.ts:722` |
-| `PI_CACHE_RETENTION` | read, write | `src/core/fusion/anthropic-attribution.ts:577`<br>`src/core/fusion/claude-cache.ts:57`<br>`src/core/fusion/pi-child.ts:271`<br>`src/core/fusion/pi-child.ts:272` |
-| `PI_FUSION_CANDIDATE_OUTPUT_RECOVERY_PATH` | read, remove, write | `src/core/fusion/pi-child.ts:1989`<br>`src/core/fusion/pi-child.ts:98`<br>`src/fusion-child-extension.ts:599` |
-| `PI_FUSION_RESEARCH_ENABLED` | read, remove, write | `src/core/fusion/pi-child.ts:2012`<br>`src/core/fusion/pi-child.ts:98`<br>`src/fusion-child-extension.ts:608` |
-| `PI_FUSION_SOURCE_POLICY_PATH` | read, remove, write | `src/core/fusion/pi-child.ts:2013`<br>`src/core/fusion/pi-child.ts:98`<br>`src/fusion-child-extension.ts:555` |
-| `PI_FUSION_SOURCE_POLICY_SHA256` | read, remove, write | `src/core/fusion/pi-child.ts:2014`<br>`src/core/fusion/pi-child.ts:98`<br>`src/fusion-child-extension.ts:556` |
-| `PI_FUSION_TOOL_CALL_LOG_PATH` | read, remove, write | `src/core/fusion/pi-child.ts:2001`<br>`src/core/fusion/pi-child.ts:98`<br>`src/fusion-child-extension.ts:598` |
-| `PI_MODEL` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:98` |
+| `PI_BG_SHELL` | read | `src/core/common.ts:722` |
+| `PI_BG_SHELL_PATH` | read | `src/core/common.ts:723` |
+| `PI_CACHE_RETENTION` | read, write | `src/core/anthropic-attribution.ts:587`<br>`src/core/fusion/claude-cache.ts:57`<br>`src/core/fusion/pi-child.ts:271`<br>`src/core/fusion/pi-child.ts:272` |
+| `PI_FUSION_CANDIDATE_OUTPUT_RECOVERY_PATH` | read, remove, write | `src/core/fusion/pi-child.ts:1872`<br>`src/core/fusion/pi-child.ts:98`<br>`src/fusion-child-extension.ts:599` |
+| `PI_FUSION_RESEARCH_ENABLED` | read, remove, write | `src/core/fusion/pi-child.ts:1895`<br>`src/core/fusion/pi-child.ts:98`<br>`src/fusion-child-extension.ts:608` |
+| `PI_FUSION_SOURCE_POLICY_PATH` | read, remove, write | `src/core/fusion/pi-child.ts:1896`<br>`src/core/fusion/pi-child.ts:98`<br>`src/fusion-child-extension.ts:555` |
+| `PI_FUSION_SOURCE_POLICY_SHA256` | read, remove, write | `src/core/fusion/pi-child.ts:1897`<br>`src/core/fusion/pi-child.ts:98`<br>`src/fusion-child-extension.ts:556` |
+| `PI_FUSION_TOOL_CALL_LOG_PATH` | read, remove, write | `src/core/fusion/pi-child.ts:1884`<br>`src/core/fusion/pi-child.ts:98`<br>`src/fusion-child-extension.ts:598` |
+| `PI_MODEL` | remove | `src/core/delegate/launch.ts:330`<br>`src/core/fusion/pi-child.ts:98` |
 | `PI_OFFLINE` | read | `src/extension.ts:456` |
-| `PI_PROVIDER` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:98` |
-| `PI_REASONING_LEVEL` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:98` |
-| `PI_SESSION_FILE` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:98` |
-| `PI_SESSION_ID` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:98` |
-| `PI_SKIP_VERSION_CHECK` | write | `src/core/delegate/launch.ts:323`<br>`src/core/fusion/pi-child.ts:270` |
-| `PIPELINE_ANTHROPIC_ATTRIBUTION_AUDIT_PATH` | read | `src/core/fusion/anthropic-attribution.ts:1003` |
-| `SHELL` | read | `src/core/common.ts:717` |
+| `PI_PROVIDER` | remove | `src/core/delegate/launch.ts:330`<br>`src/core/fusion/pi-child.ts:98` |
+| `PI_REASONING_LEVEL` | remove | `src/core/delegate/launch.ts:330`<br>`src/core/fusion/pi-child.ts:98` |
+| `PI_SESSION_FILE` | remove | `src/core/delegate/launch.ts:330`<br>`src/core/fusion/pi-child.ts:98` |
+| `PI_SESSION_ID` | remove | `src/core/delegate/launch.ts:330`<br>`src/core/fusion/pi-child.ts:98` |
+| `PI_SKIP_VERSION_CHECK` | write | `src/core/delegate/launch.ts:352`<br>`src/core/fusion/pi-child.ts:270` |
+| `PIPELINE_ANTHROPIC_ATTRIBUTION_AUDIT_PATH` | read | `src/core/anthropic-attribution.ts:1013` |
+| `SHELL` | read | `src/core/common.ts:718` |
 | `SystemRoot` | read | `src/core/windows-taskkill.ts:96` |
 | `WINDIR` | read | `src/core/windows-taskkill.ts:101` |
 
@@ -71,20 +71,20 @@ This generated registry lists production environment-variable references, runtim
 | Kind | Path/artifact | Provenance |
 | --- | --- | --- |
 | config | `fusion-models.json` | `src/core/fusion/config.ts:21` |
-| delegate-artifact | `budget-plan.json` | `src/core/delegate/artifacts.ts:42` |
-| delegate-artifact | `child-prompt.txt` | `src/core/delegate/artifacts.ts:46` |
-| delegate-artifact | `child.stderr.txt` | `src/core/delegate/artifacts.ts:47` |
-| delegate-artifact | `child.stdout.txt` | `src/core/delegate/artifacts.ts:48` |
-| delegate-artifact | `context-omission-ledger.json` | `src/core/delegate/artifacts.ts:41` |
-| delegate-artifact | `error.json` | `src/core/delegate/artifacts.ts:49` |
-| delegate-artifact | `manifest.json` | `src/core/delegate/artifacts.ts:43` |
-| delegate-artifact | `outcome.json` | `src/core/delegate/artifacts.ts:44` |
+| delegate-artifact | `budget-plan.json` | `src/core/delegate/artifacts.ts:43` |
+| delegate-artifact | `child-prompt.txt` | `src/core/delegate/artifacts.ts:47` |
+| delegate-artifact | `child.stderr.txt` | `src/core/delegate/artifacts.ts:48` |
+| delegate-artifact | `child.stdout.txt` | `src/core/delegate/artifacts.ts:49` |
+| delegate-artifact | `context-omission-ledger.json` | `src/core/delegate/artifacts.ts:42` |
+| delegate-artifact | `error.json` | `src/core/delegate/artifacts.ts:50` |
+| delegate-artifact | `manifest.json` | `src/core/delegate/artifacts.ts:44` |
+| delegate-artifact | `outcome.json` | `src/core/delegate/artifacts.ts:45` |
 | delegate-artifact | `result.json` | `src/core/delegate/result-package.ts:28` |
-| delegate-artifact | `seed.json` | `src/core/delegate/artifacts.ts:40` |
-| delegate-artifact | `spill/<receipt-named-file>` | `src/core/delegate/artifacts.ts:53` |
-| directory | `.pi/delegate/<session-id>-<pid>/<task-id>/` | `src/core/delegate/artifacts.ts:157` |
+| delegate-artifact | `seed.json` | `src/core/delegate/artifacts.ts:41` |
+| delegate-artifact | `spill/<receipt-named-file>` | `src/core/delegate/artifacts.ts:54` |
+| directory | `.pi/delegate/<session-id>-<pid>/<task-id>/` | `src/core/delegate/artifacts.ts:160` |
 | directory | `.pi/fusion/<session-id>-<pid>/<run-id>/` | `src/core/fusion/artifacts.ts:563` |
-| directory | `.pi/tasks/<session-id>-<pid>/` | `src/core/registry.ts:783` |
+| directory | `.pi/tasks/<session-id>-<pid>/` | `src/core/registry.ts:784` |
 | fusion-artifact | `<attempt-prefix> = candidate-<slot>.attempt-<n> \| evaluation.attempt-<n> \| merge.attempt-<n>` | `src/core/fusion/artifacts.ts:248` |
 | fusion-artifact | `<attempt-prefix>.calibration-violation.json` | `src/core/fusion/artifacts.ts:263` |
 | fusion-artifact | `<attempt-prefix>.events.jsonl` | `src/core/fusion/artifacts.ts:804` |
@@ -104,12 +104,12 @@ This generated registry lists production environment-variable references, runtim
 | fusion-artifact | `merged.md` | `src/core/fusion/artifacts.ts:387` |
 | fusion-artifact | `result.json` | `src/core/fusion/artifacts.ts:647` |
 | fusion-artifact | `source-policy.private.json` | `src/core/fusion/artifacts.ts:690` |
-| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.attestation.json` | `src/core/attested-pi-run.ts:583` |
-| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.json` | `src/core/registry.ts:811` |
-| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.output` | `src/core/registry.ts:810` |
-| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.pi-events.jsonl` | `src/core/attested-pi-run.ts:580` |
-| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.pi-telemetry-wrapper.cjs` | `src/core/attested-pi-run.ts:582` |
-| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.stderr` | `src/core/attested-pi-run.ts:581` |
+| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.attestation.json` | `src/core/attested-pi-run.ts:592` |
+| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.json` | `src/core/registry.ts:812` |
+| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.output` | `src/core/registry.ts:811` |
+| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.pi-events.jsonl` | `src/core/attested-pi-run.ts:589` |
+| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.pi-telemetry-wrapper.cjs` | `src/core/attested-pi-run.ts:591` |
+| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.stderr` | `src/core/attested-pi-run.ts:590` |
 
 ### Schema identifiers
 
@@ -117,16 +117,16 @@ This generated registry lists production environment-variable references, runtim
 | --- | --- |
 | `phase2.pi_task_attestation.v1` | `src/core/attested-pi-run.ts:20` |
 | `pi-background-tasks.delegate-budget-plan.v2` | `src/core/delegate/types.ts:21` |
-| `pi-background-tasks.delegate-child-terminal.v1` | `src/delegate-child-extension.ts:380` |
+| `pi-background-tasks.delegate-child-terminal.v1` | `src/delegate-child-extension.ts:387` |
 | `pi-background-tasks.delegate-hook-contract.v1` | `src/core/delegate/hook-contract.ts:15` |
-| `pi-background-tasks.delegate-launch.v1` | `src/delegate-extension.ts:413` |
+| `pi-background-tasks.delegate-launch.v1` | `src/delegate-extension.ts:458` |
 | `pi-background-tasks.delegate-ledger.v1` | `src/core/delegate/types.ts:16` |
-| `pi-background-tasks.delegate-manifest.v1` | `src/core/delegate/types.ts:22` |
-| `pi-background-tasks.delegate-outcome.v1` | `src/core/delegate/runner.ts:200` |
+| `pi-background-tasks.delegate-manifest.v2` | `src/core/delegate/types.ts:22` |
+| `pi-background-tasks.delegate-outcome.v1` | `src/core/delegate/runner.ts:224` |
 | `pi-background-tasks.delegate-receipt.v1` | `src/core/delegate/types.ts:19` |
-| `pi-background-tasks.delegate-result-view.v1` | `src/delegate-extension.ts:683` |
+| `pi-background-tasks.delegate-result-view.v1` | `src/delegate-extension.ts:731` |
 | `pi-background-tasks.delegate-result.v1` | `src/core/delegate/types.ts:18` |
-| `pi-background-tasks.delegate-seed.v1` | `src/core/delegate/types.ts:15` |
+| `pi-background-tasks.delegate-seed.v2` | `src/core/delegate/types.ts:15` |
 | `pi-background-tasks.extension-request.v1` | `src/core/extension-api.ts:15` |
 | `pi-background-tasks.extension-response.v1` | `src/core/extension-api.ts:16` |
 | `pi-background-tasks.extension-terminal.v1` | `src/core/extension-api.ts:17` |
@@ -149,7 +149,7 @@ This generated registry lists production environment-variable references, runtim
 | `pi-background-tasks.fusion-merge-input.v1` | `src/core/fusion/prompts.ts:336` |
 | `pi-background-tasks.fusion-models.v1` | `src/core/fusion/types.ts:13` |
 | `pi-background-tasks.fusion-progress.v1` | `src/fusion-extension.ts:59` |
-| `pi-background-tasks.fusion-result-view.v1` | `src/delegate-extension.ts:723` |
+| `pi-background-tasks.fusion-result-view.v1` | `src/delegate-extension.ts:772` |
 | `pi-background-tasks.fusion-result.v4` | `src/core/fusion/types.ts:19` |
 | `pi-background-tasks.fusion-result.v5` | `src/core/fusion/types.ts:20` |
 | `pi-background-tasks.fusion-runtime-guard.v2` | `src/core/fusion/child-protocol.ts:24` |

package/docs/subsystems/anthropic-attribution.md

@@ -0,0 +1,63 @@
+---
+doc_id: subsystems/anthropic-attribution
+audience: maintainer
+mode: authored
+review_policy: behavioral
+stability: evolving
+covers_surfaces: []
+covers_sources: [extensions/anthropic-attribution.ts, src/core/anthropic-attribution-path.ts, src/core/anthropic-attribution.ts]
+---
+# Anthropic attribution subsystem
+
+This subsystem owns the package-wide Anthropic subscription attribution provider, exact-match system-prompt sanitization, cache-retention command, and the package extension path shared by isolated child Pi processes.
+
+## Global package behavior
+
+`package.json.pi.extensions` loads `extensions/anthropic-attribution.ts` for every normal `pi-background-tasks` installation, before the background-task entrypoint. The extension is provider-gated: non-Anthropic sessions and payloads are unchanged.
+
+For Anthropic sessions it registers the package-owned `anthropic` provider transport and applies the Claude Code subscription request contract:
+
+- subscription OAuth token transport only; metered Anthropic credentials are refused;
+- Claude Code session, account, device, beta, user-agent, and system-identity attribution;
+- model-specific fixed/adaptive thinking policy;
+- the conservative 200K subscription context policy;
+- system, final-tool, and final-conversation cache surfaces;
+- provider-authoritative usage and one-hour cache-write accounting when reported.
+
+The extension reads `userID` and `oauthAccount.accountUuid` from `~/.claude.json` without writing it. Missing/malformed account data, unsupported model policy, malformed payload/cache controls, and non-OAuth transport fail loudly.
+
+## Sanitization
+
+The package has no runtime dependency on `@ravshansbox/pi-anthropic-sps`. Its three reviewed exact-match prompt-line rules are implemented locally in `src/core/anthropic-attribution.ts`, with the upstream MIT notice retained in `THIRD_PARTY_NOTICES.md`.
+
+Only complete matching lines are removed. Other system text, non-text blocks, custom block fields, and valid cache controls are preserved. The rules cover both Pi documentation-list variants—with and without `environment-variables.md`—plus the cross-reference instruction line.
+
+## Duplicate-owner protocol
+
+A package extension and an independent project/user copy can otherwise register duplicate provider hooks and `/claude-cache` commands. The factory therefore probes `pi-anthropic-attribution:claim:v1` on Pi's shared EventBus before registration. The first successfully registered copy installs one responder; later compatible copies become inert.
+
+Ownership is published only after all hooks and the command register. Extension loading is sequential and EventBus listener invocation is synchronous at the probe boundary, so a failed first factory cannot strand a false claim. The responder lives for the shared EventBus runtime, matching the extension registrations it protects.
+
+## Isolated package children
+
+Ambient discovery is insufficient for child paths that use `--no-extensions`. `resolveAnthropicAttributionExtensionPath()` is the single package path seam used by:
+
+- Fusion Anthropic children, before the Fusion runtime governor;
+- Anthropic delegate children, before the delegate guard;
+- Anthropic attested Pi children.
+
+Non-Anthropic child argv does not resolve or add this extension. Missing package extension bytes fail before child creation; no route substitution or sanitizer fallback is attempted.
+
+Arbitrary shell commands started through `bg_run` are not rewritten. An Anthropic child `pi` launched this way must keep normal extension discovery enabled. If the command deliberately uses `--no-extensions`, it must also explicitly load this package's `extensions/anthropic-attribution.ts` with `-e`/`--extension`; otherwise attribution and sanitization are bypassed and the launch is unsupported. The package does not parse or override arbitrary shell authority.
+
+## Cache retention
+
+`PI_CACHE_RETENTION=none|short|long` selects process/provider policy. `/claude-cache status|short|long|default` stores a branch-local session override as a custom entry that does not enter model context. Call-level `cacheRetention` remains highest precedence, notably preserving Pi's compaction opt-out.
+
+## Related docs
+
+- [`/claude-cache`](../commands/claude-cache.md)
+- [Configuration](../operations/configuration.md)
+- [Fusion subsystem](fusion.md)
+- [Delegation subsystem](delegation.md)
+- [Attested Pi runs](attested-pi-runs.md)

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.