@jopqior/pi-subagents 1.0.0

package/docs/decisions/0006-inherited-prompt-is-identity-only.md

@@ -0,0 +1,104 @@
+---
+status: amended by 0008
+date: 2026-08-30
+---
+
+# 0006 — A child inherits the parent prompt's identity, not its session-resolved tail
+
+## Status
+
+Accepted, and amended by [ADR 0008].
+Supersedes the equal-cwd exception recorded in [#640] and generalizes it into one rule for every layer Pi resolves per session.
+
+The mechanism below is unchanged: a child still inherits the identity region and nothing after it.
+[ADR 0008] amends what that placement *guarantees* — shared parts rather than shared bytes, scoped to hosts that reuse a prefix over the system text independently of the tool definitions — after [#890] found that an extension narrowing the `Available tools:` listing inside this region ended the shared prefix at offset 171.
+
+## Context
+
+`buildAgentPrompt` embeds the parent session's effective system prompt verbatim as the child's leading content.
+That placement is deliberate and load-bearing: [#180] and [#400] moved the shared parent text to the front precisely so a child's prompt shares a byte-identical prefix with its parent's, which prefix-caching providers and local inference engines reuse instead of reprocessing.
+The reporter of [#180] measured 8,333 shared tokens costing roughly 40 seconds of prompt processing on a local model before that change.
+
+What the placement overlooked is that the parent's *effective* prompt is not identity alone.
+Pi's `buildSystemPrompt` writes four regions and extensions append a fifth:
+
+| Region         | Content                                                                    | Written by                                                                |
+| -------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| Identity       | preamble or `customPrompt`, tool snippets, guidelines, `<project_context>` | `buildSystemPrompt`                                                       |
+| Catalogue      | the skills heading and `<available_skills>` … `</available_skills>`        | `formatSkillsForPrompt`, gated on the session's tool set including `read` |
+| Footer         | `Current working directory: <cwd>`                                         | `buildSystemPrompt`, always last                                          |
+| Extension tail | further blocks                                                             | handlers returning `systemPrompt` from `before_agent_start`               |
+
+The last three are resolved against **one session**: its directory, its loaded skills, its bound extensions.
+The extension tail is resolved against one *turn* — Pi rebuilds it from the base prompt on every turn and applies it as a single-turn override.
+
+A child session rebuilds all three for itself and appends them after the inherited copy.
+Inheriting them therefore hands the child a second, stale claim of each.
+[#640] found this for the footer, where a worktree-isolated child followed the parent's directory back out of its workspace.
+[#801] found it again for the catalogue, reported as a visibly duplicated `<available_skills>` block.
+
+## Decision
+
+The inherited prompt contributes **only its identity region**.
+`inheritedIdentity` cuts at the first per-session layer present — the catalogue, or the footer when the parent session resolved no skills — and returns what precedes it.
+
+### Truncate rather than excise
+
+The alternative was to cut the catalogue and footer out while keeping the extension tail.
+It was rejected on both criteria.
+
+On accuracy, the inherited tail is the least defensible layer of the three.
+It was built for the parent's directory and the parent's extension set: `@gotgenes/pi-nocd`'s block names the parent's cwd — the [#640] defect itself — and a package excluded from children through `excludedExtensionPackages` ([#696]) still reaches them through the inherited copy, which is the exact opposite of what that setting asks for.
+
+On cost, excision is strictly worse for the constituency [#180] exists to protect.
+Removing an interior span leaves the tail in the child but displaces it past the divergence point, moving it from cached to prefilled — measured at roughly 275 characters in [#640]'s environment.
+Truncation deletes it instead, so a child's prefilled token count is unchanged from before this decision while its total prompt shrinks by the whole tail.
+
+### The equal-cwd exception is withdrawn
+
+[#640] kept an inherited footer when the child's directory matched the parent's, on the grounds that removing an accurate duplicate would shorten the byte-identical prefix.
+That reasoning depended on the footer being inside the shared prefix.
+The catalogue precedes the footer, so once the catalogue is cut the footer is already past the divergence point and the exception preserves nothing.
+It survives only for a parent session that resolved no skills, where it would save one line.
+The footer is now stripped unconditionally.
+
+### The catalogue is located by position, not by document order
+
+A project-context file may quote Pi's own prompt text, and so may a block an extension appended after the footer.
+Any rule that picks the first or the last `<available_skills>` in the prompt is a guess about document order, and it is wrong in one direction or the other: the first loses to a quote in project context, the last loses to a quote in an appended block.
+
+`buildSystemPrompt` writes the cwd footer immediately after the catalogue, in both of its branches and unconditionally.
+Pi's own catalogue is therefore exactly the one whose closing tag is the line before the footer, which is a structural fact rather than a heuristic.
+The heading is then found by searching back from that tag, so prose quoting the heading ahead of the section is not mistaken for it either.
+A prompt with no footer has been rewritten by something downstream; there the last closing tag is the best remaining guess.
+
+Both anchors match whole lines, which keeps a footer naming a directory that merely shares a prefix with the parent's from being mistaken for it.
+
+## Consequences
+
+- A child's assembled prompt carries exactly one skills catalogue and one working-directory claim, both describing the child's own session.
+- Extensions that append to the system prompt no longer reach children through inheritance.
+  Their handlers still run in the child — it binds the parent's extension set and its turn loop fires `before_agent_start` unconditionally — so an unconditional appender simply writes a block built for the child.
+  This is documented for extension authors in the README.
+- **Accepted residual:** a handler that appends conditionally — gated on an interactive UI, or on state cached at `session_start` — contributes nothing in a child, which then carries less guidance than it did before this decision.
+  The mechanism is verified to fire in children and this package's own appender is unconditional, but the third-party population cannot be enumerated.
+  The trade is accepted because the alternative is inheriting a block built for another directory and another extension set, which is wrong rather than merely absent.
+- The shared prefix a child holds with its parent is shorter by the three dropped regions.
+  Nothing that remains in the child's prompt moved out of that prefix, so no additional tokens require processing.
+- `@gotgenes/pi-nocd` documents a rewrite path premised on subagents inheriting the prompt verbatim, which this decision ends.
+  Tracked as [#846].
+- A consumer that recovers the inherited region by searching a child's prompt for the parent's *full* assembled prompt finds nothing, because truncation ends the containment it matches on.
+  `pi-claude-bridge` does exactly this to project a child's prompt onto another harness, so a child on that provider forwards Pi's base prompt where the parent forwards only its portable parts.
+  Reported as [#883]; a consumer-side matcher fix is proposed at [pi-claude-bridge#88].
+  A child whose cwd differs from its parent's is beyond any such fix: Pi's `useExtensionCacheCwd` clears the extension cache on a cwd change, so the consumer's capture of the parent never exists in the child's module instance at all.
+
+[#180]: https://github.com/gotgenes/pi-packages/issues/180
+[#400]: https://github.com/gotgenes/pi-packages/issues/400
+[#640]: https://github.com/gotgenes/pi-packages/issues/640
+[#696]: https://github.com/gotgenes/pi-packages/issues/696
+[#801]: https://github.com/gotgenes/pi-packages/issues/801
+[#846]: https://github.com/gotgenes/pi-packages/issues/846
+[#890]: https://github.com/gotgenes/pi-packages/issues/890
+[ADR 0008]: 0008-inherited-region-is-shared-parts.md
+[#883]: https://github.com/gotgenes/pi-packages/issues/883
+[pi-claude-bridge#88]: https://github.com/elidickinson/pi-claude-bridge/issues/88

package/docs/decisions/0007-transcript-viewer-is-not-an-overlay.md

@@ -0,0 +1,228 @@
+---
+status: accepted
+date: 2026-09-03
+---
+
+# 0007 — The transcript viewer is a docked pane, not an overlay
+
+## Status
+
+Accepted.
+Closes Pi's overlay mount to this package until the upstream compositor changes.
+
+## Context
+
+`/subagents:sessions` mounted its transcript viewer with `ui.custom(..., { overlay: true })`.
+Operators reported fragments of the viewer's box — the `╭─` top rule, the `Subagent session` header, empty box rows — interwoven through the terminal's scrollback, repeating every few screens and surviving the viewer being closed ([#733]).
+
+### The mechanism
+
+In pi-tui 0.84.4's `TuiMainScreen.doRender`, overlays are composited into the rendered lines **before** the differential compare (`packages/tui/src/tui-main-screen.ts:267`), and that composited array is then stored as `previousLines` — at every assignment site, not only the clearing one (`:314` full render, `:440` deleted-lines path, `:611` the ordinary differential path).
+The renderer's model of the transcript at those rows *is* the overlay.
+
+Differential rendering can only repair rows still on screen.
+Anything the terminal has scrolled past is already committed to scrollback with the overlay's pixels in it.
+
+`TuiAltScreen` composites into a bounded `screen` buffer with no scrollback behind it (`tui-alt-screen.ts:1321`), so this is a regular-mode defect only.
+
+### The precondition, measured
+
+The obvious account — that every row under the overlay eventually scrolls off carrying chrome — is **wrong**, and the first two attempts at a reproduction correctly found nothing.
+While output is appended a line at a time, the overlay band moves up through rows that are still on screen, and the differential renderer repairs each one before it scrolls away.
+
+The failure needs a single append large enough to carry a row from under the overlay past the top of the screen in one frame.
+That row is committed with the chrome still in it and can never be reached again.
+
+Measured on a 24-row terminal with a 10-line centered overlay, by the script below:
+
+| Lines appended per frame | Rows committed carrying chrome |
+| ------------------------ | ------------------------------ |
+| 1, 3, 6, 7               | 0                              |
+| 8                        | 57                             |
+| 9                        | 114                            |
+| 10                       | 171 of 576                     |
+| 25                       | 590                            |
+
+The threshold is geometry, not chance: a 10-line box centered in 24 rows sits at screen row `floor((24 - 10) / 2) = 7`, so a row beneath its top edge must travel 8 rows to leave the screen entirely — one more than the distance to the top.
+An identical control run without the overlay commits none.
+
+This is why the symptom is intermittent, and why [#733] reports it as worst during tool calls: tool output arrives in chunks.
+The shipped viewer's box was 70% of the terminal height, putting its threshold around 7 lines, which nearly any tool call clears.
+
+### Upstream
+
+The maintainer rejected an adjacent diagnosis in [earendil-works/pi#4785] — a report that the diff scan's start index forces a full redraw on off-screen spinner ticks — with "you are wrong. your clanker is wrong. as explained on twitter.com."
+No technical reason is recorded in the tracker and the cited explanation is off-platform.
+That report concerns the widget render loop ([#864]), not this mechanism, so nothing upstream has ruled on the claim here.
+
+It is recorded because it is the reason not to plan around upstream fixing this.
+By contrast [earendil-works/pi#2759], which arrived with a reproduction command against the repo's own example extension, was reproduced by the maintainer and fixed within the hour — which is why the script below exists.
+
+## Decision
+
+Mount the transcript viewer through `ui.custom`'s **non-overlay** path, and do not use `overlay: true` in this package.
+
+Pi's `showExtensionCustom` then clears the input-editor container, adds the component, and focuses it.
+The pane renders at full terminal width with the conversation streaming above it, and `ui.custom` restores the editor and any typed text on close.
+No compositing happens, so nothing can be baked into scrollback.
+
+The rejected alternative was forcing a full repaint on close (`requestRender(true)`).
+It erases the fragments already in scrollback but leaves the viewer shredding while open, and wipes the terminal's scrollback history as a side effect.
+
+Fixing `compositeOverlays` upstream is the more general answer and is not ours to make.
+The non-overlay path is entirely within our control and removes the failure mode rather than papering over it.
+
+## Consequences
+
+- The viewer is a pane docked above the editor, not a floating window.
+  Its chrome is a header and a footer line: docked, it is already bracketed by the agents widget above and Pi's footer below, so a frame costs rows for nothing.
+- It renders at full terminal width, so there is no overlay width to keep in sync and no compositor `maxHeight` slice.
+- Its height is sized to its content, capped at a share of the terminal, because a docked pane that reserves a fixed 70% pushes the conversation off screen to show blank space.
+- The path is well exercised rather than novel: it is what Pi runs for the editor on every turn, and what `pi-permission-system`'s permission prompt already uses with an explicit `{ overlay: false }`.
+- This is consistent with [ADR 0004](0004-reconsider-ui-direction.md), which replaced the bespoke `ConversationViewer` overlay with native session navigation and framed the interaction as navigation rather than a live overlay.
+- The repo's other `overlay: true` call site, `pi-permission-system`'s settings modal, has the same defect at much lower exposure and is tracked separately as [#874].
+  Its fix is a different question, because it asks for a fixed 82-column width the non-overlay path does not offer.
+
+## Reproduction
+
+A dated claim about `@earendil-works/pi-tui` **0.84.4**, using only its public API (`TuiMainScreen`, `showOverlay`, `renderNow`, `captureRenderState`).
+It needs no Pi monorepo checkout and no extension.
+Nothing in CI runs it; it is preserved as evidence, not as a test, and it will stop being meaningful when the upstream compositor changes.
+
+Run with `node repro.mjs <lines-appended-per-frame>`; the table above used 1 through 25.
+
+```javascript
+import { TuiMainScreen } from "@earendil-works/pi-tui";
+
+const COLUMNS = 80;
+const ROWS = 24;
+const FRAMES = 60;
+const BURST = Number(process.argv[2] ?? 1);
+
+function fakeTerminal() {
+  return {
+    start() {}, stop() {}, async drainInput() {}, write() {},
+    get columns() { return COLUMNS; },
+    get rows() { return ROWS; },
+    get kittyProtocolActive() { return false; },
+    moveBy() {}, hideCursor() {}, showCursor() {}, clearLine() {},
+    clearFromCursor() {}, clearScreen() {}, setTitle() {}, setProgress() {},
+  };
+}
+
+/** The transcript: plain text only. Never emits a box-drawing glyph. */
+class Chat {
+  constructor() { this.lineCount = 0; }
+  render() {
+    return Array.from(
+      { length: this.lineCount },
+      (_, i) => `chat line ${String(i).padStart(3, "0")}`,
+    );
+  }
+}
+
+/** A bordered overlay, exactly the shape a transcript viewer paints. */
+class BoxOverlay {
+  render(width) {
+    const inner = width - 2;
+    const lines = [`╭${"─".repeat(inner)}╮`];
+    for (let i = 0; i < 8; i++) lines.push(`│${" ".repeat(inner)}│`);
+    lines.push(`╰${"─".repeat(inner)}╯`);
+    return lines;
+  }
+}
+
+const BOX_GLYPHS = /[╭╮╰╯│─]/;
+const stripAnsi = (s) => s.replace(/\x1b\[[0-9;]*m/g, "");
+
+function run({ withOverlay }) {
+  const tui = new TuiMainScreen(fakeTerminal(), false, "/tmp/pi733");
+  const chat = new Chat();
+  tui.addChild(chat);
+
+  if (withOverlay) {
+    tui.showOverlay(new BoxOverlay(), {
+      anchor: "center",
+      width: "90%",
+      maxHeight: "70%",
+    });
+  }
+
+  // What the terminal keeps for each row index, captured at the last frame in
+  // which that row was still on screen (and therefore still repairable).
+  const committed = new Map();
+
+  for (let i = 0; i < FRAMES; i++) {
+    chat.lineCount = (i + 1) * BURST;
+    tui.renderNow();
+    const { previousLines, previousViewportTop } = tui.captureRenderState();
+    for (let row = previousViewportTop; row < previousLines.length; row++) {
+      committed.set(row, previousLines[row]);
+    }
+  }
+
+  const finalTop = tui.captureRenderState().previousViewportTop;
+  return { committed, finalTop, fullRedraws: tui.fullRedraws };
+}
+
+function report(label, { committed, finalTop, fullRedraws }) {
+  const scrolledOff = [...committed.entries()].filter(([row]) => row < finalTop);
+  const contaminated = scrolledOff.filter(([, line]) => BOX_GLYPHS.test(line));
+
+  console.log(`\n--- ${label}`);
+  console.log(`  full redraws:               ${fullRedraws}`);
+  console.log(`  rows scrolled into history: ${scrolledOff.length}`);
+  console.log(`  ...committed WITH chrome:   ${contaminated.length}`);
+  for (const [row, line] of contaminated.slice(0, 3)) {
+    console.log(`    row ${String(row).padStart(2)}: ${JSON.stringify(stripAnsi(line).slice(0, 56))}`);
+    console.log(`            the Chat component rendered: ${JSON.stringify(`chat line ${String(row).padStart(3, "0")}`)}`);
+  }
+  return contaminated.length;
+}
+
+const withOverlay = report("WITH overlay", run({ withOverlay: true }));
+const control = report("WITHOUT overlay (control)", run({ withOverlay: false }));
+
+console.log("\n=== Result");
+console.log(
+  withOverlay > 0 && control === 0
+    ? `REPRODUCED: ${withOverlay} rows entered scrollback carrying overlay chrome.`
+    : `NOT REPRODUCED (with=${withOverlay}, control=${control}).`,
+);
+```
+
+At a burst of 10 it reports a row the `Chat` component rendered as `"chat line 013"` committed to history as `"chat╭─────…"` — the overlay having overwritten from column 4, its left margin.
+That is the signature operators see in scrollback.
+
+## An upstream report, if one is filed
+
+Nobody has filed this upstream, and this repository does not depend on anyone doing so.
+The text below is kept ready rather than pending.
+
+```markdown
+Title: Regular-mode overlays composite into the scrollback buffer, baking chrome into history
+
+In `TuiMainScreen.doRender`, overlays are composited into `newLines` before the
+differential compare, and that composited array becomes `previousLines`
+(`tui-main-screen.ts:267`, assigned at `:314`, `:440`, and `:611`). The renderer's
+model of the transcript at those rows is the overlay.
+
+While output is appended a line at a time the band is repaired as it moves, so
+nothing is lost. The failure needs a single append large enough to carry a row from
+under the overlay past the top of the screen: that row is committed to scrollback
+with the chrome in it, and differential rendering can no longer reach it.
+
+Measured on 0.84.4, 24-row terminal, 10-line centered overlay: zero contamination
+for appends of 7 lines or fewer; 57 rows at 8; 171 of 576 at 10. The threshold of 8
+is one more than the distance from the overlay's top edge to the top of the screen,
+which is the row count needed to carry a row off screen. An identical
+control run without the overlay commits none.
+
+Repro script, public API only, no monorepo checkout needed: <attached>
+```
+
+[#733]: https://github.com/gotgenes/pi-packages/issues/733
+[#864]: https://github.com/gotgenes/pi-packages/issues/864
+[#874]: https://github.com/gotgenes/pi-packages/issues/874
+[earendil-works/pi#2759]: https://github.com/earendil-works/pi/issues/2759
+[earendil-works/pi#4785]: https://github.com/earendil-works/pi/issues/4785

package/docs/decisions/0008-inherited-region-is-shared-parts.md

@@ -0,0 +1,81 @@
+---
+status: accepted
+date: 2026-09-08
+---
+
+# 0008 — The inherited region guarantees shared parts, not shared bytes
+
+## Status
+
+Accepted.
+Amends [ADR 0006], which stands: a child still inherits the parent prompt's identity region and nothing after it.
+What this record changes is the *goal* that placement serves, and the claim the package makes about it.
+
+## Context
+
+[#180] and [#400] moved the inherited parent prompt to the front of a child's prompt so the child's leading bytes would be **byte-identical** to the parent's, which prefix-caching providers and local inference engines reuse instead of reprocessing.
+[#180]'s reporter measured 8,333 shared tokens costing roughly 40 seconds on a local model.
+[ADR 0006] then narrowed what is inherited to the identity region, on the reasoning that everything after it is resolved per session.
+
+[#890] found that the goal, stated that way, was not being met and in one important case could not be.
+
+### The tool list sits inside the region
+
+`@gotgenes/pi-permission-system` narrows a session's `Available tools:` listing to the tools policy allows.
+That listing is at offset 171 of Pi's preamble — inside the identity.
+Rewriting it in place ended the shared prefix there for every child whose allowed set differed from its parent's: measured at **365 shared characters of a 57,423-character identity** in this repo's configuration, and reported from the field as a divergence at offset 412 of a 22,157-character prompt ([#890]).
+
+Neither package was misbehaving.
+A shared identity and an honest per-session tool list cannot coexist while the list lives inside the identity.
+
+### The byte-identical claim was unscoped
+
+Anthropic builds its cache prefix in the order `tools`, `system`, `messages`, and modifying tool definitions "invalidates the entire cache".
+The `tools` array precedes the system prompt, so **any** child whose tool array differs from its parent's gets no cache hit from a byte-identical system prompt — which is every child with a narrowed `tools:` list, and every child at all, since the core installs `ask_parent`/`notify_parent` that no parent has.
+
+On the Anthropic OAuth path there is a second, independent break: `@gotgenes/pi-anthropic-auth` prepends a billing block as system block 0 whose hash is derived from the first user message, and a parent and child never share one.
+
+The property pays where tool definitions are rendered *after* the system text — local inference engines whose chat template does so, which is [#180]'s own constituency, and API-key Anthropic with an identical tool array.
+The package had never said so.
+
+## Decision
+
+The inherited region guarantees **shared parts, not shared bytes**, and the benefit is scoped to hosts that reuse a prefix over the system text independently of the tool definitions.
+
+Concretely:
+
+1. `buildAgentPrompt` continues to place the inherited identity first, verbatim, and to cut at the first per-session layer ([ADR 0006] is unchanged in mechanism).
+2. Per-session **prose about the tool surface does not belong in that region.**
+   An extension that must state a session's tools states them after the layers a child inherits, so each session speaks for itself and none edits another's bytes.
+   `pi-permission-system` implements this in [its ADR 0014].
+3. The package documents the property as a shared leading prefix whose value is host-dependent, not as an unconditional byte-for-byte guarantee.
+
+### The bridge block goes with it
+
+The `<sub_agent_context>` block append mode injected is removed in the same change.
+It named `read`, `edit`, `write`, `find`, and `grep` unconditionally — instructing an `Explore` child, which has neither `edit` nor `write`, to use them — and duplicated the `promptGuidelines` Pi's own tools already contribute to every child's prompt.
+It was inherited verbatim from the upstream fork with no decision behind it.
+
+It sat after the identity, so removing it costs no prefix.
+
+## Consequences
+
+- The identity a child shares with its parent is now the full identity minus the relocated tool surface, rather than ending at the tool list.
+  A test pins it in this package (`buildAgentPrompt` opens with the inherited identity verbatim, in both modes), which the property had never had.
+- Append mode differs from replace mode only in the `<agent_instructions>` wrapper.
+- A child gets tool guidance for the tools it actually holds, rendered per session, instead of a fixed five-tool assertion.
+- **Accepted residual:** with `pi-permission-system` absent, nothing restates a child's tool list and it still inherits its parent's.
+  Tracked as [#901]; this package has no `before_agent_start` handler today, and adding one is that issue's work.
+- A consumer that projects a child's prompt by matching the parent's — `pi-claude-bridge` — is helped rather than hindered: the region it looks for is verbatim again.
+  That interaction is recorded, with what remains unverified, in [its ADR 0014].
+- The region is still Pi's preamble, which a provider that re-homes the prompt into another harness carries into that harness's API.
+  [#883] is that case, and [ADR 0009] adds an opt-in `portable` strategy for it — scoped per provider, so the shared prefix this record restored stays the default everywhere else.
+
+[#180]: https://github.com/gotgenes/pi-packages/issues/180
+[#400]: https://github.com/gotgenes/pi-packages/issues/400
+[#890]: https://github.com/gotgenes/pi-packages/issues/890
+[#901]: https://github.com/gotgenes/pi-packages/issues/901
+[#883]: https://github.com/gotgenes/pi-packages/issues/883
+[ADR 0006]: 0006-inherited-prompt-is-identity-only.md
+[ADR 0009]: 0009-portable-inheritance-is-provider-scoped.md
+[its ADR 0014]: https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0014-tool-surface-is-node-local-prose.md

package/docs/decisions/0009-portable-inheritance-is-provider-scoped.md

@@ -0,0 +1,116 @@
+---
+status: accepted
+date: 2026-09-08
+---
+
+# 0009 — Portable inheritance is opt-in and scoped to the provider
+
+## Status
+
+Accepted.
+Extends [ADR 0006] and [ADR 0008], both of which stand: a child still inherits the parent prompt's identity region and nothing after it, and that region still guarantees shared parts rather than shared bytes.
+What this record adds is a second strategy for the case where inheriting the region is not merely worthless but harmful, and it settles what selects between them.
+
+## Context
+
+[#883] reported a `pi-subagents` child failing its first API call with `400 Third-party apps now draw from your extra usage`, while its parent — same machine, same OAuth token, same Claude Code binary — passed.
+
+The chain, bisected by the reporter and independently corroborated by `pi-claude-bridge`'s own `diag/EXTRA-USAGE-400.md`:
+
+1. `buildAgentPrompt` places the parent's identity region first in the child's prompt.
+   That region opens with Pi's base preamble, which includes a documentation-routing line naming `custom providers (docs/custom-provider.md)` and `pi packages (docs/packages.md)`.
+2. `pi-claude-bridge` projects a session's system prompt into Claude Code's `--append-system-prompt`, so the child's copy of that line reaches Anthropic.
+3. Anthropic's subscription OAuth gate scores the appended text.
+   The two phrases **together** trip it; either alone passes, and substituting `banana packages` for `pi packages` passes.
+4. Classified as a third-party app, the request draws from extra usage — a hard 400 on an account with none.
+
+The parent passes because the bridge's projection carries only its portable parts; Pi's base never reaches the API on that path.
+
+### Why the region cannot simply be narrowed further
+
+The offending line is in Pi's base preamble, which `inheritedIdentity` keeps by construction — the cut is at the *first per-session layer*, and the preamble precedes all of them.
+Cutting further would not be a boundary any principle draws; it would be a blocklist of phrases one provider currently dislikes.
+
+### The benefit being traded away is real, and recently restored
+
+[#180] and [#400] placed the inherited region first so a child's leading bytes match its parent's, which prefix-reusing inference engines reuse instead of reprocessing — [#180]'s reporter measured 8,333 shared tokens at roughly 40 seconds on a local model.
+[#890] found `@gotgenes/pi-permission-system` had been rewriting that region in place and moved the tool surface out, restoring the shared prefix from 365 characters to about 57,000 in this repo's configuration.
+
+So a strategy that discards the region is correct for a re-homing host and a regression for a local-inference host.
+The two cannot share a default.
+
+## Decision
+
+A second strategy, `portable`, is available and **off by default**, selected per provider.
+
+### The identity is the operator's own text
+
+A `portable` child's identity is composed from the parent's operator-authored prompt parts, in the order Pi's own `buildSystemPrompt` composes them: the custom prompt, the appended prompt, then the `<project_context>` block.
+The result is what Pi would assemble for a session with a custom prompt and no tools or skills.
+
+Three of Pi's `BuildSystemPromptOptions` fields are excluded, each for a reason already settled:
+
+- `skills` — the child loads its own catalogue ([ADR 0006]).
+- `promptGuidelines` — Pi derives it per session from the tools actually in the registry, so inheriting the parent's asserts guidance for tools the child may not hold.
+  That is the defect [ADR 0008] removed with the `<sub_agent_context>` block.
+- `selectedTools` and `toolSnippets` — the tool surface is node-local prose ([its ADR 0014]).
+
+Context files are **included**, and load-bearing: `createSubagentSession` builds the child's loader with `noContextFiles: true`, so this is the only way a portable child sees project instructions at all.
+
+### The provider selects the strategy, not the agent
+
+```json
+{ "promptInheritance": { "claude-bridge": "portable" } }
+```
+
+Re-homing is a property of the **transport**, not of the agent.
+An agent has no opinion about prompt inheritance; a provider has a requirement.
+
+Keying on the agent — a frontmatter `inherit_prompt`, which the contributed reference implementation ranked above the provider rule — resolves wrongly under a per-spawn `model` override: an agent declaring `portable` because its own `model:` names a bridge model keeps that strategy when spawned onto the raw API, discarding the parent identity for a transport that never needed it.
+Keying on the child's resolved provider is correct by construction, because the override changes the provider and therefore the strategy, with nothing to keep in sync.
+
+A provider-**declared** policy would be better still — the provider knows whether it re-homes — but is not reachable: Pi's `ProviderConfigInput` carries no policy field.
+The settings map is the available seam, not the preferred one.
+
+### The default does not change
+
+Every provider the map does not list inherits `full`.
+Flipping the default would change every existing child's prompt on a routine upgrade with no user edit, undo [#890]'s just-restored prefix for [#180]'s constituency, and — for a user without `pi-permission-system` — trade [#901]'s wrong tool list for no tool list at all, which is [#901]'s decision to make.
+
+There is deliberately **no global default arm** on the setting.
+A `"default": "portable"` would let one entry silently switch a local-model child, which is exactly the harm above; a re-homing host is per-provider by definition, so the map alone expresses every real case.
+
+### An unusable capture never falls back to the full prompt
+
+An absent or whitespace-only portable capture falls back to the generic base, never to the parent's assembled prompt.
+Opting into portable must never silently re-embed the harness base it exists to avoid.
+
+## Consequences
+
+- A child on a listed provider carries none of Pi's base preamble, so a host that re-homes its prompt sees only text that host's own harness would have produced.
+- `portable` is correct **only** where the host supplies its own base, and this is documented rather than enforced — Pi exposes no way to identify a re-homing provider.
+  Pointed at a provider that does not re-home, it is worse than `full`: `@gotgenes/pi-anthropic-auth` locates Pi's role line to shape the OAuth prompt and returns it unchanged when that line is absent, so such a child loses the neutral role prompt shaping would have substituted and gains nothing.
+- The `full` path is unchanged, so [ADR 0008]'s guarantee and its pinning test are untouched.
+- A child that resolved no model resolves to `full`.
+  This is defensive rather than reachable: Pi leaves the model unset only when no authenticated model exists at all, and such a parent cannot run a turn, emits no `before_agent_start`, and holds no capture to render.
+- This package now registers a `before_agent_start` handler, its first.
+  It stores the capture and returns nothing, so [#901]'s planned handler extends it rather than competing with it.
+- **Accepted residual:** a portable child whose parent has no context files, custom prompt, or append prompt falls back to `genericBase`, which claims write and exec capability a read-only child does not hold.
+  Tracked as [#904].
+- `pi-claude-bridge` is fixing the projection on its own side ([bridge#89]), which would resolve [#883] for bridge users specifically.
+  `portable` remains the answer for any other re-homing host with no projection to fix.
+
+The bisection and replay methodology that established the discriminator are `elidickinson`'s, in `pi-claude-bridge`'s `diag/EXTRA-USAGE-400.md`.
+The capability, the capture seam, and the fail-safe fallback are @georgeharker's, contributed in [#884].
+
+[#180]: https://github.com/gotgenes/pi-packages/issues/180
+[#400]: https://github.com/gotgenes/pi-packages/issues/400
+[#883]: https://github.com/gotgenes/pi-packages/issues/883
+[#884]: https://github.com/gotgenes/pi-packages/pull/884
+[#890]: https://github.com/gotgenes/pi-packages/issues/890
+[#901]: https://github.com/gotgenes/pi-packages/issues/901
+[#904]: https://github.com/gotgenes/pi-packages/issues/904
+[ADR 0006]: 0006-inherited-prompt-is-identity-only.md
+[ADR 0008]: 0008-inherited-region-is-shared-parts.md
+[its ADR 0014]: https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0014-tool-surface-is-node-local-prose.md
+[bridge#89]: https://github.com/elidickinson/pi-claude-bridge/pull/89

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@jopqior/pi-subagents",
+  "version": "1.0.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/public.d.ts",
+      "default": "./src/service/service.ts"
+    },
+    "./settings": {
+      "types": "./dist/settings.d.ts",
+      "default": "./src/layered-settings.ts"
+    }
+  },
+  "files": [
+    "src",
+    "dist",
+    "docs/*.md",
+    "docs/architecture",
+    "docs/decisions",
+    "CHANGELOG.md"
+  ],
+  "imports": {
+    "#src/*": "./src/*",
+    "#test/*": "./test/*"
+  },
+  "description": "A focused, in-process sub-agent core for pi — autonomous agents plus a typed API and lifecycle events other extensions build on. Friendly fork of @tintinweb/pi-subagents.",
+  "author": {
+    "name": "Chris Lasher"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jopqior/gotgenes-pi-packages.git",
+    "directory": "packages/pi-subagents"
+  },
+  "homepage": "https://github.com/Jopqior/gotgenes-pi-packages/tree/main/packages/pi-subagents#readme",
+  "bugs": {
+    "url": "https://github.com/Jopqior/gotgenes-pi-packages/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "subagent",
+    "agent",
+    "autonomous"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.75.0",
+    "@earendil-works/pi-coding-agent": ">=0.81.0",
+    "@earendil-works/pi-tui": ">=0.75.0"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.49"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.11",
+    "@earendil-works/pi-ai": "0.84.4",
+    "@earendil-works/pi-coding-agent": "0.84.4",
+    "@earendil-works/pi-tui": "0.84.4",
+    "@types/node": "^22.15.3",
+    "rollup": "^4.63.1",
+    "rollup-plugin-dts": "^6.5.1",
+    "rumdl": "0.2.24",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.11"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "video": "https://github.com/gotgenes/pi-subagents/raw/main/media/demo.mp4",
+    "image": "https://github.com/gotgenes/pi-subagents/raw/main/media/screenshot.png"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "build:types": "rollup -c rollup.dts.config.mjs",
+    "verify:public-types": "bash scripts/verify-public-types.sh",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint:md": "rumdl check *.md docs/**/*.md",
+    "lint": "biome check . && eslint . && pnpm run lint:md"
+  }
+}