@jopqior/pi-subagents 1.0.0

package/docs/decisions/0002-extensions-on-a-minimal-core.md

@@ -0,0 +1,125 @@
+---
+status: accepted
+date: 2026-05-29
+---
+
+# 0002 — Workspaces and permissions are extensions on a minimal core
+
+## Status
+
+Accepted.
+Supersedes the "agent collaborator architecture" framing of Phase 16 (an abandoned exploration) and the work shipped under it: issue #256 (`WorktreeIsolation` as an `Agent` collaborator) and issue #257 (`ChildSessionFactory` extraction, parked at planning).
+Reclaims Phase 16's original intent — "invert dependencies" — and extends it to evict worktree isolation from the core.
+
+## Context
+
+The core question that triggered this decision: a single-method `ChildSessionFactory` with a `create(cwd?)` method (planned for #257) looked like it wanted to be a function, and the `cwd` parameter was late-bound.
+Pulling that thread exposed progressively more rudimentary issues.
+
+1. `cwd` is late-bound because `WorktreeIsolation.setup()` is called lazily inside `Agent.run()`, after construction — a two-phase `construct-then-setup()` that violates design principle 8 ("Construct complete").
+2. The worktree is *ready* only at dequeue (a concurrency slot is held and `git worktree add` has run).
+   "Construct when ready" therefore means constructing the worktree at run-start, not at spawn — which dissolves the lazy `setup()` and makes `cwd` knowable at construction.
+3. The worktree and the child session share one lifespan: both are born at run-start and torn down at completion (the worktree's cleanup saves a branch; the session is disposed).
+   Resources with one lifetime are one resource, not sibling collaborators that `Agent` must sequence.
+   The `create(cwd?)` parameter only existed because we split one run-scoped resource (the worktree) out and made `Agent` relay its output back in.
+4. Worktrees are not intrinsic to what makes subagents useful.
+   The maintainer never uses them (WIP-of-1, trunk-based, CI/CD).
+   Git worktree isolation is one *strategy* for answering "where does this child run, and what brackets the run?"
+   — a container, a throwaway tmpdir, or a remote sandbox are others.
+   The core needs only *a working directory and a disposal hook*; the default (the parent's cwd, no setup/teardown) is always correct.
+5. This mirrors Phase 14, which evicted tool/extension *policy* (`disallowed_tools`, `extensions` filtering) to `@gotgenes/pi-permission-system`.
+   Worktrees are *environment* policy; they belong outside the core for the same reason.
+
+Permissions and workspaces are orthogonal concerns that must compose as independent extensions on the core, never knowing about each other.
+
+## Decision
+
+pi-subagents is a minimal orchestrator: it spawns a child session derived from the parent, runs the turn loop, tracks and streams and collects the result, gates concurrency, supports resume, and **publishes its lifecycle**.
+Everything else attaches through exactly two extension surfaces, distinguished by the direction of information flow.
+
+### Two extension surfaces
+
+1. **Lifecycle events (observational) — unlimited.**
+   The core emits awaited, ordered events for the child-execution lifecycle (`spawning`, `session-created` pre-`bindExtensions`, `bound` post-`bindExtensions`, `completed`, `disposed`).
+   Any number of extensions subscribe; handlers return nothing.
+   Reactive concerns live here: permission detection, telemetry, UI, notifications.
+   Adding a reactive concern never modifies the core.
+
+2. **Provider seams (generative) — rationed.**
+   The rare concern that must *inject* a value the core consumes synchronously registers a provider the core consults.
+   Today there is exactly one: the **workspace provider** (it returns the child's working directory plus bracketed setup/teardown).
+   A provider seam is the only place the core is "open," so the list is kept as small as possible.
+
+### The discriminator
+
+When deciding how a concern attaches:
+
+- It only needs to **know** what happened → subscribe to a lifecycle event (observational, unlimited).
+- It must **return a value the core consumes** → register a provider (generative, rationed).
+
+Permissions are observational: the core does not enforce policy; it publishes the child's identity at the pre-bind instant so the permission extension (loaded in the child) can detect "am I a subagent?"
+and gate tool calls at runtime.
+Workspaces are generative: the core cannot default the cwd away when an isolation strategy is requested, so the provider hands it back.
+
+### The governing rule: no vacant hooks
+
+The architecture must *admit* a seam without *shipping* it until a concrete consumer exists.
+A provider seam with no consumer is not extensibility — it is a speculative abstraction that taxes every reader, and `fallow` flags it as dead.
+Latent extensibility (the design can host the seam additively) is the deliverable; a vacant hook is not.
+
+### What leaves the core
+
+- **Worktree isolation** (`worktree.ts`, `worktree-isolation.ts`, `GitWorktreeManager`, the `isolation: "worktree"` spawn mode) → a new package, `@gotgenes/pi-subagents-worktrees`, that implements the workspace provider and owns the git plumbing and the "saved to branch" result.
+- **`permission-bridge.ts`** → retired.
+  The core stops reaching *out* to `Symbol.for("@gotgenes/pi-permission-system:service")` and instead *emits* lifecycle events the permission system subscribes to.
+- **`isolated` / `extensions: false` / `noSkills`** → removed.
+  Deny-at-use (the in-child permission layer blocking disallowed tool calls) covers what `isolated` pretended to do for tools.
+  Prevent-load (refusing to bind an extension because of load-time side effects, cost, or true sandboxing) is genuinely generative and cannot be reduced to observation, so it is left as a *latent* (un-built) provider seam, added only if a real consumer needs it.
+
+### What stays in the core (not policy)
+
+- The **recursion guard** (stripping the core's own `subagent` / `get_subagent_result` / `steer_subagent` tools from children).
+  It defends the core's own invariant — a subagent must not recursively spawn — keyed off the core's own tool names.
+  With `isolated` gone, children always load the parent's resources, so the guard becomes unconditional rather than gated on `cfg.extensions`.
+
+### Composition test
+
+Install neither extension, only permissions, only workspaces, or both: the core is byte-for-byte identical in all four cases, and the two extensions never reference each other.
+Permissions depend only on the core's events; workspaces depend only on the core's provider seam; the core depends on neither.
+
+## Consequences
+
+- The "agent collaborator architecture" Phase 16 (give `Agent` a worktree collaborator + a session factory) is abandoned.
+  #256 is superseded (worktree was placed in the wrong layer); #257 is parked (it polished a subsystem slated for eviction).
+- A new package `@gotgenes/pi-subagents-worktrees` is introduced; the core spawn API drops `isolation` and `isolated`.
+- `permission-bridge.ts` is removed; `@gotgenes/pi-permission-system` migrates from a published-service lookup to lifecycle-event subscription, which requires the core to emit an awaited, ordered `session-created` event before `bindExtensions()`.
+  Confirming Pi's event model supports awaited pre-bind emission is the first investigation of the reclaimed phase.
+- Once the cwd is resolved through the provider seam rather than relayed by `Agent`, child-session creation can construct a born-complete execution and the "runner" concept dissolves — recovering the structural goal of the abandoned collaborator steps by a cleaner route.
+- The reclaimed Phase 16 roadmap and step issues live in [`docs/architecture/architecture.md`](../architecture/architecture.md).
+
+## Amendment: prevent-load ships as a settings key, not a provider seam (#696)
+
+This decision reserved prevent-load as a *latent* provider seam, "added only if a real consumer needs it."
+A real consumer arrived: in-process children reloaded `@cortexkit/pi-magic-context`, whose per-session initialization scans the whole Pi session store, and four concurrent children exhausted the V8 heap in the shared process.
+
+The seam was nonetheless **not** built.
+The governing rule above — no vacant hooks — decides it: a provider seam is warranted when an *extension* must inject a value the core consumes, and no extension wants to supply a prevent-load policy.
+The only policy source is the operator's configuration, so a registerable provider whose sole consumer would be pi-subagents' own settings reader is precisely the speculative abstraction this ADR forbids.
+
+The core therefore reads an `excludedExtensionPackages` list from the layered `subagents.json` and filters the child's package view before resource loading.
+This is narrower than the per-agent policy Phase 14 evicted: it is global/project scope only, never per agent type; it names packages rather than individual extensions or tools; and it carries no tool-permission semantics, which remain deny-at-use in `@gotgenes/pi-permission-system`.
+Default inheritance is unchanged — an absent or empty list reproduces prior behavior exactly.
+
+Latent extensibility is preserved rather than spent.
+The filtering is applied at the composition root, so if a sandboxing extension ever needs to supply the policy generatively, a provider seam can be added additively without disturbing the settings key or the assembly factory.
+
+## Amendment: the child-announcement contract is specified downstream (#789)
+
+This decision required the core to emit an awaited, ordered `session-created` event before `bindExtensions()`, and the channel names and payload shapes were then declared independently in this package and in `@gotgenes/pi-permission-system`, each with a comment asking that they stay in sync.
+
+That arrangement ends here.
+The contract is now named — the **subagent adapter convention** — and specified in one place: [Subagent Integration](https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/subagent-integration.md#the-subagent-adapter-convention), per pi-permission-system's [ADR 0012](https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0012-cross-node-extension-contract.md) decision 5.
+Read it there rather than reconstructing it from this record.
+
+Nothing about this package's obligations changed: the core still publishes its lifecycle and knows nothing about its consumers, and the inverted dependency this decision established is untouched.
+What changed is that the convention now has a canonical home, and any implementation — not only this one — can conform to it.

package/docs/decisions/0003-publish-bundled-type-declarations.md

@@ -0,0 +1,71 @@
+---
+status: accepted
+date: 2026-05-29
+---
+
+# 0003 — Publish a bundled `.d.ts` for the public surface
+
+## Status
+
+Accepted.
+Introduces the repository's first build step, scoped to type declarations only.
+
+## Context
+
+`@gotgenes/pi-subagents` could not be imported by another TypeScript package in this workspace.
+Issue #263 (extract worktree isolation to `@gotgenes/pi-subagents-worktrees`) is the first intra-repo consumer: it must `implements WorkspaceProvider` and call `getSubagentsService().registerWorkspaceProvider(...)`, both of which require importing the package by name.
+
+A `tsc --traceResolution` of a sibling consuming the package surfaced two compounding failures.
+
+1. `package.json` `exports["."]` pointed at `./src/service.ts`, which does not exist — the real module is `./src/service/service.ts`.
+   A latent bug, unnoticed because nothing in-repo imported the package by name.
+2. Once corrected, the public entry's internal alias imports cascade.
+   `service/service.ts` imports `type LifetimeUsage` and `type WorkspaceProvider` via the `#src/*` alias.
+   When a sibling's `tsc` follows the symlink, the consumer's own `paths` (`#src/*` → `./src/*`) intercept first and resolve into the *consumer's* `src/` — a global-`paths` collision, since both packages define `#src/*`.
+   The fallback to the publisher's `package.json` `imports` field also fails: `tsc` cannot resolve the extensionless `.ts` target under Node `imports` semantics ("Import specifier '#src/lifecycle/usage' does not exist in package.json scope").
+
+The public entry's type closure is deeply entangled: `WorkspaceProvider` (in `lifecycle/workspace.ts`) reaches `AgentStatus` in the 510-line `lifecycle/agent.ts`, plus `SubagentType`/`AgentInvocation` from `types.ts` (which itself re-exports the `Agent` class).
+A shallow alias-free entry is therefore not achievable without a substantial source restructure.
+
+This collides with the ship-source model ([ADR-0002]): every package ships raw `.ts` executed directly by Pi, with no build step.
+
+## Decision
+
+Emit a single, self-contained `dist/public.d.ts` for the public surface and advertise it through a `types` export condition, while the runtime entry continues to serve `.ts` source.
+
+```jsonc
+"exports": {
+  ".": {
+    "types": "./dist/public.d.ts",
+    "default": "./src/service/service.ts"
+  }
+}
+```
+
+- `rollup-plugin-dts` rolls the declaration graph rooted at `src/service/service.ts` into one file, inlining the internal `#src/*` types and keeping peer-dependency types (`@earendil-works/*`, `@sinclair/typebox`) external.
+  We ship `.ts` source, so only the declaration bundle is emitted — no JS.
+- The bundle is generated at `prepack` time and shipped via a `files` allowlist; it is gitignored and never committed.
+- `default` → `./src/service/service.ts` fixes the stale path and serves runtime consumers; its `import type` lines erase, so no runtime `#src/*` resolution is needed.
+- A `pnpm pack` → throwaway-consumer → `tsc` harness proves external consumability with no publish round-trip and no workspace privileges.
+
+This is the repository's first build step.
+It is deliberately narrow: it produces type declarations only and changes nothing about how Pi loads the extension from source (`pi.extensions: ["./src/index.ts"]` is untouched).
+
+## Alternatives considered
+
+- Alias-free public entry (restructure the source so the entry's full type closure resolves via same-directory `./` imports).
+  Mechanically possible, but it requires moving the `AgentStatus`/`SubagentType`/`AgentInvocation`/`WorkspaceProvider` definitions and untangling the `agent.ts`/`types.ts` graph, with care that inner layers do not import the outer service layer.
+  `eslint`'s `no-parent-relative-imports` rule (which forbids `../`) narrows the options further.
+  Larger blast radius than emitting a `.d.ts`, and it churns the domain model to serve a packaging concern.
+- A self-contained entry that re-declares the public types inline, guarded by a conformance test.
+  Avoids a build step but duplicates the seam/usage/status type definitions, which drift over time.
+
+## Consequences
+
+- The repository now has a build step, but it is type-only and isolated to this package; the ship-source model is otherwise intact.
+- Consumers (including `@gotgenes/pi-subagents-worktrees` in #263) consume the packaged public interface like any external developer — no `workspace:*` privileges.
+- The `types` condition points at a build-time artifact; an in-repo workspace-linked consumer that imported the package would need `dist/public.d.ts` present.
+  This is acceptable because no in-repo package imports the surface yet; #263 consumes the built artifact from the published tarball.
+- Sequencing: #270 must be published (its release-please PR merged) before #263 edits `pi-subagents` core, so #263's changes do not batch into the same `pi-subagents` release.
+
+[ADR-0002]: ./0002-extensions-on-a-minimal-core.md

package/docs/decisions/0004-reconsider-ui-direction.md

@@ -0,0 +1,279 @@
+---
+status: accepted
+date: 2026-06-18
+---
+
+# 0004 — Reconsider the UI direction from first principles
+
+## Status
+
+Accepted.
+Completes Phase 18 (reconsider the UI) and gateways Phase 19 (implement the recorded decisions).
+Decision-only: this ADR changes no runtime code.
+The inherited UI stays live until Phase 19 acts on these decisions.
+
+## Context
+
+Phase 18's spine (Steps 1–7, #420 through #426) disentangled the activity tier from the core.
+The core now owns all run state in one place (`SubagentState`), the widget self-drives from lifecycle events, the LLM-facing `subagent` tool no longer depends on the widget, and the public event contract's declared channels equal its emitted channels.
+The UI is therefore a pure reactive consumer of the broadcast-plus-query surface — _substitutable_.
+
+This final step decides the UI's _direction and distribution_, not whether substitution is possible.
+The goal is **substitutable, not optional**: a human needs some surface, but the specific UI is replaceable — the way Pi ships a default TUI built on the same public API any extension targets.
+The disentangled core stays byte-for-byte identical whether or not a given UI consumer is installed (the composition invariant), so a replacement UI is a downstream concern even though _some_ UI is not.
+
+Unlike the worktrees provider seam (generative, rationed — one provider the core consults), the UI is an observational consumer (unlimited, the core never waits on it).
+That asymmetry is why packaging the UI is the secondary question and decoupling it was the real win.
+
+Three operator-framed concerns shape the per-component judgment.
+
+1. **Foreground progress is already shown by the tool call.**
+   In foreground the `subagent` tool's inline `onUpdate` stream renders progress well; the above-editor widget duplicates it.
+2. **Background agents have no tool-call display.**
+   When agents run in the background there is no inline stream, so _something_ must indicate their state — and multiple subagents can run in parallel, so that surface must represent N concurrent agents at once.
+3. **Operator visibility into a subagent's session is a distinct, richer need.**
+   "Switch into a subagent's session, scroll/read it, switch between subagents, and exit back to root" is a navigation interaction, not a live overlay.
+   The core already persists each child as a standalone Pi session JSONL at `Subagent.outputFile`, and `Subagent.messages` exposes the full history — so the data was never the limit; the bespoke, width-capped `ConversationViewer` overlay was.
+
+### Relevant Pi SDK surface
+
+Verified against `@earendil-works/pi-coding-agent@0.79.1`:
+
+- `ExtensionActions.switchSession(sessionPath, { withSession })` switches the **active** session to a different session file.
+  It is a full active-session takeover: it fires `session_before_switch` / `session_shutdown`, invalidates the current session context (`setBeforeSessionInvalidate` exists for host-owned UI teardown), and returns `{ cancelled }`.
+  The switched-to session is fully interactive — `ReplacedSessionContext` exposes `sendUserMessage`.
+- `session-manager` exports `loadEntriesFromFile(filePath)` / `parseSessionEntries(content)`, which read a session file's entries without switching — the read-only alternative to a full takeover.
+
+## Decision
+
+Judge each UI component on the first principles above, then record the distribution.
+
+### A — Foreground widget: shrink to background agents only
+
+The above-editor widget duplicates the foreground tool's inline `onUpdate` stream.
+The widget survives **only** as the background-agent status surface (concern 2): foreground runs suppress it, the inline stream is authoritative there, and the background surface keeps the widget's existing per-agent tree so it represents N parallel agents at once.
+The change is _when_ the widget shows (background-only), not _what_ it shows.
+
+### B — Conversation viewer: replace the bespoke overlay with native session navigation
+
+Remove the bespoke `ConversationViewer` overlay.
+Operator visibility (concern 3) is served by Pi's own session machinery applied to the already-persisted child session file, not a hand-rolled transcript renderer — the recursive-Pi insight applied to `Subagent.outputFile`.
+
+The illustrative call shape (Phase 19, not final):
+
+```typescript
+// "View running agents" → pick a child → switch into its persisted session
+const child = manager.getRecord(id);
+if (child?.outputFile) {
+  await ctx.switchSession(child.outputFile);
+  // operator reads/scrolls in Pi's native viewer; a later switch returns to root
+}
+```
+
+This is Tell-Don't-Ask (hand Pi the session path; Pi owns the viewer) and keeps the core free of transcript-rendering code.
+
+This decision records the _direction_ (native session machinery over a bespoke renderer), not the _mechanism_.
+`switchSession` is a full active-session takeover and is interactive, so the operator UX is gated on a Phase 19 spike that chooses between (i) true `switchSession` round-trips and (ii) a read-only transcript built from `loadEntriesFromFile` that renders Pi-standard entries without leaving the root session.
+See "Phase 19 entry criteria."
+
+### C — `/agents` menu: dissolve the monolithic command into focused surfaces
+
+The single `/agents` command bundles four unrelated jobs; split them, and do not keep all in one command.
+Managing agent _definitions_ through the menu earns no keep — creating or editing agents is better done with other tools (directly in Pi, or a real text editor / IDE).
+
+- **Create new agent (wizard)** → **remove.**
+  An operator generates a new agent `.md` by asking a Pi agent directly (more capable than a fixed wizard) or by writing the file in an editor.
+- **Agent types (list + config editor)** → **remove.**
+  Viewing and editing agent definitions is better served by opening the `.md` files directly in an editor/IDE.
+- **Running agents (visibility)** → **keep the responsibility, re-home it.**
+  _Something_ must own running-agent visibility; it moves onto the background widget (Decision A) plus the native session navigation (Decision B), not a bespoke in-menu overlay.
+- **Settings (concurrency / max turns / grace turns)** → **extract to a focused command** (e.g. `/subagents:settings`).
+  Some value, but it does not belong bundled with agent management.
+
+### D — Distribution: keep the surviving UI in-core (substitutable, not extracted)
+
+The spine already made the UI substitutable; a replacement UI is a downstream concern that targets the public broadcast-plus-query surface.
+The surviving UI — the background widget, a focused settings command, and the session-navigation glue — **stays in-core** as a reactive consumer.
+Extraction to a separate `@gotgenes/pi-subagents-ui` package is **not** chosen now.
+
+This answers the issue's headline question — the UI's _distribution_ — with "keep in core, substitutable," recorded explicitly rather than left implicit.
+Extraction remains an available future option precisely because the composition invariant holds: the core is byte-for-byte identical with or without a given UI consumer.
+It would be revisited if a second, materially different UI consumer appears, or if the in-core UI starts to pull SDK or rendering concerns back into core modules.
+
+## Consequences
+
+- The inherited UI is no longer preserved by default; each component now has a recorded fate (shrink / replace / dissolve) motivated by the first principles, not by inheritance.
+- Phase 18 is complete.
+  This ADR gateways Phase 19, which implements the decisions (background-only widget, native session navigation, `/agents` decomposition, `/subagents:settings` extraction) under its own plan and issues.
+- No interim regression: this ADR removes nothing.
+  The widget, the `ConversationViewer`, and the full `/agents` menu stay live until Phase 19 replaces them.
+- Phase 19 must preserve the spine's invariants when it acts on these decisions: the runtime holds zero UI state (#422), the widget is a reactive consumer with no inbound calls from core spawn tools (#423), the LLM tool depends only on manager/runtime/settings/registry (#424), and declared event channels equal emitted channels with no vacant hook (#425).
+  These are pinned today by the existing observer/widget/event-contract suites, which Phase 19 inherits.
+
+## Phase 19 entry criteria
+
+The following are open and must be resolved by a Phase 19 spike before committing to a mechanism; they are deliberately not decided here.
+
+- **Root-continuity during a session switch.**
+  `switchSession` invalidates the current session context — does the root's in-flight turn survive a switch-out-and-return, and what is the correct "return to root" gesture?
+  Resolve before committing to true `switchSession` round-trips.
+- **View-only vs interactive.**
+  A switched-to child session is interactive (`sendUserMessage`).
+  Decide whether steering a child from its own session is desirable, or whether the viewer should be strictly read-only (favoring the `loadEntriesFromFile` transcript path).
+- **Parallel-agent navigation.**
+  With N background agents running, decide the operator's gesture to pick which child to view and to cycle between them — driven from the background widget, a dedicated command, or both.
+- **Settings command namespace.**
+  Confirm the final command name/namespace for the extracted settings surface (`/subagents:settings` vs another form) against how sibling packages register namespaced commands.
+
+The agent create/edit surfaces are **not** open questions: both are removed (Decision C).
+
+## Addendum (2026-06-20): Phase 19 entry-criteria answers ([#446])
+
+The Phase 19 Step 1 spike ([#446]) resolved all four entry criteria.
+Evidence comes from the bundled `@earendil-works/pi-coding-agent` SDK surface (`packages/pi-subagents/node_modules/@earendil-works/pi-coding-agent/dist`) and a throwaway vitest harness run against a **real child session JSONL** (a 43-entry subagent session: 1 `session` header carrying a `parentSession` backref, 1 `model_change`, 1 `thinking_level_change`, 40 `message` entries).
+The harness was discarded after observation; no production source changed.
+
+### Finding 0 — `loadEntriesFromFile` is not part of the package's public surface
+
+The original "Relevant Pi SDK surface" section cited `loadEntriesFromFile` as the read-only alternative to a switch.
+The spike found it is **not reachable** from `@earendil-works/pi-coding-agent`, and that this is not a types/runtime mismatch — the type barrel and the runtime barrel agree, both omitting it.
+`loadEntriesFromFile` is defined in the deep module `core/session-manager.ts` (annotated `/** Exported for testing */`), but the public barrel `src/index.ts` (→ `dist/index.d.ts` + `dist/index.js`) re-exports only a curated subset of that module — including `parseSessionEntries` but **not** `loadEntriesFromFile`.
+The `package.json` `exports` map exposes only `"."` → the barrel, so the deep import `@earendil-works/pi-coding-agent/dist/core/session-manager.js` is not a supported entry point either.
+`tsc` correctly rejects `import { loadEntriesFromFile } from "@earendil-works/pi-coding-agent"` with `TS2305: Module … has no exported member 'loadEntriesFromFile'`; the throwaway Vitest harness only reached a runtime `is not a function` because esbuild strips types without type-checking (the package's own `pnpm run check` would have caught it at compile time).
+This is not version-specific: the barrel omits it identically in both the pinned `0.79.1` and the latest `0.79.8`, so an SDK upgrade does not surface it — Step 4 should not chase one.
+The viable read-only path is therefore `parseSessionEntries(readFileSync(outputFile, "utf8"))` — `parseSessionEntries` _is_ public (both types and runtime) — which the harness confirmed returns the full `FileEntry[]` transcript with no session switch and no active-session mutation.
+Step 4 ([#445]) should read the file itself and call `parseSessionEntries`, not `loadEntriesFromFile`.
+
+Upstream references:
+
+- Barrel that omits it: [`packages/coding-agent/src/index.ts`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/index.ts).
+- Test-annotated definition: [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/core/session-manager.ts).
+
+### Finding 1 — the read-only transcript renders entirely on public Pi APIs (no bespoke renderer)
+
+The read-only path returns raw `FileEntry[]`, so _something_ must render them.
+The spike found that every piece needed to turn those entries into a Pi-standard transcript is already re-exported through the public root barrel — so Step 4 wires Pi's own machinery rather than re-implementing the formatting the bespoke `ConversationViewer`/`message-formatters.ts` carried.
+This matters because ADR-0004 Decision B's `switchSession` sketch implied "Pi owns the viewer"; the read-only path keeps that property at the _component_ level (Pi renders each entry) without the active-session takeover.
+
+The verified public pipeline (all symbols confirmed present in `dist/index.d.ts`, the root barrel):
+
+1. **Load** — `parseSessionEntries(readFileSync(record.outputFile, "utf8")): FileEntry[]` (Finding 0).
+2. **Bridge** — `buildSessionContext(entries, leafId?, byId?): SessionContext` turns the entries into `{ messages: AgentMessage[], thinkingLevel, model }`, handling tree traversal, compaction, and branch summaries along the path.
+   Note `buildSessionContext` takes `SessionEntry[]`, so drop the leading `SessionHeader` (`type: "session"`) that `parseSessionEntries` includes.
+3. **Render** — one of:
+   - **Text:** `serializeConversation(messages: Message[]): string` (from `core/compaction`) for a plain-text dump.
+   - **TUI:** the per-entry components `AssistantMessageComponent`, `UserMessageComponent`, `ToolExecutionComponent`, `BashExecutionComponent`, `CompactionSummaryMessageComponent`, `BranchSummaryMessageComponent`, `CustomMessageComponent`, `SkillInvocationMessageComponent` (from `modes/interactive/components`), plus `renderDiff`, for a scrollable native transcript.
+
+Unlike `loadEntriesFromFile`, all of these _are_ public (both types and runtime).
+So the read-only viewer is buildable end-to-end on supported APIs, and ADR-0004 Decision B's "keep the core free of transcript-rendering code" holds — the rendering is Pi's, imported, not hand-rolled.
+
+Upstream references:
+
+- Component barrel: [`packages/coding-agent/src/modes/interactive/components/index.ts`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/modes/interactive/components/index.ts).
+- `serializeConversation`: [`packages/coding-agent/src/core/compaction/utils.ts`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/core/compaction/utils.ts).
+
+### Criterion 1 — Root-continuity during a session switch: avoid the switch
+
+`switchSession` is a full active-session takeover: it fires `session_before_switch` (cancellable) and then tears the current runtime down via `session_shutdown` (whose `targetSessionFile` field marks a replacement-driven shutdown).
+The root's in-flight turn does **not** survive the takeover — the runtime that owns that turn is invalidated — and a "return to root" would require a second `switchSession(rootSessionFile)` that re-incurs the teardown on the way back.
+Because background agents run precisely while the operator keeps working at root, a true `switchSession` round-trip is hostile to a root with a turn in flight.
+
+**Answer:** do not use `switchSession` for navigation.
+The read-only transcript path (Criterion 2) sidesteps root-continuity entirely — it never touches the active session, so there is no return gesture to get wrong.
+
+### Criterion 2 — View-only vs interactive: read-only
+
+`ReplacedSessionContext` (handed to a `switchSession` `withSession` callback) extends `ExtensionCommandContext` and exposes `sendUserMessage`/`sendMessage`, so a switched-to child session is interactive.
+But operator visibility (concern 3) is framed as "switch in, scroll/read, switch between, exit back to root" — a navigation interaction, not a live steering overlay — and steering already has a home (`steer_subagent` tool / the widget).
+Adding in-session steering would create a second, redundant steering surface.
+
+**Answer:** the viewer is strictly **read-only**, loaded via `parseSessionEntries(readFileSync(record.outputFile))` (Finding 0) and rendered through Pi's public entry components (Finding 1) without leaving the root session.
+This also resolves Criterion 1 by construction.
+
+### Criterion 3 — Parallel-agent navigation: command-first
+
+With N background agents running, the operator needs a gesture to pick which child to view.
+The background widget (Decision A, [#444]) already represents N parallel agents as a per-agent tree, making it the natural eventual selection surface; a flat command gives a non-widget entry point that lists running background agents and lets the operator pick one keyed on `record.outputFile`.
+
+**Answer:** Step 4 ([#445]) ships a **command** as the primary, unit-testable selection surface (list background agents → pick → render that child's transcript read-only), with a widget gesture as an optional later enhancement.
+"Both" remains the eventual target; command-first is the Step 4 starting point because it does not depend on the widget shrink ([#444]) landing first.
+
+### Criterion 4 — Settings command name: `/subagents-settings`
+
+Sibling packages register flat, hyphenated command names with no `:` namespace: `registerCommand("agents", …)` (this package), `"colgrep-reindex"`, `"permission-system"`.
+A `/subagents:settings` form would be inconsistent with every existing command in the repo, and `/agents-settings` wrongly implies it manages agent definitions (which Decision C removes).
+
+**Answer:** confirm **`/subagents-settings`** (flat, hyphenated) for Step 2 ([#447]).
+Reject the tentative `/subagents:settings` and the `/agents-settings` alternative.
+
+### Net mechanism for Phase 19
+
+- Session navigation (Step 4, [#445]): a read-only transcript, surfaced through a flat command; no `switchSession`, no `loadEntriesFromFile`.
+  The pipeline is `parseSessionEntries(readFileSync(record.outputFile, "utf8"))` → drop the `SessionHeader` → `buildSessionContext(...).messages` → render via Pi's public entry components (`AssistantMessageComponent` / `ToolExecutionComponent` / … ) or `serializeConversation` (Findings 0 and 1).
+- Settings command (Step 2, [#447]): `/subagents-settings`.
+
+This keeps bespoke transcript rendering out of the package (rendering is Pi's own public components), adds no inbound call from the UI to the core, and preserves the Phase 18 spine invariants (#422–#425).
+
+## Addendum 2 (2026-06-20): Step 4 sourcing — live record plus file snapshot ([#445])
+
+This addendum revises the first addendum's Criterion 2 answer for Step 4 ([#445]).
+The "strictly read-only, file-only" sourcing and the "not a live overlay" framing are superseded by the dual-source decision below; everything else from the spike stands.
+
+**Why revise.**
+The spike's mechanism — `parseSessionEntries(readFileSync(record.outputFile))` read once — serves a _completed_ subagent well but is a frozen snapshot for a _running_ one: it shows only what was flushed to disk at open time and does not stream.
+The clarified desired behavior is to see the **live** activity of any subagent _and_ the activity of a completed subagent.
+The bespoke `ConversationViewer` being removed in Step 5 already delivers both — it subscribes to the live in-memory record (`record.subscribeToUpdates()`) and renders `record.messages` plus a streaming indicator built from `record.activeTools` / `record.responseText`.
+That liveness comes from the in-memory record, not the persisted file, so a file-only viewer drops it.
+
+**Decision — dual-source, one renderer.**
+Step 4 sources the transcript by liveness and renders both sources through the same Pi public entry components (Finding 1 holds — no bespoke renderer):
+
+- **Tracked agent (still in `manager.listAgents()`)** — render from the live in-memory record: `record.messages` for history, `record.subscribeToUpdates()` to re-render on streaming updates, and `record.activeTools` / `record.responseText` for the running-agent streaming indicator.
+  This is live.
+- **Evicted / untracked agent** — render from the file snapshot: `parseSessionEntries(readFileSync(record.outputFile, "utf8"))` → drop the `SessionHeader` → `buildSessionContext(...).messages` (Findings 0 and 1).
+
+Both sources yield `AgentMessage[]`, so a single Pi-component renderer serves both.
+
+**Type-boundary note.**
+`SubagentSession.messages` is deliberately widened to `readonly unknown[]` at the core boundary (`src/lifecycle/subagent-session.ts`), even though the underlying `_session.messages` is the SDK's `AgentMessage[]`.
+Step 4 should add a typed accessor that returns `AgentMessage[]` (or narrow at the boundary) rather than feeding `unknown[]` into Pi's components.
+This is a read accessor on the existing record — it adds no inbound call from the UI to the core and does not regress the Phase 18 spine invariants.
+
+**Still read-only (non-interactive).**
+The viewer remains strictly non-interactive: Criterion 2's anti-redundant-steering rationale stands (steering lives in the `steer_subagent` tool and the widget), and Criterion 1's rejection of `switchSession` is unchanged — "live" here means the in-memory subscription, not an active-session takeover.
+
+**Candidate set (revises Criterion 3).**
+The selection command lists **any subagent with a live record or a persisted session file** — foreground agents included, not only running background agents.
+This matches the bespoke viewer's current reach (gated on `record.isSessionReady()`, never background-filtered) and avoids an interim regression.
+A foreground agent is navigable only _after_ it completes — while it runs, the root turn is blocked on it — whereas a background agent is navigable live.
+The background widget ([#444]) remains the optional secondary selection gesture for background agents; the command is the primary, unit-testable surface.
+
+**Evicted-agent candidate set ([#463]).**
+Step 4b realizes the file-snapshot branch for fully-evicted agents.
+The candidate set is broadened via **manager-retained descriptors**, not a directory scan of the tasks directory: the persisted child session carries no subagent `type`/`description` (those live only on the in-memory record), so a scan yields degraded labels and parses every file per picker open.
+The cleanup sweep instead stashes a lightweight `EvictedSubagent` descriptor (label fields + `outputFile`, no messages) before disposing a record, preserving rich labels and bounded memory.
+This covers in-session evictions — the sweep's only targets, since a fresh manager per session never reloads prior-process subagents.
+The "render from the file snapshot" mechanism for an evicted agent (above) is unchanged; only the candidate-set _enumeration_ is pinned to descriptors.
+
+## Addendum 3 (2026-06-23): adopt the `subagents:` colon namespace, superseding Criterion 4
+
+This addendum reverses **Criterion 4**, which confirmed flat, hyphenated command names (`/subagents-settings`) and rejected `/subagents:settings`.
+The two registered commands are renamed: `/subagents-settings` → `/subagents:settings` and `/subagent-sessions` → `/subagents:sessions`.
+This is a breaking change to the command surface.
+
+**Why revise.**
+Criterion 4 surveyed only in-repo siblings (`agents`, `colgrep-reindex`, `permission-system`) and concluded a `:` namespace would be inconsistent with every existing command.
+That survey missed the broader Pi ecosystem: `@eko24ive/pi-ask` establishes the colon convention with `answer:again` and `ask:replay`, grouping a package's commands under a shared prefix.
+The colon namespace reads as a deliberate grouping gesture (`subagents:settings`, `subagents:sessions` clearly belong to one package) where the hyphen form blurs into an ordinary command name.
+The newer ecosystem signal outweighs the original in-repo-only consistency argument.
+
+**Scope.**
+This change is pi-subagents-only.
+Whether the colon convention becomes repo-wide (renaming `colgrep-reindex`, `permission-system`, etc.) is deferred — not decided here.
+`/agents` is intentionally left flat: it is slated for removal in the Phase 18 / Step 5 menu retirement, so namespacing it would be churn on a command being deleted.
+
+[#444]: https://github.com/gotgenes/pi-packages/issues/444
+[#445]: https://github.com/gotgenes/pi-packages/issues/445
+[#446]: https://github.com/gotgenes/pi-packages/issues/446
+[#447]: https://github.com/gotgenes/pi-packages/issues/447
+[#463]: https://github.com/gotgenes/pi-packages/issues/463

package/docs/decisions/0005-subagent-record-admission-policy.md

@@ -0,0 +1,106 @@
+---
+status: accepted
+date: 2026-08-29
+---
+
+# 0005 — What the public `SubagentRecord` snapshot exposes
+
+## Status
+
+Accepted.
+Settles the admission policy for the public snapshot and its contract direction; the lifecycle **event payloads** keep their own guarantee unstated.
+
+## Context
+
+`SubagentRecord` is what `SubagentsService.getRecord()` and `.listAgents()` return.
+It is produced by `toSubagentRecord()` in `src/service/service-adapter.ts`, which copies a named set of fields and drops everything else — a deliberate allowlist that keeps live session objects out of a snapshot a consumer may serialize.
+
+The allowlist had no stated admission policy, so every proposed widening re-litigated the same trade-off from scratch.
+Pull request [#748] proposed `turnCount` and `activeTools` as required fields plus an optional `outputFile`, and flagged the required-versus-optional hazard itself.
+[#724] deferred `isBackground` here rather than deciding it in passing.
+Several more fields — `maxTurns`, `responseText`, `consumedAt`, `stoppedWhileQueued` — exist on the live `Subagent`/`SubagentState` and were dropped with no recorded reason.
+
+Three facts shaped the decision.
+
+1. **The record has no in-repo consumer.**
+   Outside `service-adapter.ts` and its tests, nothing in this repository reads a `SubagentRecord`; the background widget reads live `Subagent` objects through `manager.listAgents()`.
+   The policy is therefore a judgment about consumers in other extensions, not a response to local demand.
+2. **`architecture.md` already supplies the axis.**
+   Its "Reactive versus discrete (not internal versus external)" refinement rules `SubagentsService.getRecord` a query by nature, in-package or not.
+   A snapshot is the discrete half of that split, and what belongs in it follows from that rather than from a field-by-field vote.
+3. **Whether the required-versus-optional question is even a semver question depends on the contract direction.**
+   TypeScript is structurally typed: adding a required property to a type breaks code that *builds* the value, never code that *reads* it.
+
+## Decision
+
+### Admission rules
+
+A field is admitted to `SubagentRecord` when **all four** hold.
+
+1. **Serializable by value** — a JSON primitive, array, or plain object.
+   Never a live object, a function, or a `Map`.
+2. **Discrete, not momentary** — identity, a resolved spawn decision, a cumulative metric, or a pointer to a durable artifact.
+   State whose value is stale the instant it is read is reactive by nature, and the discrete-query half of the split does not serve it.
+3. **Meaningful outside this package** — not bookkeeping the core keeps in order to run its own sweeps.
+4. **Stable in meaning** — the package can keep producing it without re-deriving it from a display snapshot or a UI concern.
+
+Four exclusion classes follow, and a proposal is answered by naming one of them rather than by reopening the debate:
+
+- **live objects** (rule 1) — `subagentSession`, `abortController`, `promise`, `execution`;
+- **momentary activity** (rule 2) — `activeTools`, `responseText`;
+- **internal bookkeeping** (rule 3) — `consumedAt`, `stoppedWhileQueued`;
+- **display snapshots** (rule 4) — `invocation`, which only the tool door built.
+  It was removed from `Subagent` outright by [#828], so this class currently has no live instance; the rule stands on its own and answers the next display snapshot proposed.
+
+### `SubagentRecord` is produced, not implemented
+
+The package constructs every `SubagentRecord` that exists; consumers read them.
+`SubagentRecord` and `SubagentsService` are not contracts third parties satisfy — a consumer's test double should be a cast or a `Partial<>`, not an implementation.
+
+The semver consequence is therefore fixed once, here:
+
+- **adding a field is semver-minor**, required or optional, because structural typing leaves every reader unaffected;
+- **removing a field, renaming one, or narrowing its type is semver-major.**
+
+A field is optional only when its underlying value is genuinely absent in a real state — never as a compatibility hedge.
+
+### A snapshot is by value
+
+`getRecord()` and `listAgents()` return data that no later mutation of the agent can alter, and that no consumer mutation can write back into the agent.
+This was true of every field except `lifetimeUsage`, which was assigned by reference to the object `SubagentState.addUsage()` mutates in place — so a held record drifted, and a consumer could write into a running agent's token totals.
+`toSubagentRecord` now copies it.
+
+### Dispositions
+
+| Field                                          | Disposition                          | Basis                                                           |
+| ---------------------------------------------- | ------------------------------------ | --------------------------------------------------------------- |
+| `id`, `type`, `description`, `status`          | admitted (already present)           | identity and lifecycle status                                   |
+| `result`, `error`, `completedAt`               | admitted, optional (already present) | terminal facts, absent until the agent ends                     |
+| `toolUses`, `lifetimeUsage`, `compactionCount` | admitted (already present)           | cumulative metrics                                              |
+| `startedAt`                                    | admitted (already present)           | resolved lifecycle timestamp                                    |
+| `isBackground`                                 | admitted, required                   | resolved spawn fact, known from the choke point onward ([#724]) |
+| `turnCount`                                    | admitted, required                   | cumulative metric; parity with `toolUses` and `compactionCount` |
+| `maxTurns`                                     | admitted, optional                   | spawn-time configuration; genuinely absent when unset           |
+| `outputFile`                                   | admitted, optional                   | pointer to the child's durable session transcript               |
+| `activeTools`                                  | declined                             | rule 2 — momentary set, and a `Map` on the live record          |
+| `responseText`                                 | declined                             | rule 2 — momentary and unbounded in size                        |
+| `consumedAt`                                   | declined                             | rule 3 — result-delivery bookkeeping behind the retention sweep |
+| `stoppedWhileQueued`                           | declined                             | rule 3 — internal marker selecting a never-started result text  |
+
+## Consequences
+
+- The public snapshot answers "what is this agent, how is it progressing, and how did it end?"
+  A consumer can render progress (`turnCount` against `maxTurns`), filter the roster (`isBackground`) without reconstructing the mode from a display snapshot, and open the child's transcript (`outputFile`) — the pipeline [ADR 0004](0004-reconsider-ui-direction.md) established against the in-package record.
+- Pull request [#748]'s widening is **partially adopted**: `turnCount` and `outputFile` are in, `activeTools` is declined under rule 2.
+- Live agent activity has no external path at all, since no broadcast channel carries it either.
+  That is the intended state of a "no vacant hooks" core, not an oversight.
+  **Revisit condition:** a named consumer plus a reactive channel for momentary state.
+  Whoever reopens it should add the channel, not widen the snapshot — a pulled `activeTools` would be stale on arrival.
+- Both halves of the policy are pinned by tests in `test/service/service-adapter.test.ts`: exact `toEqual` assertions on the admitted set, and a test that populates every declined field on the source and asserts none of them reaches the output.
+  A future widening fails those tests by design; that failure is the moment the proposal meets this policy.
+- `SubagentRecord.lifetimeUsage` stays declared mutable.
+  Once the value is a copy, a consumer mutating it harms nothing, and retyping a shipped public property as `Readonly` would be a breaking change bought for nothing.
+
+[#724]: https://github.com/gotgenes/pi-packages/issues/724
+[#748]: https://github.com/gotgenes/pi-packages/pull/748
+[#828]: https://github.com/gotgenes/pi-packages/issues/828