@gotgenes/pi-subagents 13.2.0 → 13.2.2

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [13.2.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v13.2.1...pi-subagents-v13.2.2) (2026-06-01)
+
+
+### Documentation
+
+* use ADR-NNNN with links docs-wide ([c6b6431](https://github.com/gotgenes/pi-packages/commit/c6b6431c004f324931f23be46cf2e47e8fdac919))
+
+## [13.2.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v13.2.0...pi-subagents-v13.2.1) (2026-05-30)
+
+
+### Documentation
+
+* **pi-subagents:** refresh permission-integration and architecture sections ([#267](https://github.com/gotgenes/pi-packages/issues/267)) ([4096f83](https://github.com/gotgenes/pi-packages/commit/4096f83c343250b4d2cb5a522bbb140e1e023ed3))
+
 ## [13.2.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v13.1.0...pi-subagents-v13.2.0) (2026-05-30)
 
 

package/README.md

@@ -427,10 +427,10 @@ When [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-permissio
 - **Tool filtering** — the permission system's `before_agent_start` handler removes denied tools from the child session before the agent starts.
 - **`ask`-state forwarding** — when a child session triggers an `ask` permission, the prompt forwards to the parent session's UI.
   The parent approves or denies, and the child resumes.
-- **Deterministic child detection** — every child session registers with the permission system's `SubagentSessionRegistry` before `bindExtensions()` fires, so detection does not rely on env vars or filesystem heuristics.
+- **Deterministic child detection** — this extension publishes `subagents:child:session-created` before `bindExtensions()` fires; the permission system subscribes and registers the child session synchronously, so detection does not rely on env vars or filesystem heuristics.
 
 No configuration is required.
-When `@gotgenes/pi-permission-system` is not installed, the registration calls are silent no-ops.
+When `@gotgenes/pi-permission-system` is not installed, the lifecycle events have no subscriber — a harmless no-op.
 
 ## Architecture
 
@@ -451,19 +451,27 @@ src/
     session-config.ts               # Session configuration assembler
     prompts.ts                      # Config-driven system prompt builder
     context.ts                      # Parent conversation context for inherit_context
-    skill-loader.ts                 # Preload skills from Pi-standard + Agent Skills spec
+    conversation.ts                 # Render a session's messages as formatted text
+    content-items.ts                # Shared message content parsing
     env.ts                          # Environment detection (git, platform)
     model-resolver.ts               # Fuzzy model matching
+    session-dir.ts                  # Session directory derivation
   lifecycle/                        # Agent execution and state tracking
-    agent-manager.ts                # Spawn, queue, abort, resume, concurrency
-    agent-runner.ts                 # Session creation, turn loop, tool filtering
-    agent-record.ts                 # Status state machine
+    agent-manager.ts                # Collection manager + observer wiring
+    agent.ts                        # Full execution lifecycle (run, abort, steer, workspace)
+    create-subagent-session.ts      # Assembly factory: session creation, binding, tool filtering
+    subagent-session.ts             # Born-complete child session: turn loop, steer, dispose
+    child-lifecycle.ts              # Child-execution lifecycle event publisher
+    concurrency-queue.ts            # Background agent scheduling
     parent-snapshot.ts              # Immutable spawn-time parent state
-    permission-bridge.ts            # Optional bridge to pi-permission-system registry
-    worktree.ts                     # Git worktree isolation
+    turn-limits.ts                  # Turn-count policy (normalizeMaxTurns)
+    workspace.ts                    # Workspace provider seam
+    usage.ts                        # Token usage tracking
   observation/                      # Progress tracking and notification
     record-observer.ts              # Session-event stats observer
     notification.ts                 # Completion nudges
+    notification-state.ts           # Notification state tracking
+    renderer.ts                     # Notification rendering
   service/                          # Cross-extension API boundary
     service.ts                      # SubagentsService interface + Symbol.for() accessors
     service-adapter.ts              # SubagentsService wrapper around AgentManager
@@ -484,8 +492,9 @@ Each has a corresponding upstream PR:
 3. **`<active_agent>` system-prompt tag** (`src/prompts.ts`) — `buildAgentPrompt` prepends `<active_agent name="${config.name}"/>` to every assembled child system prompt (both `replace` and `append` modes).
    Downstream extensions like [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-permission-system) parse this tag to resolve per-agent `permission:` frontmatter inside the child session.
    Upstream PR: [tintinweb/pi-subagents#73](https://github.com/tintinweb/pi-subagents/pull/73).
-4. **Permission-system registration** (`src/lifecycle/permission-bridge.ts`) — `runAgent` registers every child session with `@gotgenes/pi-permission-system`'s `SubagentSessionRegistry` before `bindExtensions()` and unregisters in the `finally` block.
-   This enables deterministic child detection and `ask`-state forwarding to the parent UI.
+4. **Child-execution lifecycle events** (`src/lifecycle/child-lifecycle.ts`) — the child-session execution lifecycle is published as ordered events on `pi.events` (`subagents:child:spawning`, `session-created`, `completed`, `disposed`).
+   `session-created` fires synchronously before `bindExtensions()` so consumers (e.g. `@gotgenes/pi-permission-system`) can register the child session before binding proceeds.
+   This inverts the former outbound `permission-bridge` pattern ([ADR-0002] / [#261]) — the core publishes, consumers subscribe.
    No upstream equivalent — this feature is specific to the `@gotgenes` fork.
 
 The upstream `vitest` suite plus tests added for each patch all pass on every commit.
@@ -493,3 +502,5 @@ The upstream `vitest` suite plus tests added for each patch all pass on every co
 ## License
 
 MIT — [tintinweb](https://github.com/tintinweb) (upstream) and [Chris Lasher](https://github.com/gotgenes) (fork)
+
+[ADR-0002]: docs/decisions/0002-extensions-on-a-minimal-core.md

package/dist/public.d.ts

@@ -1,19 +1,5 @@
 import { ThinkingLevel } from '@earendil-works/pi-ai';
 
-/** usage.ts — Token usage: shapes, accumulator operators, session-stats readers. */
-/**
- * Lifetime usage components, accumulated via `message_end` events. Survives
- * compaction (which replaces session.state.messages and would reset any
- * stats-derived sum). cacheRead is excluded because each turn's cacheRead is
- * the cumulative cached prefix re-read on that one call — summing across
- * turns counts the prefix N times. See issue #38.
- */
-type LifetimeUsage = {
-    input: number;
-    output: number;
-    cacheWrite: number;
-};
-
 /**
  * types.ts — Type definitions for the subagent system.
  */
@@ -29,27 +15,19 @@ interface AgentInvocation {
     runInBackground?: boolean;
 }
 
+/** usage.ts — Token usage: shapes, accumulator operators, session-stats readers. */
 /**
- * agent.ts — Agent class with encapsulated status-transition logic and per-agent behavior.
- *
- * Status transitions (status, result, error, startedAt, completedAt) are owned
- * by the class and exposed via transition methods. External code reads these
- * fields through public properties but cannot write them directly.
- *
- * Stats (toolUses, lifetimeUsage, compactionCount) are owned by the class and
- * accumulated via mutation methods (incrementToolUses, addUsage, incrementCompactions).
- *
- * Behavior (abort, steer buffering) lives on the agent rather than on
- * AgentManager — each agent manages its own lifecycle concerns.
- *
- * The child's working directory is supplied by a registered WorkspaceProvider
- * (the workspace seam); with no provider the child runs in the parent cwd.
- *
- * Phase-specific collaborators (subagentSession, notification) are attached
- * after construction as lifecycle information becomes available.
+ * Lifetime usage components, accumulated via `message_end` events. Survives
+ * compaction (which replaces session.state.messages and would reset any
+ * stats-derived sum). cacheRead is excluded because each turn's cacheRead is
+ * the cumulative cached prefix re-read on that one call — summing across
+ * turns counts the prefix N times. See issue #38.
  */
-
-type AgentStatus = "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
+type LifetimeUsage = {
+    input: number;
+    output: number;
+    cacheWrite: number;
+};
 
 /**
  * workspace.ts — The single generative extension seam (ADR 0002, Phase 16 Step 2).
@@ -73,7 +51,7 @@ interface WorkspacePrepareContext {
 }
 /** Outcome the core reports to a workspace when the run ends. */
 interface WorkspaceDisposeOutcome {
-    status: AgentStatus;
+    status: SubagentStatus;
     description: string;
 }
 /** What dispose may hand back for the core to fold into the child result. */
@@ -92,6 +70,28 @@ interface WorkspaceProvider {
     prepare(ctx: WorkspacePrepareContext): Promise<Workspace | undefined>;
 }
 
+/**
+ * subagent.ts — Subagent class with encapsulated status-transition logic and per-subagent behavior.
+ *
+ * Status transitions (status, result, error, startedAt, completedAt) are owned
+ * by the class and exposed via transition methods. External code reads these
+ * fields through public properties but cannot write them directly.
+ *
+ * Stats (toolUses, lifetimeUsage, compactionCount) are owned by the class and
+ * accumulated via mutation methods (incrementToolUses, addUsage, incrementCompactions).
+ *
+ * Behavior (abort, steer buffering) lives on the subagent rather than on
+ * SubagentManager — each subagent manages its own lifecycle concerns.
+ *
+ * The child's working directory is supplied by a registered WorkspaceProvider
+ * (the workspace seam); with no provider the child runs in the parent cwd.
+ *
+ * Phase-specific collaborators (subagentSession, notification) are attached
+ * after construction as lifecycle information becomes available.
+ */
+
+type SubagentStatus = "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
+
 /**
  * service.ts — Public API surface for cross-extension access to subagents.
  *
@@ -103,7 +103,6 @@ interface WorkspaceProvider {
  *   svc?.spawn("Explore", "Check for stale TODOs");
  */
 
-type SubagentStatus = "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
 /** Serializable snapshot of an agent's state — no live session objects. */
 interface SubagentRecord {
     id: string;

package/docs/architecture/architecture.md

@@ -51,11 +51,11 @@ flowchart TB
 
     subgraph lifecycle["Lifecycle domain"]
         direction TB
-        AgentManager["AgentManager<br/>(spawn, abort, collection)"]
+        SubagentManager["SubagentManager<br/>(spawn, abort, collection)"]
         ConcurrencyQueue["ConcurrencyQueue<br/>(scheduling, drain)"]
         CreateSubagentSession["createSubagentSession<br/>(assembly factory)"]
         SubagentSession["SubagentSession<br/>(turn loop, steer, dispose)"]
-        Agent["Agent<br/>(status, behavior: abort/steer/run lifecycle)"]
+        Subagent["Subagent<br/>(status, behavior: abort/steer/run lifecycle)"]
         ParentSnapshot["ParentSnapshot<br/>(frozen parent state)"]
         Workspace["workspace<br/>(provider seam: child cwd + teardown)"]
     end
@@ -85,9 +85,9 @@ flowchart TB
         Menu["agent-menu<br/>(slash command)"]
     end
 
-    AgentTool --> AgentManager
-    AgentManager --> Agent
-    Agent --> CreateSubagentSession & SubagentSession
+    AgentTool --> SubagentManager
+    SubagentManager --> Subagent
+    Subagent --> CreateSubagentSession & SubagentSession
     CreateSubagentSession --> SubagentSession
     CreateSubagentSession --> SessionConfig
     SessionConfig --> AgentTypeRegistry
@@ -95,18 +95,18 @@ flowchart TB
     AgentTypeRegistry --> DefaultAgents & CustomAgents
     RecordObserver -.->|subscribes| SubagentSession
     UIObserver -.->|subscribes| SubagentSession
-    Widget -.->|polls| AgentManager
+    Widget -.->|polls| SubagentManager
 ```
 
 ### Key domain types
 
 ```mermaid
 classDiagram
-    class Agent {
+    class Subagent {
         +id: string
         +type: SubagentType
         +description: string
-        +status: AgentStatus
+        +status: SubagentStatus
         +result?: string
         +error?: string
         +toolUses: number
@@ -123,7 +123,7 @@ classDiagram
         +run()
         +resume(prompt, signal)
         +abort(): boolean
-        +steer(message): Promise<boolean>
+        +steer(message): Promise~boolean~
         +isSessionReady(): boolean
         +getConversation(): string | undefined
         +getContextPercent(): number | null
@@ -137,12 +137,12 @@ classDiagram
         +releaseListeners()
     }
 
-    class AgentManager {
+    class SubagentManager {
         +spawn(snapshot, type, prompt, config)
         +spawnAndWait(snapshot, type, prompt, config)
         +resume(id, prompt, signal)
-        +getRecord(id): Agent
-        +listAgents(): Agent[]
+        +getRecord(id): Subagent
+        +listAgents(): Subagent[]
         +abort(id)
     }
 
@@ -171,10 +171,10 @@ classDiagram
         +hasRunning(): boolean
     }
 
-    AgentManager --> Agent : creates/manages
-    AgentManager --> ParentSnapshot : receives at spawn
-    SubagentsService --> AgentManager : wraps via adapter
-    AgentManager --> AgentTypeRegistry : resolves types
+    SubagentManager --> Subagent : creates/manages
+    SubagentManager --> ParentSnapshot : receives at spawn
+    SubagentsService --> SubagentManager : wraps via adapter
+    SubagentManager --> AgentTypeRegistry : resolves types
 ```
 
 ## Agent lifecycle
@@ -216,8 +216,8 @@ sequenceDiagram
     participant LLM as Parent LLM
     participant Tool as subagent tool
     participant Spawn as spawn-config
-    participant Mgr as AgentManager
-    participant Ag as Agent
+    participant Mgr as SubagentManager
+    participant Ag as Subagent
     participant Factory as createSubagentSession
     participant Asm as assembleSessionConfig
     participant Sub as SubagentSession
@@ -238,8 +238,8 @@ sequenceDiagram
     Sub->>Child: prompt + drive turn loop
     Child-->>Sub: result text
     Sub-->>Ag: TurnLoopResult
-    Ag-->>Mgr: update Agent
-    Mgr-->>Tool: Agent
+    Ag-->>Mgr: update Subagent
+    Mgr-->>Tool: Subagent
     Tool-->>LLM: formatted result
     Note over Mgr: disposeSession() fires `disposed` at cleanup (resume-detectable)
 ```
@@ -277,11 +277,11 @@ src/
 │   └── session-dir.ts              session directory derivation
 │
 ├── lifecycle/                      agent execution and state tracking
-│   ├── agent-manager.ts            collection manager + observer wiring
+│   ├── subagent-manager.ts         collection manager + observer wiring
 │   ├── create-subagent-session.ts  assembly factory: session creation, binding, tool filtering
 │   ├── subagent-session.ts         born-complete child session: turn loop, steer, dispose
 │   ├── turn-limits.ts              normalizeMaxTurns (turn-count policy)
-│   ├── agent.ts                    owns full execution lifecycle (run, abort, steer, workspace)
+│   ├── subagent.ts                 owns full execution lifecycle (run, abort, steer, workspace)
 │   ├── concurrency-queue.ts        background agent scheduling with configurable concurrency limit
 │   ├── parent-snapshot.ts          immutable spawn-time parent state
 │   ├── child-lifecycle.ts          child-execution lifecycle event publisher
@@ -296,7 +296,7 @@ src/
 │
 ├── service/                        cross-extension API boundary
 │   ├── service.ts                  SubagentsService interface + Symbol.for() accessors
-│   └── service-adapter.ts          SubagentsServiceAdapter class wrapping AgentManager
+│   └── service-adapter.ts          SubagentsServiceAdapter class wrapping SubagentManager
 │
 ├── tools/                          LLM-facing tool implementations
 │   ├── agent-tool.ts               subagent tool definition, validation, dispatch
@@ -334,7 +334,7 @@ Record statistics (tool uses, token usage, compaction counts) are updated by `re
 UI streaming (active tools, response text, turn counts) is handled by `ui/ui-observer.ts`, which subscribes to the same session events independently.
 Neither observer wraps or forwards the other — both subscribe directly to the session.
 
-The widget reads agent state by polling a shared `Map<string, AgentActivityTracker>` on `SubagentRuntime` every 80 ms. The conversation viewer subscribes to session events via `Agent.subscribeToUpdates()` and reads messages via `Agent.messages` — no direct `AgentSession` reference (#277).
+The widget reads agent state by polling a shared `Map<string, AgentActivityTracker>` on `SubagentRuntime` every 80 ms. The conversation viewer subscribes to session events via `Subagent.subscribeToUpdates()` and reads messages via `Subagent.messages` — no direct `AgentSession` reference (#277).
 
 ## Cross-extension architecture
 
@@ -343,7 +343,7 @@ flowchart TD
     subgraph core["@gotgenes/pi-subagents"]
         direction TB
         exports["SubagentsService API<br/>publish / getSubagentsService<br/>SubagentRecord, SubagentStatus"]
-        engine["Tools: subagent, get_subagent_result,<br/>steer_subagent<br/>AgentManager, createSubagentSession, SubagentSession"]
+        engine["Tools: subagent, get_subagent_result,<br/>steer_subagent<br/>SubagentManager, createSubagentSession, SubagentSession"]
         ui_int["Internal UI: widget, viewer,<br/>/agents menu"]
     end
 
@@ -358,14 +358,14 @@ They declare this package as an optional peer dependency and use dynamic import
 ### What the core owns
 
 - The three tools: `subagent` (née `Agent`), `get_subagent_result`, `steer_subagent`.
-- `AgentManager` — spawn, abort, resume, collection management, observer wiring.
+- `SubagentManager` — spawn, abort, resume, collection management, observer wiring.
 - `ConcurrencyQueue` — background agent scheduling with configurable concurrency limit.
 - `createSubagentSession` — assembly factory: session creation and extension binding; returns a born-complete `SubagentSession`.
 - `SubagentSession` — the born-complete child session: drives the turn loop (`runTurnLoop`/`resumeTurnLoop`), steers, and disposes (firing `disposed` at true session disposal, so resume executions are registry-detected).
 - `child-lifecycle` — publishes the child-execution lifecycle (`spawning`, `session-created` before `bindExtensions()`, `completed`, `disposed`) on `pi.events`.
   Reactive consumers subscribe: `@gotgenes/pi-permission-system` registers each child session on `session-created` and unregisters it on `disposed`.
-  This replaced the former outbound `permission-bridge` (#261, ADR 0002) — the core no longer looks up a named consumer.
-- `workspace` — the single generative seam (#262, ADR 0002): a registered `WorkspaceProvider` supplies a child's cwd plus bracketed `dispose()` at run-start.
+  This replaced the former outbound `permission-bridge` (#261, [ADR-0002]) — the core no longer looks up a named consumer.
+- `workspace` — the single generative seam (#262, [ADR-0002]): a registered `WorkspaceProvider` supplies a child's cwd plus bracketed `dispose()` at run-start.
   With no provider, children run in the parent cwd (default unchanged); the git worktree strategy lives behind this seam in `@gotgenes/pi-subagents-worktrees` (#263, the seam's first consumer).
 - `session-config` — pure configuration assembler (called by `createSubagentSession`).
 - `SubagentRuntime` — session-scoped state bag with methods.
@@ -373,7 +373,7 @@ They declare this package as an optional peer dependency and use dynamic import
 - `record-observer` — session-event observer that updates record statistics without callback threading.
 - Agent type registry — default agents, custom `.md` file loading.
 - Prompt assembly, context extraction, skills, environment.
-- Worktree isolation — evicted to `@gotgenes/pi-subagents-worktrees` via the workspace provider seam in Phase 16 (#263, ADR 0002); `git` no longer appears in the core.
+- Worktree isolation — evicted to `@gotgenes/pi-subagents-worktrees` via the workspace provider seam in Phase 16 (#263, [ADR-0002]); `git` no longer appears in the core.
 - Token usage tracking.
 - Session directory derivation and persisted `SessionManager` for subagent transcripts.
 - Settings persistence.
@@ -478,7 +478,7 @@ Extensions attach through exactly two surfaces, distinguished by the direction o
    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.
+   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** (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.
 
@@ -487,7 +487,7 @@ 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).
 
-The governing rule — **no vacant hooks**: the architecture must *admit* a seam without *shipping* it until a concrete consumer exists.
+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 a speculative abstraction that taxes every reader and that `fallow` flags as dead.
 Latent extensibility is the deliverable; a vacant hook is not.
 
@@ -509,11 +509,11 @@ Latent extensibility is the deliverable; a vacant hook is not.
 - **Tool policy** (`disallowed_tools`) — access control belongs in pi-permission-system's `permission:` frontmatter.
 - **Extension filtering** (`extensions: string[]` allowlist) — tool visibility is pi-permission-system's job.
 - **Worktree isolation** (`worktree.ts`, `worktree-isolation.ts`, `GitWorktreeManager`, the `isolation: "worktree"` spawn mode) — environment policy, not core.
-  Git worktrees are one *strategy* for choosing the child's working directory; containers, throwaway tmpdirs, and remote sandboxes are others.
+  Git worktrees are one _strategy_ for choosing the child's working directory; containers, throwaway tmpdirs, and remote sandboxes are others.
   Evicted to `@gotgenes/pi-subagents-worktrees` (#263), the first consumer of the workspace provider seam.
 - **Extension lifecycle control** (`extensions: false`, `isolated`, `noSkills`) — removed in #264.
   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 is left as a *latent* (un-built) provider seam, added only if a real consumer needs it.
+  Prevent-load (refusing to bind an extension because of load-time side effects, cost, or true sandboxing) is genuinely generative and is left as a _latent_ (un-built) provider seam, added only if a real consumer needs it.
 
 ### Composition model
 
@@ -563,7 +563,7 @@ Bags with 10+ fields are the highest priority for decomposition.
 | `AgentToolDeps`               | 8                                                            | agent-tool                                        | ✓ done    |
 | `AgentMenuDeps`               | 8                                                            | agent-menu                                        | ✓ done    |
 | `ConversationViewerOptions`   | 8                                                            | conversation-viewer                               | Low       |
-| `AgentInit`                   | 8                                                            | agent                                             | Low       |
+| `SubagentInit`                | 8                                                            | subagent                                          | Low       |
 
 ### Complexity hotspots
 
@@ -595,19 +595,19 @@ One 11-line internal clone group remains within `agent-config-editor.ts` (lines
 
 ### Session encapsulation debt (Law of Demeter) — resolved by [#277] ✔️
 
-All consumer reach-throughs to the raw SDK `AgentSession` via `Agent.session` have been eliminated.
-`Agent.session` is removed; `SubagentSession.session` is marked `@internal` (lifecycle use only).
+All consumer reach-throughs to the raw SDK `AgentSession` via `Subagent.session` have been eliminated.
+`Subagent.session` is removed; `SubagentSession.session` is marked `@internal` (lifecycle use only).
 The intent-revealing replacements added by [#277]:
 
-| Reach-through                            | Sites                                                                              | Replacement                                      |
-| ---------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------ |
-| Steer buffer-or-deliver (was duplicated) | `service-adapter.ts`, `steer-tool.ts`                                              | `Agent.steer(message)`                           |
-| Conversation viewing                     | `get-result-tool.ts`, `agent-menu.ts`, `conversation-viewer.ts`                    | `Agent.getConversation()` / `Agent.messages`     |
-| Session-readiness guard                  | `agent-tool.ts`, `agent-manager.ts`                                                | `Agent.isSessionReady()`                         |
-| Context-window stats                     | `steer-tool.ts`, `get-result-tool.ts`, `notification.ts`, `conversation-viewer.ts` | `Agent.getContextPercent()`                      |
-| Live updates (subscription)              | `conversation-viewer.ts`                                                           | `Agent.subscribeToUpdates(fn)`                   |
-| Observer callback session param          | `background-spawner.ts`, `foreground-runner.ts`                                    | `agent.subagentSession` (narrowed callback)      |
-| Session disposal                         | `agent-manager.ts`                                                                 | `SubagentSession.dispose()` — resolved by [#265] |
+| Reach-through                            | Sites                                                                              | Replacement                                        |
+| ---------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------- |
+| Steer buffer-or-deliver (was duplicated) | `service-adapter.ts`, `steer-tool.ts`                                              | `Subagent.steer(message)`                          |
+| Conversation viewing                     | `get-result-tool.ts`, `agent-menu.ts`, `conversation-viewer.ts`                    | `Subagent.getConversation()` / `Subagent.messages` |
+| Session-readiness guard                  | `agent-tool.ts`, `subagent-manager.ts`                                             | `Subagent.isSessionReady()`                        |
+| Context-window stats                     | `steer-tool.ts`, `get-result-tool.ts`, `notification.ts`, `conversation-viewer.ts` | `Subagent.getContextPercent()`                     |
+| Live updates (subscription)              | `conversation-viewer.ts`                                                           | `Subagent.subscribeToUpdates(fn)`                  |
+| Observer callback session param          | `background-spawner.ts`, `foreground-runner.ts`                                    | `subagent.subagentSession` (narrowed callback)     |
+| Session disposal                         | `subagent-manager.ts`                                                              | `SubagentSession.dispose()` — resolved by [#265]   |
 
 ### Proposed bag decompositions
 
@@ -755,106 +755,15 @@ After Phase 15, Agent is born complete with all dependencies and configuration,
 All six steps are closed: [#227], [#228], [#231], [#229], [#230], [#232].
 See [phase-15-domain-model-evolution.md](history/phase-15-domain-model-evolution.md) for details.
 
-## Improvement roadmap (Phase 16 — invert dependencies: extensions on a minimal core)
+## Phase 16 (complete)
 
-Phase 16 reclaims its original intent — invert the core's outbound dependencies — and extends it: worktree isolation joins permissions as an *extension* on a minimal core, leaving pi-subagents a pure child-session orchestrator.
-The decision and the full reasoning chain are recorded in [ADR 0002](../decisions/0002-extensions-on-a-minimal-core.md); the two-surface extension model is described under [Target architecture](#target-architecture).
-
-### Abandoned exploration: agent collaborator architecture
-
-An earlier Phase 16 plan ("agent collaborator architecture") proposed giving `Agent` three collaborators — a session factory, a `WorktreeIsolation`, and a lifecycle observer — and dissolving the runner.
-That framing was abandoned.
-Pulling on a single late-bound `create(cwd?)` parameter on the planned `ChildSessionFactory` exposed deeper problems:
-
-- `WorktreeIsolation.setup()` is a two-phase `construct-then-setup()` that violates "Construct complete" (principle 8) — the worktree is only *ready* at dequeue.
-- The worktree and the child session share one lifespan, so they are one run-scoped resource, not sibling collaborators that `Agent` must sequence; the `cwd` parameter only existed because the worktree was split out and `Agent` relayed its output back in.
-- Worktrees are not intrinsic to subagents — they are one *workspace strategy* and belong outside the core, exactly as Phase 14 evicted tool/extension policy.
-
-Issue #256 (`WorktreeIsolation` as a collaborator) shipped under the abandoned plan and is now superseded by #263; issue #257 (`ChildSessionFactory` extraction) was parked.
-The structural win the collaborator plan chased — a born-complete child execution and the dissolution of the runner — is recovered by a cleaner route once the workspace seam exists (Step 5).
-
-### Steps
-
-#### Step 1: Child-execution lifecycle events; retire permission-bridge — [#261] ✅ Delivered
-
-Emit ordered child-execution events (`spawning`, `session-created` before `bindExtensions()`, `completed`, `disposed`) carrying child identity (session directory, agent name, parent session id).
-Migrate `@gotgenes/pi-permission-system` to subscribe to `session-created`/`disposed` for registration instead of being looked up by the core; delete `permission-bridge.ts`.
-
-- Cross-package: pi-subagents (emit + remove bridge) and pi-permission-system (subscribe).
-- Investigation (resolved): `pi.events` is a Node `EventEmitter`, so `emit()` dispatches listeners synchronously on the same call stack — a synchronous subscriber completes before `emit()` returns.
-  Emitting `session-created` immediately before `bindExtensions()` therefore guarantees the registry entry lands pre-bind, with no new SDK hook.
-  The synchronous-handler constraint is encoded as a real-bus test in pi-permission-system.
-- Outcome: the core stops reaching out to a named consumer; permission detection rides events.
-- Deferred: removing the now-caller-less `registerSubagentSession`/`unregisterSubagentSession` from `PermissionsService` → #267; registry-detected resume ("executing now" → "exists" semantics) → #265.
-
-#### Step 2: Define the `WorkspaceProvider` seam — [#262] ✅ Delivered
-
-Added the `WorkspaceProvider` / `Workspace` interfaces (`src/lifecycle/workspace.ts`) and `SubagentsService.registerWorkspaceProvider` (single provider, throws on duplicate, returns an unregister disposer).
-All five workspace types are named-re-exported from `service.ts`: `WorkspaceProvider`, `Workspace`, `WorkspacePrepareContext`, `WorkspaceDisposeOutcome`, and `WorkspaceDisposeResult` (added in #272).
-At run-start `Agent.run()` consults the registered provider for the child's cwd and a disposal handle; with no provider the child runs in the parent's cwd (the legacy worktree-collaborator fallback was removed when worktrees left the core in #263).
-On completion the core calls `Workspace.dispose({ status, description })` and appends the returned `resultAddendum` verbatim — the provider owns the wording.
-
-- The seam is additive and non-breaking: the existing `isolation: "worktree"` path is untouched (its eviction is Step 3).
-- Land alongside its first consumer (Step 3) to avoid a vacant hook — the "no vacant hooks" rule.
-  Within #262 the seam is exercised only by test fakes; do not cut a release containing the seam without `@gotgenes/pi-subagents-worktrees`.
-- Outcome: a single generative seam; the core no longer knows what an "isolation strategy" is.
-
-#### Step 3: Extract worktrees to `@gotgenes/pi-subagents-worktrees` — [#263] ✅ Delivered
-
-New package implementing `WorkspaceProvider`: prepares a git worktree at run-start (born complete), tears it down after (saving the branch), and owns the "changes saved to branch" result.
-Worktree isolation is opt-in per agent type via the package's own `worktreeAgents` config; creation failure for an opted-in agent throws (strict, no silent fallback).
-Removed `worktree.ts`, `worktree-isolation.ts`, `GitWorktreeManager`, and the `isolation: "worktree"` mode from the core; dropped `isolation` from the spawn API and `SubagentsService`, and `worktreeResult` from `SubagentRecord`.
-
-- Supersedes #256.
-  New package registered in `release-please-config.json` and `.pi/settings.json` (after pi-subagents); consumes the published `@gotgenes/pi-subagents` from the registry (`linkWorkspacePackages: false`), since `exports.types` resolves to the shipped declaration bundle.
-  From the release carrying #272, all five workspace types are importable by name: `WorkspaceProvider`, `Workspace`, `WorkspacePrepareContext`, `WorkspaceDisposeOutcome`, and `WorkspaceDisposeResult`.
-- Outcome: git leaves the core; worktree users install one package, everyone else pays nothing.
-
-#### Step 4: Remove `isolated` / `extensions: false` / `noSkills` — [#264] ✅ Delivered
-
-Children always load the parent's extensions and skills; the recursion guard is now unconditional.
-Deny-at-use (the in-child permission layer) covers tool restriction; prevent-load is left as a latent provider seam (not shipped).
-The `skills` curation axis collapsed symmetrically with `extensions`: `AgentConfig.skills`, the skill-preload path (`skill-loader.ts`, `safe-fs.ts`, `preloadSkills`, `PromptExtras`), `SessionConfig.{extensions,noSkills,extras}`, and the `isolated:` / `extensions:` / `skills:` custom-agent frontmatter keys are all gone.
-
-- Depended on: Step 1 (deny-at-use over events).
-- Outcome: the `isolated`/`extensions`/`noSkills`/`skills` axis is gone; the guard is unconditional.
-
-#### Step 5: Born-complete child execution; dissolve the runner — [#265] ✅ Delivered
-
-`createSubagentSession()` is an assembly factory that returns a born-complete `SubagentSession` (session created, extensions bound, recursion guard applied).
-`SubagentSession` owns turn driving (`runTurnLoop`/`resumeTurnLoop`), steering, and disposal.
-`Agent.run()` is coordination, not assembly; `runAgent` / `resumeAgent` / `ConcreteAgentRunner` / `AgentRunner` / `RunOptions` / `RunResult` / `ExecutionState` dissolved.
-`getAgentConversation()` relocated to `session/conversation.ts`; `normalizeMaxTurns()` to `lifecycle/turn-limits.ts`.
-`disposed` now fires at true session disposal (cleanup), so resume executions are registry-detected (closing the gap deferred from #261).
-
-- Depends on: Steps 2–4.
-- Outcome: the "runner" concept is gone; `Agent.run()` is coordination, not assembly — the structural goal of the abandoned collaborator plan, reached cleanly.
-
-### Step dependency diagram
-
-```mermaid
-flowchart LR
-    S1["Step 1<br/>Lifecycle events<br/>(retire bridge)"]
-    S2["Step 2<br/>WorkspaceProvider seam"]
-    S3["Step 3<br/>Extract worktrees pkg"]
-    S4["Step 4<br/>Remove isolated"]
-    S5["Step 5<br/>Born-complete execution"]
-
-    S2 --> S3
-    S1 --> S4
-    S2 --> S5
-    S3 --> S5
-    S4 --> S5
-```
-
-### Tracks
-
-1. **Track A — Inversion seams** (Steps 1, 2): lifecycle events and the workspace seam.
-   Independent of each other — can proceed in parallel.
-2. **Track B — Eviction** (Steps 3, 4): worktrees and `isolated` leave the core.
-   Step 3 depends on Step 2.
-3. **Track C — Consolidation** (Step 5): dissolve the runner around the new seam.
-   Depends on Tracks A and B.
+Phase 16 inverted the core's outbound dependencies: worktree isolation joined permissions as an _extension_ on a minimal core, leaving pi-subagents a pure child-session orchestrator.
+The core now attaches extensions through exactly two surfaces — observational lifecycle events (unlimited) and rationed generative provider seams (today only the workspace provider) — and has zero knowledge of its consumers.
+The "runner" concept is gone: `createSubagentSession()` returns a born-complete `SubagentSession` that owns turn driving, steering, and disposal, and `Subagent.run()` is coordination, not assembly.
+The decision and the full reasoning chain are recorded in [ADR-0002]; the two-surface extension model is described under [Target architecture](#target-architecture).
+All five steps are closed: [#261], [#262], [#263], [#264], [#265].
+The earlier "agent collaborator architecture" framing (#256 superseded, #257 parked, #258 and #259 closed not-planned) was abandoned; its structural win was reached cleanly via the workspace seam.
+See [phase-16-invert-dependencies.md](history/phase-16-invert-dependencies.md) for details.
 
 ## Improvement roadmap (Phase 17 — extract UI)
 
@@ -864,8 +773,8 @@ By this point the core is minimal and stable — the API boundary has been prove
 
 ## Refactoring history
 
-Phases 1–5, 7–14 are complete.
-Phase 6 (UI extraction to a separate package) is deferred.
+Phases 1–5, 7–16 are complete.
+Phase 6 (UI extraction to a separate package) is deferred → Phase 17.
 Detailed records are preserved in per-phase history files:
 
 | Phase | Title                                               | Status              | History                                                                              |
@@ -885,7 +794,7 @@ Detailed records are preserved in per-phase history files:
 | 13    | Remaining structural smells                         | Complete            | [phase-13-remaining-smells.md](history/phase-13-remaining-smells.md)                 |
 | 14    | Strip policy from core                              | Complete            | [phase-14-strip-policy.md](history/phase-14-strip-policy.md)                         |
 | 15    | Domain model evolution                              | Complete            | [phase-15-domain-model-evolution.md](history/phase-15-domain-model-evolution.md)     |
-| 16    | Invert dependencies (extensions on a minimal core)  | Planned             | [ADR 0002](../decisions/0002-extensions-on-a-minimal-core.md)                        |
+| 16    | Invert dependencies (extensions on a minimal core)  | Complete            | [phase-16-invert-dependencies.md](history/phase-16-invert-dependencies.md)           |
 | 17    | Extract UI to separate package                      | Planned             | —                                                                                    |
 
 ### Structural refactoring issues
@@ -907,7 +816,7 @@ Detailed records are preserved in per-phase history files:
 | Phase 14             | #237, #238, #239, #242                                     | Remove disallowed_tools, remove extensions filtering, collapse filterActiveTools, rename Agent to subagent                                                 |
 | Phase 15             | #227, #228, #231, #229, #230, #232                         | Agent domain model, async startAgent, runner self-contained, Agent.run(), ConcurrencyQueue, Agent.resume()                                                 |
 | Phase 16             | #261, #262, #263, #264, #265                               | Lifecycle events (retire permission-bridge), WorkspaceProvider seam, extract worktrees package, remove isolated, born-complete execution / dissolve runner |
-| Phase 16 (abandoned) | #256 (superseded), #257 (parked)                           | Agent collaborator architecture — replaced by the inversion approach above (ADR 0002)                                                                      |
+| Phase 16 (abandoned) | #256 (superseded), #257 (parked), #258, #259 (not planned) | Agent collaborator architecture — replaced by the inversion approach above ([ADR-0002])                                                                    |
 
 The remaining open issue is #22 (parent-session resolution), a cross-extension track that does not gate the structural work.
 
@@ -952,3 +861,4 @@ The upstream test suite is run periodically as a regression canary for the sessi
 [#264]: https://github.com/gotgenes/pi-packages/issues/264
 [#265]: https://github.com/gotgenes/pi-packages/issues/265
 [#277]: https://github.com/gotgenes/pi-packages/issues/277
+[ADR-0002]: ../decisions/0002-extensions-on-a-minimal-core.md