@gotgenes/pi-subagents 18.0.1 → 18.0.2

package/docs/plans/0277-encapsulate-agent-session.md

@@ -1,304 +0,0 @@
----
-issue: 277
-issue_title: "Encapsulate AgentSession behind SubagentSession; retire the remaining agent.session reach-throughs"
----
-
-# Encapsulate AgentSession behind SubagentSession
-
-## Problem Statement
-
-Callers outside the `lifecycle/` domain reach through `Agent.session` (which returns the raw SDK `AgentSession` via `this.subagentSession?.session`) and operate on the session object directly.
-This violates Law of Demeter and Tell-Don't-Ask — the missing abstractions are intent-revealing methods on `Agent` and `SubagentSession` that delegate internally.
-
-Issue #265 introduced `SubagentSession` and routed the run/resume/dispose path through it.
-The remaining consumer-facing reach-throughs were deferred to this issue.
-
-## Goals
-
-- Add intent-revealing methods to `Agent` and `SubagentSession` that replace every raw `AgentSession` access outside `lifecycle/`.
-- Collapse the duplicated steer buffer-or-deliver logic into a single `Agent.steer()` method.
-- Narrow the `onSessionCreated` observer callback to stop delivering the raw `AgentSession` to spawners.
-- Remove the `Agent.session` getter.
-- After this change, no production module outside `lifecycle/` references the raw `AgentSession`.
-
-## Non-Goals
-
-- The `Agent` → `Subagent` class rename — independent of this issue, can land in either order.
-- Changing the public `SubagentsService` API surface in `service/service.ts` — it already uses `SubagentRecord` (no live session objects).
-- Refactoring the conversation viewer's rich-rendering internals — only its session reference changes.
-- Architecture doc updates for the file-layout listing — `SubagentSession` and `Agent` files are not being added, moved, or removed.
-
-## Background
-
-### Affected reach-through sites
-
-Every site reaches the raw `AgentSession` exposed by the `Agent.session` getter.
-
-| Reach-through                          | Production files                                                                                                           | Current pattern                                                                                               |
-| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| Steer buffer-or-deliver (duplicated)   | `service/service-adapter.ts:93`, `tools/steer-tool.ts:43`                                                                  | `record.session` → `session.steer()` or `record.queueSteer()`                                                 |
-| Context-percent stats                  | `tools/get-result-tool.ts:56`, `tools/steer-tool.ts:57`, `observation/notification.ts:49`, `ui/conversation-viewer.ts:145` | `getSessionContextPercent(record.session)`                                                                    |
-| Conversation viewing                   | `tools/get-result-tool.ts:83-84`, `ui/agent-menu.ts:255`, `ui/conversation-viewer.ts:63,223`                               | `getAgentConversation(record.session)` / `session.messages`                                                   |
-| Session-readiness guard                | `tools/agent-tool.ts:111`, `lifecycle/agent-manager.ts:205`                                                                | `!record.session` / `!agent?.session`                                                                         |
-| Observer callback delivers raw session | `tools/background-spawner.ts:56`, `tools/foreground-runner.ts:111`                                                         | `onSessionCreated(_agent, session)` → `tracker.setSession(session)` + `subscribeUIObserver(session, tracker)` |
-| Activity-tracker session stats         | `ui/widget-renderer.ts:106`                                                                                                | `activity?.session` → `getSessionContextPercent(activity.session)` (via `AgentActivityTracker.session`)       |
-
-### Existing delegate methods
-
-`SubagentSession` already has `steer(message)`, `runTurnLoop()`, `resumeTurnLoop()`, and `dispose()`.
-The `session` getter is marked "retired by #277" in its JSDoc.
-
-`subscribeAgentObserver` in `observation/record-observer.ts` already accepts `SubscribableSession` (not `AgentSession`), so it can accept `SubagentSession` directly once `SubagentSession` implements the `subscribe()` delegate.
-
-### Public API surface
-
-The public API (`SubagentsService` + `SubagentRecord` in `service/service.ts`) does not expose `Agent` or `AgentSession`.
-Removing `Agent.session` is not a breaking change for cross-extension consumers.
-
-## Design Overview
-
-### New delegate methods on `SubagentSession`
-
-```typescript
-// Delegates to getAgentConversation(this._session)
-getConversation(): string
-
-// Delegates to getSessionContextPercent(this._session)
-getContextPercent(): number | null
-
-// Delegates to this._session.subscribe(fn) — satisfies SubscribableSession
-subscribe(fn: (event: AgentSessionEvent) => void): () => void
-
-// Delegates to this._session.getSessionStats() — satisfies SessionLike
-getSessionStats(): SessionStatsLike
-
-// Delegates to this._session.messages
-get messages(): readonly unknown[]
-```
-
-With `subscribe()` and `getSessionStats()`, `SubagentSession` structurally satisfies both `SubscribableSession` and `SessionLike`.
-This lets spawners pass a `SubagentSession` directly to `subscribeUIObserver()` and `tracker.setSession()` without exposing the raw `AgentSession`.
-
-### New intent-revealing methods on `Agent`
-
-```typescript
-// Buffer-or-deliver: returns true if delivered, false if buffered
-async steer(message: string): Promise<boolean>
-
-// Returns true when a SubagentSession is available
-isSessionReady(): boolean
-
-// Delegates to SubagentSession.getConversation(), returns undefined if no session
-getConversation(): string | undefined
-
-// Delegates to SubagentSession.getContextPercent(), returns null if no session
-getContextPercent(): number | null
-
-// Delegates to SubagentSession.subscribe() for conversation-viewer live updates
-subscribeToUpdates(fn: (event: AgentSessionEvent) => void): (() => void) | undefined
-
-// Delegates to SubagentSession.messages for conversation-viewer rendering
-get messages(): readonly unknown[]
-```
-
-The `steer()` method replaces the duplicated buffer-or-deliver logic:
-
-```typescript
-async steer(message: string): Promise<boolean> {
-  if (!this.subagentSession) {
-    this.queueSteer(message);
-    return false;
-  }
-  await this.subagentSession.steer(message);
-  return true;
-}
-```
-
-### Observer callback narrowing
-
-`AgentLifecycleObserver.onSessionCreated` changes from `(agent: Agent, session: AgentSession)` to `(agent: Agent)`.
-Spawners access `agent.subagentSession!` (already public) which satisfies `SubscribableSession & SessionLike`:
-
-```typescript
-// tools/background-spawner.ts — after
-onSessionCreated: (agent) => {
-  const sub = agent.subagentSession!;
-  bgState.setSession(sub);         // SubagentSession satisfies SessionLike
-  subscribeUIObserver(sub, bgState); // SubagentSession satisfies SubscribableSession
-},
-```
-
-### Internal lifecycle wiring
-
-`Agent.run()` already passes the session to `subscribeAgentObserver()`, which accepts `SubscribableSession`.
-After the change, it passes `this.subagentSession` directly instead of `this.subagentSession.session`:
-
-```typescript
-// lifecycle/agent.ts — Agent.run(), after
-this.attachObserver(subscribeAgentObserver(this.subagentSession, this, { ... }));
-this.observer?.onSessionCreated?.(this);
-```
-
-### Removals
-
-- `Agent.session` getter — removed entirely.
-- `SubagentSession.session` getter — marked `@internal`, kept for lifecycle-internal uses (the `getLastAssistantText()` private helper reads `this._session.messages`).
-- `Agent.queueSteer()` — becomes private (called only from `Agent.steer()` and `Agent.flushPendingSteers()`).
-- `Agent.flushPendingSteers()` — becomes private (called only from `Agent.run()`).
-
-## Module-Level Changes
-
-### `src/lifecycle/subagent-session.ts`
-
-- Add `getConversation()`, `getContextPercent()`, `subscribe()`, `getSessionStats()`, `messages` getter.
-- Import `getAgentConversation` from `#src/session/conversation` and `getSessionContextPercent`, `SessionStatsLike` from `#src/lifecycle/usage`.
-- Mark the `session` getter with `@internal` JSDoc.
-
-### `src/lifecycle/agent.ts`
-
-- Add `steer()`, `isSessionReady()`, `getConversation()`, `getContextPercent()`, `subscribeToUpdates()`, `messages` getter.
-- Remove the `session` getter.
-- Make `queueSteer()` and `flushPendingSteers()` private.
-- In `run()`: pass `this.subagentSession` (not `this.subagentSession.session`) to `subscribeAgentObserver()` and fire `onSessionCreated(this)` without the session param.
-- In `resume()`: pass `subagentSession` (not `subagentSession.session`) to `subscribeAgentObserver()`.
-- Remove the `AgentSession` import.
-- Update `AgentLifecycleObserver.onSessionCreated` to `(agent: Agent)` — no session param.
-
-### `src/service/service-adapter.ts`
-
-- Replace the 6-line steer reach-through with `await record.steer(message)`.
-- Remove the `!session` guard — `Agent.steer()` owns it.
-
-### `src/tools/steer-tool.ts`
-
-- Replace the buffer-or-deliver dance with `const delivered = await record.steer(message)`.
-- Use `record.getContextPercent()` instead of `getSessionContextPercent(session)`.
-- Remove the `getSessionContextPercent` import.
-
-### `src/tools/get-result-tool.ts`
-
-- Use `record.getContextPercent()` instead of `getSessionContextPercent(record.session)`.
-- Use `record.getConversation()` instead of `getAgentConversation(record.session)`.
-- Remove the `getSessionContextPercent` and `getAgentConversation` imports.
-
-### `src/tools/agent-tool.ts`
-
-- Use `existing.isSessionReady()` instead of `!existing.session`.
-
-### `src/lifecycle/agent-manager.ts`
-
-- Use `agent.isSessionReady()` instead of `agent?.session`.
-- Update the `onSessionCreated` relay to `(agent) => options.observer!.onSessionCreated!(agent)` — no session param.
-
-### `src/observation/notification.ts`
-
-- Use `record.getContextPercent()` instead of `getSessionContextPercent(record.session)`.
-- Remove the `getSessionContextPercent` import.
-
-### `src/ui/conversation-viewer.ts`
-
-- Remove `session: AgentSession` from `ConversationViewerOptions`.
-- Remove the `private session: AgentSession` field.
-- Use `this.record.subscribeToUpdates(() => ...)` instead of `session.subscribe(...)`.
-- Use `this.record.messages` instead of `this.session.messages`.
-- Use `this.record.getContextPercent()` instead of `getSessionContextPercent(this.record.session)`.
-- Remove the `AgentSession` and `getSessionContextPercent` imports.
-
-### `src/ui/agent-menu.ts`
-
-- Use `record.isSessionReady()` instead of `record.session` check.
-- Remove the `session` variable and stop passing it to `ConversationViewer`.
-
-### `src/tools/background-spawner.ts`
-
-- Update `onSessionCreated` callback: `(agent) => { const sub = agent.subagentSession!; ... }`.
-- Pass `sub` instead of `session` to `bgState.setSession()` and `subscribeUIObserver()`.
-
-### `src/tools/foreground-runner.ts`
-
-- Same pattern as `background-spawner.ts`.
-
-### `test/helpers/mock-session.ts`
-
-- Update `createSubagentSessionStub` to include the new delegate methods (`getConversation`, `getContextPercent`, `subscribe`, `getSessionStats`, `messages`).
-- The stub's `subscribe` can delegate to the underlying mock session's `subscribe`.
-
-### Test files requiring updates
-
-- `test/lifecycle/subagent-session.test.ts` — add tests for new delegate methods.
-- `test/lifecycle/agent.test.ts` — add tests for `steer()`, `isSessionReady()`, `getConversation()`, `getContextPercent()`; update `queueSteer` and `flushPendingSteers` tests (now private, tested through `steer()`); update `session` getter tests to `isSessionReady()`.
-- `test/service/service-adapter.test.ts` — update steer tests (no more session reach-through).
-- `test/tools/steer-tool.test.ts` — update to use `Agent.steer()` semantics.
-- `test/tools/get-result-tool.test.ts` — update context-percent and conversation assertions.
-- `test/tools/agent-tool.test.ts` — update resume guard to use `isSessionReady()`.
-- `test/tools/background-spawner.test.ts` — update `onSessionCreated` callback assertions.
-- `test/tools/foreground-runner.test.ts` — update `onSessionCreated` callback assertions.
-- `test/observation/notification.test.ts` — update context-percent assertions.
-- `test/conversation-viewer.test.ts` — remove `session` from viewer options, update to use `record` methods.
-- `test/ui/agent-menu.test.ts` — update session guard assertions.
-- `test/lifecycle/agent-manager.test.ts` — update resume guard + observer relay tests.
-
-## Test Impact Analysis
-
-1. **New unit tests enabled:** Direct testing of `SubagentSession.getConversation()`, `getContextPercent()`, `subscribe()`, `getSessionStats()`, `messages` — these were previously only testable by reaching through the raw session.
-   Direct testing of `Agent.steer()` buffer-or-deliver logic — previously scattered across consumer tests.
-2. **Existing tests that become simpler:** `steer-tool.test.ts` and `service-adapter.test.ts` no longer need to set up the session-present/session-absent dance — they test through `Agent.steer()`.
-   `get-result-tool.test.ts` no longer needs mock sessions for context-percent assertions.
-3. **Existing tests that stay as-is:** `SubagentSession.runTurnLoop()` and `resumeTurnLoop()` tests — they exercise turn driving, which is unrelated.
-   `Agent.run()` integration tests — they verify the full lifecycle including observer wiring.
-
-## TDD Order
-
-1. Add delegate methods to `SubagentSession` (`getConversation`, `getContextPercent`, `subscribe`, `getSessionStats`, `messages`).
-   Update `createSubagentSessionStub` test helper to include the new methods.
-   Test: unit tests for each delegate method in `subagent-session.test.ts`.
-   Commit: `feat: add delegate methods to SubagentSession for session encapsulation (#277)`.
-
-2. Add intent-revealing methods to `Agent` (`steer`, `isSessionReady`, `getConversation`, `getContextPercent`, `subscribeToUpdates`, `messages`).
-   Test: unit tests for each method in `agent.test.ts`.
-   Commit: `feat: add session-encapsulation methods to Agent (#277)`.
-
-3. Migrate steer callers: replace the buffer-or-deliver reach-through in `service-adapter.ts` and `steer-tool.ts` with `record.steer()`.
-   Replace `getSessionContextPercent(session)` in `steer-tool.ts` with `record.getContextPercent()`.
-   Make `queueSteer()` and `flushPendingSteers()` private on `Agent`.
-   Update tests in `service-adapter.test.ts`, `steer-tool.test.ts`, `agent.test.ts` (the `queueSteer`/`flushPendingSteers` tests become tests for `Agent.steer()`; existing tests from step 2 may cover this).
-   Commit: `refactor: use Agent.steer for buffer-or-deliver (#277)`.
-
-4. Migrate context-percent, conversation, and readiness callers: `get-result-tool.ts`, `agent-tool.ts`, `agent-manager.ts`, `notification.ts`.
-   Update corresponding test files.
-   Commit: `refactor: replace session reach-throughs in tools and observation (#277)`.
-
-5. Refactor conversation viewer and agent-menu: remove `session: AgentSession` from `ConversationViewerOptions`, use `record` methods for subscribe/messages/contextPercent.
-   Update `conversation-viewer.test.ts` and `agent-menu.test.ts`.
-   Commit: `refactor: remove raw session from conversation viewer (#277)`.
-
-6. Narrow `onSessionCreated` callback: change `AgentLifecycleObserver.onSessionCreated` to `(agent: Agent)` — no session param.
-   Update `Agent.run()` and `Agent.resume()` to pass `SubagentSession` (not raw session) to `subscribeAgentObserver`.
-   Update spawners (`background-spawner.ts`, `foreground-runner.ts`) and `agent-manager.ts` relay.
-   Update corresponding test files.
-   Commit: `refactor: narrow onSessionCreated to hide raw AgentSession (#277)`.
-
-7. Remove `Agent.session` getter.
-   Mark `SubagentSession.session` getter as `@internal`.
-   Remove `AgentSession` import from `agent.ts`.
-   Update any remaining tests that reference `Agent.session` (use `agent.isSessionReady()` or `agent.subagentSession`).
-   Verify with `pnpm run check` and `pnpm -r run test`.
-   Commit: `refactor: remove Agent.session getter (#277)`.
-
-8. Update the architecture doc's "Session encapsulation debt" section to reflect completion.
-   Commit: `docs: mark session encapsulation debt resolved (#277)`.
-
-## Risks and Mitigations
-
-| Risk                                                                                          | Mitigation                                                                                                                                                                 |
-| --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `SubagentSession` might not structurally satisfy `SubscribableSession` or `SessionLike`       | Verify with `pnpm run check` after step 1 — the delegate methods must match the expected signatures exactly.                                                               |
-| Making `queueSteer`/`flushPendingSteers` private breaks tests                                 | Step 3 explicitly migrates those tests to exercise `Agent.steer()` instead.                                                                                                |
-| The conversation viewer's `messages` accessor returns `readonly unknown[]` which loses typing | The viewer already casts messages to `{ role: string; [key: string]: unknown }` — the cast is unchanged, and the viewer's rendering is unaffected.                         |
-| Narrowing `onSessionCreated` could break the `agent-manager.ts` relay's non-null assertion    | The relay checks `options.observer?.onSessionCreated` before wiring — the narrowed signature is structurally compatible; the only change is dropping the second parameter. |
-| Large number of test files to update                                                          | Steps 3–6 group migrations by concern (steer, stats/conversation/readiness, viewer, observer) so each commit is self-contained and reviewable.                             |
-
-## Open Questions
-
-- None — the issue's proposed methods are unambiguous and the acceptance criteria are clear.
-  The only design addition beyond the issue is narrowing `onSessionCreated` and adding `messages`/`subscribeToUpdates` for the conversation viewer, both of which are required to satisfy the "no production module outside lifecycle/ references AgentSession" acceptance criterion.

package/docs/plans/0280-rename-agent-to-subagent.md

@@ -1,197 +0,0 @@
----
-issue: 280
-issue_title: "Rename the internal Agent class to Subagent"
----
-
-# Rename the internal `Agent` class to `Subagent`
-
-## Problem Statement
-
-The internal lifecycle class `Agent` (`src/lifecycle/agent.ts`) models a single spawned subagent, but the bare name `Agent` collides with two unrelated concepts in the same code: the parent Pi agent that invokes our tooling, and the SDK's `AgentSession` that each subagent wraps.
-The public API already standardized on the `Subagent*` family (`SubagentsService`, `SubagentRecord`, `SubagentStatus`, `SubagentType`, and — after [#265] — `SubagentSession` / `createSubagentSession`).
-The internal lifecycle layer is the lone holdout still using bare `Agent*`.
-Renaming the subagent-instance cluster closes that inconsistency and removes the parent/child/SDK ambiguity.
-
-## Goals
-
-- Rename the subagent-instance cluster in `src/lifecycle/` to the `Subagent*` family: `Agent` → `Subagent`, `AgentManager` → `SubagentManager`, `AgentInit` → `SubagentInit`, `AgentLifecycleObserver` → `SubagentLifecycleObserver`, `AgentManagerObserver` → `SubagentManagerObserver`, `AgentManagerOptions` → `SubagentManagerOptions`, `AgentObserverOptions` → `SubagentObserverOptions`, `AgentManagerLike` → `SubagentManagerLike`.
-- Consolidate the duplicate `AgentStatus` union into the existing public `SubagentStatus`, deleting the duplicate and re-pointing `WorkspaceDisposeOutcome.status`.
-- Rename the lifecycle module files to match their primary export: `agent.ts` → `subagent.ts`, `agent-manager.ts` → `subagent-manager.ts`, plus the matching test files and the `make-agent.ts` test helper.
-- Extend the rename to adjacent identifiers in the same cluster for full consistency: the `subscribeAgentObserver` function → `subscribeSubagentObserver`, the `SubagentManagerObserver` methods `onAgent*` → `onSubagent*`, and the `createTestAgent` helper → `createTestSubagent`.
-- Update residual bare `Agent` / `AgentManager` references in lifecycle comments, JSDoc, and error strings — the acceptance grep matches these, not just symbols.
-- Update `docs/architecture/architecture.md` to the new names.
-- This is internal-only and non-breaking — the exported surface is unchanged apart from `WorkspaceDisposeOutcome.status` reading `SubagentStatus` (an identical union), so commits use `refactor:`, never `feat!:`.
-
-## Non-Goals
-
-- The agent-type/config axis stays untouched: `AgentConfig`, `AgentType`, `AgentTypeRegistry`, `AgentConfigLookup`, `AgentInvocation`, `AgentPromptConfig`, `AgentCategories`.
-- The UI/tool surface stays untouched: `AgentTool` (+ `AgentTool*` variants), `AgentSpawnConfig`, `AgentWidget`, `AgentsMenuHandler`, `AgentActivityTracker`, `AgentDetails`, `AgentCreationWizard`, `AgentConfigEditor`, `AgentFileOps`.
-- SDK types stay untouched: `AgentSession`, `AgentSessionEvent`.
-- Internal field/method names that do not contain the bare `Agent` word — `listAgents`, `getRecord`, the `agents` map, and `record:` parameters — are left as-is; they are not bare-`Agent` symbols and the acceptance grep does not flag them.
-- No behavior changes: this is a pure rename plus a structurally no-op type consolidation.
-
-## Background
-
-Relevant modules (Lifecycle domain unless noted):
-
-- `src/lifecycle/agent.ts` — defines `Agent`, `AgentInit`, `AgentLifecycleObserver`, and the duplicate `AgentStatus` union; owns the full execution lifecycle (`run`, `resume`, `abort`, `steer`, status transitions, workspace disposal).
-  Contains bare-`Agent` JSDoc and two error strings (`"Agent not configured for execution …"`, `"Agent not configured for resume …"`).
-- `src/lifecycle/agent-manager.ts` — defines `AgentManager`, `AgentManagerObserver` (methods `onAgentStarted` / `onAgentCompleted` / `onAgentCompacted` / `onAgentCreated`), `AgentManagerOptions`, and `AgentSpawnConfig` (out of scope).
-- `src/lifecycle/workspace.ts` — `WorkspaceDisposeOutcome.status` is typed as the internal `AgentStatus`, imported from `#src/lifecycle/agent`.
-- `src/observation/record-observer.ts` — defines `AgentObserverOptions` and the `subscribeAgentObserver` function.
-- `src/service/service.ts` — defines the public `SubagentStatus` union (verbatim duplicate of `AgentStatus`) and re-exports `LifetimeUsage`, `Workspace`, and the four workspace collaborator types from the lifecycle layer.
-- `src/service/service-adapter.ts` — defines the `AgentManagerLike` test seam.
-- `src/types.ts` — barrel that re-exports `Agent` from `#src/lifecycle/agent`; most consumers import `Agent` via this barrel.
-- `test/helpers/make-agent.ts` — exports `createTestAgent`, imported by ~16 test files.
-
-Blast radius is mechanical but wide (~360 occurrences, dominated by the `Agent` class via the `types.ts` barrel).
-`typescript` + `tsserver` are available, so each rename is a scope-aware language-service pass verified by `pnpm run check`; the occurrence count does not drive scope.
-
-Constraints from AGENTS.md and skills that apply:
-
-- Within a package, import siblings via `#src/` / `#test/` aliases (eslint enforces this) — the file moves must preserve alias imports, not introduce relative paths.
-- After a barrel rename, verify at least one consumer still imports the renamed symbol from the barrel — many consumers import `Subagent` from `#src/types`, so this holds.
-- The public `dist/public.d.ts` bundle is rolled from `src/service/service.ts`; run `pnpm run verify:public-types` after touching the public surface or the status consolidation.
-- Load the `mermaid` skill before editing the architecture doc's class/sequence diagrams.
-
-## Design Overview
-
-### Status consolidation and the layering constraint
-
-`AgentStatus` (in `agent.ts`) and `SubagentStatus` (in `service.ts`) are identical seven-member unions (`queued | running | completed | steered | aborted | stopped | error`).
-The issue asks `WorkspaceDisposeOutcome.status` to point at the public `SubagentStatus`.
-
-A naive fix — importing `SubagentStatus` from `service.ts` into `workspace.ts` — would create a circular dependency: `service.ts` already imports the workspace collaborator types (`WorkspaceDisposeOutcome`, …) from `workspace.ts`, so `workspace.ts → service.ts` reverses an existing arrow.
-The correct single home is the lifecycle layer, mirroring how `service.ts` already re-exports `LifetimeUsage` from `#src/lifecycle/usage` and the workspace types from `#src/lifecycle/workspace`:
-
-- Keep the union defined in the lifecycle layer (in the renamed `subagent.ts`), renamed `AgentStatus` → `SubagentStatus`.
-- `service.ts` deletes its local definition and adds `export type { SubagentStatus } from "#src/lifecycle/subagent";` alongside its existing re-exports.
-- `workspace.ts` imports `SubagentStatus` from `#src/lifecycle/subagent` (it already imports `AgentStatus` from the same module today — only the symbol name and, after the file move, the path change).
-
-The `subagent ↔ workspace` relationship is type-only and already exists (`subagent.ts` imports `Workspace` / `WorkspaceProvider` from `workspace.ts`; `workspace.ts` imports the status union from `subagent.ts`), so no new runtime cycle is introduced — type-only imports are erased.
-
-`rollup-plugin-dts` inlines `#src/*` types, so `dist/public.d.ts` still emits the same `SubagentStatus` union literal — structurally a no-op for consumers, confirmed by `verify:public-types`.
-
-```typescript
-// src/lifecycle/subagent.ts (renamed from agent.ts)
-export type SubagentStatus =
-  | "queued" | "running" | "completed" | "steered"
-  | "aborted" | "stopped" | "error";
-
-// src/service/service.ts — delete local def, re-export instead
-export type { SubagentStatus } from "#src/lifecycle/subagent";
-
-// src/lifecycle/workspace.ts
-import type { SubagentStatus } from "#src/lifecycle/subagent";
-export interface WorkspaceDisposeOutcome {
-  status: SubagentStatus;
-  description: string;
-}
-```
-
-### Rename mechanics
-
-Each symbol rename is an atomic, scope-aware language-service operation (the API behind LSP "Rename Symbol"); after each, `pnpm run check` verifies the tree compiles.
-Because a rename updates every reference in one pass and leaves the build green, each logical rename is its own commit with the repository in a valid state — no lift-and-shift staging is required (a rename is not a type replacement; old and new names never coexist).
-
-Symbol renames do not touch comments, JSDoc, or string literals.
-There are 26 bare `Agent` and 4 bare `AgentManager` word-occurrences in `src/lifecycle/` comments/strings (e.g. the two `"Agent not configured …"` error messages and cross-file JSDoc in `turn-limits.ts`, `create-subagent-session.ts`, `subagent-session.ts`).
-The acceptance criterion greps `src/lifecycle/` for bare `Agent` / `AgentManager`, so each rename step must also sweep residual comment/string occurrences.
-Compound names (`AgentSession`, `AgentInvocation`, `AgentTypeRegistry`) are not bare-word matches and stay.
-
-### Full-consistency adjacent identifiers
-
-Per the scope decision, the rename extends to the rest of the cluster's naming so no `Agent`-as-subagent identifier survives:
-
-- `src/observation/record-observer.ts`: `subscribeAgentObserver` → `subscribeSubagentObserver`, `AgentObserverOptions` → `SubagentObserverOptions`.
-- `src/lifecycle/subagent-manager.ts`: `SubagentManagerObserver` methods `onAgentStarted` / `onAgentCompleted` / `onAgentCompacted` / `onAgentCreated` → `onSubagentStarted` / `onSubagentCompleted` / `onSubagentCompacted` / `onSubagentCreated` (8 + 11 + 6 + 14 call sites across `src/` and `test/`, all updated by the language-service rename).
-- `test/helpers/make-agent.ts`: `createTestAgent` → `createTestSubagent`, file → `make-subagent.ts` (~16 importers, including `make-deps.ts` and `ui-stubs.ts`).
-
-## Module-Level Changes
-
-Renamed files (git move, preserving `#src/` / `#test/` alias imports):
-
-- `src/lifecycle/agent.ts` → `src/lifecycle/subagent.ts`
-- `src/lifecycle/agent-manager.ts` → `src/lifecycle/subagent-manager.ts`
-- `test/lifecycle/agent.test.ts` → `test/lifecycle/subagent.test.ts`
-- `test/lifecycle/agent-manager.test.ts` → `test/lifecycle/subagent-manager.test.ts`
-- `test/helpers/make-agent.ts` → `test/helpers/make-subagent.ts`
-- `test/helpers/make-agent.test.ts` → `test/helpers/make-subagent.test.ts`
-
-Changed (symbols, members, imports, comments/strings):
-
-- `src/lifecycle/subagent.ts` — `Agent` → `Subagent`, `AgentInit` → `SubagentInit`, `AgentLifecycleObserver` → `SubagentLifecycleObserver`, `AgentStatus` → `SubagentStatus` (kept here as the single home); update JSDoc and the two error strings.
-- `src/lifecycle/subagent-manager.ts` — `AgentManager` → `SubagentManager`, `AgentManagerObserver` → `SubagentManagerObserver` (+ `onAgent*` methods → `onSubagent*`), `AgentManagerOptions` → `SubagentManagerOptions`; `AgentSpawnConfig` unchanged; update header comment.
-- `src/lifecycle/workspace.ts` — import `SubagentStatus` from `#src/lifecycle/subagent`; `WorkspaceDisposeOutcome.status` retyped.
-- `src/service/service.ts` — delete local `SubagentStatus` definition; add `export type { SubagentStatus } from "#src/lifecycle/subagent";`.
-- `src/service/service-adapter.ts` — `AgentManagerLike` → `SubagentManagerLike`; update header comment referencing `AgentManager`.
-- `src/observation/record-observer.ts` — `subscribeAgentObserver` → `subscribeSubagentObserver`, `AgentObserverOptions` → `SubagentObserverOptions`; update header comment.
-- `src/types.ts` — barrel re-export `export { Agent } from "#src/lifecycle/agent";` → `export { Subagent } from "#src/lifecycle/subagent";`.
-- All consumers of the renamed symbols across `src/` and `test/` (tools, UI, runtime, `index.ts`, session, observation, and their tests) — updated transitively by each language-service rename.
-  Out-of-scope `Agent*` symbols in these files are untouched.
-- `test/helpers/make-subagent.ts`, `make-deps.ts`, `ui-stubs.ts`, and ~16 test importers — `createTestAgent` → `createTestSubagent` and updated import paths.
-- `docs/architecture/architecture.md` — file-listing entries (`agent.ts`, `agent-manager.ts`), class/sequence Mermaid diagrams, the type-complexity table row (`AgentInit` → `SubagentInit`, module `agent` → `subagent`), and current-state prose naming the renamed cluster.
-  Out-of-scope `Agent*` names (`AgentTool`, `AgentSession`, `AgentTypeRegistry`, …) and historical phase narrative stay as written.
-
-No exports are removed from the public surface; the barrel rename swaps one name for another with many live consumers.
-Also swept for the `package-pi-subagents` SKILL.md, which documents internals (`AgentManager`, `Agent`, `make-agent`): update its dependency-flow sketch and module table to the new names.
-
-## Test Impact Analysis
-
-This is a pure rename plus a no-op type consolidation, so the extraction-style test questions resolve simply:
-
-1. New tests enabled: none — no new seams or behavior are introduced.
-2. Tests made redundant: none — no test is duplicated or subsumed.
-3. Tests that must stay as-is (renamed/retargeted only): all of them.
-   `test/lifecycle/subagent.test.ts`, `subagent-manager.test.ts`, `record-observer.test.ts`, `service-adapter.test.ts`, and every `createTestSubagent` consumer continue to exercise the same behavior under the new names.
-   The status consolidation leaves `WorkspaceDisposeOutcome` behavior identical, so workspace/service tests are unchanged beyond the symbol name.
-
-## TDD Order
-
-This is a refactor with no red phase; each step is a green checkpoint verified by `pnpm run check` && `pnpm -r run test` (and `verify:public-types` where the public surface is touched) before committing.
-Steps are independent renames ordered smallest-blast-first where practical; any order keeps the tree green.
-
-1. Consolidate the status union.
-   In `agent.ts` rename `AgentStatus` → `SubagentStatus` and keep the definition there; delete the duplicate in `service.ts` and re-export from the lifecycle module; retype `workspace.ts`.
-   Run `pnpm run check`, tests, and `pnpm run verify:public-types` to confirm the bundle is unchanged.
-   Commit: `refactor: consolidate AgentStatus into public SubagentStatus (#280)`.
-2. Rename the `Agent` class cluster.
-   `Agent` → `Subagent`, `AgentInit` → `SubagentInit`, `AgentLifecycleObserver` → `SubagentLifecycleObserver`; git-move `agent.ts` → `subagent.ts` and `test/lifecycle/agent.test.ts` → `subagent.test.ts`; update the `types.ts` barrel re-export and the `workspace.ts` / `service.ts` import paths to `#src/lifecycle/subagent`; sweep residual bare-`Agent` JSDoc and the two error strings in `subagent.ts`.
-   Commit: `refactor: rename Agent class to Subagent (#280)`.
-3. Rename the manager cluster.
-   `AgentManager` → `SubagentManager`, `AgentManagerObserver` → `SubagentManagerObserver` (+ `onAgent*` methods → `onSubagent*`), `AgentManagerOptions` → `SubagentManagerOptions`; git-move `agent-manager.ts` → `subagent-manager.ts` and its test file; sweep residual bare-`AgentManager` comments.
-   `AgentSpawnConfig` left untouched.
-   Commit: `refactor: rename AgentManager cluster to SubagentManager (#280)`.
-4. Rename the observation seam.
-   `subscribeAgentObserver` → `subscribeSubagentObserver`, `AgentObserverOptions` → `SubagentObserverOptions` in `record-observer.ts`; update its test and header comment.
-   Commit: `refactor: rename subscribeAgentObserver to subscribeSubagentObserver (#280)`.
-5. Rename the adapter seam.
-   `AgentManagerLike` → `SubagentManagerLike` in `service-adapter.ts`; update its test and header comment.
-   Commit: `refactor: rename AgentManagerLike to SubagentManagerLike (#280)`.
-6. Rename the test helper.
-   `createTestAgent` → `createTestSubagent`; git-move `make-agent.ts` → `make-subagent.ts` and `make-agent.test.ts` → `make-subagent.test.ts`; update all importers and `#test/helpers/make-agent` paths.
-   Commit: `test: rename createTestAgent to createTestSubagent (#280)`.
-7. Update docs.
-   Architecture doc current-state references (file listing, Mermaid diagrams, complexity table, prose) and the `package-pi-subagents` SKILL.md internals; load the `mermaid` skill before editing diagrams.
-   Final verification: `pnpm run check`, `pnpm run lint`, `pnpm -r run test`, `pnpm fallow dead-code`, `pnpm run verify:public-types`, and `grep -rnE '\bAgent(Manager|Init)?\b' src/lifecycle/` returns no bare in-scope matches.
-   Commit: `docs: update architecture and skill docs for Subagent rename (#280)`.
-
-## Risks and Mitigations
-
-- Risk: a symbol rename misses string literals or comments, leaving bare `Agent` that the acceptance grep flags.
-  Mitigation: each rename step explicitly sweeps comments/strings; the final grep gate in step 7 is the backstop.
-- Risk: pointing `workspace.ts` at the public `SubagentStatus` introduces a `lifecycle → service` cycle.
-  Mitigation: keep the union's home in the lifecycle layer (`subagent.ts`) and re-export from `service.ts`, mirroring the existing `LifetimeUsage` / workspace re-export pattern — no new arrow.
-- Risk: the public type bundle changes shape.
-  Mitigation: `verify:public-types` after step 1 and step 7; the union is identical, so the bundle differs only in provenance, not content.
-- Risk: a file move accidentally rewrites `#src/` alias imports to relative paths.
-  Mitigation: use `git mv` and rely on the language service for import updates; eslint's no-relative-sibling rule catches regressions during `pnpm run lint`.
-- Risk: over-reach into out-of-scope `Agent*` names.
-  Mitigation: the rename is symbol-scoped (not text find-replace); the Non-Goals list enumerates the protected names, and the acceptance grep targets only bare `Agent` / `AgentManager` / `AgentInit` / `Agent*Observer`.
-
-## Open Questions
-
-- Whether to later lowercase incidental prose uses of "Agent" (meaning subagent) in the architecture doc's event tables and history sections — deferred; this plan updates symbol/file names and current-state references, leaving historical narrative as written.
-- Whether `listAgents` / `getRecord` / the `agents` map deserve a follow-up naming pass — deferred; they are not bare-`Agent` symbols and fall outside the approved scope.
-
-[#265]: https://github.com/gotgenes/pi-packages/issues/265

package/docs/plans/0360-custom-agents-default-append.md

@@ -1,132 +0,0 @@
----
-issue: 360
-issue_title: "fix(pi-subagents): custom agents default to replace mode instead of append"
----
-
-# Custom agents default to append prompt mode
-
-## Problem Statement
-
-Custom agents loaded from `.pi/agents/*.md` (and the global agents directory) default to `replace` prompt mode when no `prompt_mode` frontmatter key is present, while built-in agents default to `append`.
-This asymmetry surprises users: a custom agent with no explicit `prompt_mode` silently drops the parent system prompt (AGENTS.md, skills, project conventions) and instead shows the bare replace-mode header. @jeffutter reported this in [#180 (comment)](https://github.com/gotgenes/pi-packages/issues/180#issuecomment-4644369646) — their `researcher` agent rendered `"You are a pi coding agent sub-agent."` instead of inheriting the parent prompt.
-
-The root cause is the ternary in `src/config/custom-agents.ts` line 65:
-
-```typescript
-promptMode: fm.prompt_mode === "append" ? "append" : "replace",
-```
-
-Any value other than the literal `"append"` — including `undefined` (key omitted) — falls through to `replace`.
-
-## Goals
-
-- Custom agents without an explicit `prompt_mode` frontmatter key default to `append`, matching the built-in default in `agent-types.ts`.
-- Only `prompt_mode: replace` (explicit opt-in) selects replace mode.
-- Update tests and user-facing documentation to reflect the new default.
-
-This is a **breaking change**: any existing `.pi/agents/*.md` that omits `prompt_mode` flips from `replace` to `append` on upgrade, so those agents begin inheriting the parent system prompt (AGENTS.md / CLAUDE.md / skills) where they previously did not.
-The behavior change is triggered purely by upgrading, with no config edit — it warrants a `fix!:` commit and a `BREAKING CHANGE:` footer so release-please cuts a major version.
-Users who relied on the old implicit-`replace` behavior must add `prompt_mode: replace` explicitly to restore it.
-
-## Non-Goals
-
-- No change to built-in agents (`default-agents.ts`): `Explore` and `Plan` keep their explicit `promptMode: "replace"`, `general-purpose` keeps `append`.
-- No change to the prompt-assembly logic in `src/session/prompts.ts` — only the default a custom agent resolves to changes.
-- No change to other frontmatter field defaults or parsers.
-
-## Background
-
-- `src/config/custom-agents.ts` — `loadFromDir` parses each `.md` file's frontmatter into an `AgentConfig`.
-  Line 65 is the only place a custom agent's `promptMode` is decided.
-- `src/config/agent-types.ts:118` — the built-in absolute-fallback config uses `promptMode: "append"`.
-- `src/session/prompts.ts:36` — `buildAgentPrompt` branches on `config.promptMode === "append"`; append mode threads the parent system prompt (AGENTS.md / CLAUDE.md) into the child, replace mode does not.
-- The field-parser convention documented at the top of the parser section of `custom-agents.ts` is "omitted → default, none/empty → nothing, value → exact".
-  Today `prompt_mode` violates the spirit of "omitted → default" by mapping omitted to `replace` rather than the system default `append`.
-  This fix aligns it.
-
-Constraint from AGENTS.md: this is the `pi-subagents` package — Biome handles formatting, the upstream vitest suite is a regression canary, and all tests must pass before publishing.
-
-## Design Overview
-
-Flip the ternary so `replace` requires an explicit opt-in and everything else (including omitted) defaults to `append`:
-
-```typescript
-promptMode: fm.prompt_mode === "replace" ? "replace" : "append",
-```
-
-Decision table for the resolved `promptMode`:
-
-| `prompt_mode` frontmatter value | Before  | After   |
-| ------------------------------- | ------- | ------- |
-| omitted / `undefined`           | replace | append  |
-| `replace`                       | replace | replace |
-| `append`                        | append  | append  |
-| unknown (e.g. `merge`)          | replace | append  |
-
-Unknown values now resolve to `append` rather than `replace`.
-This is the safer fallback: an append-mode agent inherits the parent prompt (a superset), so a typo degrades to "inherits everything" rather than "silently drops project context".
-
-No type shape changes — `promptMode` remains `"replace" | "append"` (`src/types.ts`).
-
-## Module-Level Changes
-
-- `src/config/custom-agents.ts` (line 65) — flip the ternary to `fm.prompt_mode === "replace" ? "replace" : "append"`.
-- `src/ui/agent-creation-wizard.ts` (line 106) — update the inline frontmatter doc comment: `Default: replace` → `Default: append` for `prompt_mode`.
-  The surrounding guidelines (lines 117–118) already describe both modes correctly and need no change.
-- `README.md` (line 187) — change the `prompt_mode` default column from `` `replace` `` to `` `append` ``.
-  Keep the cell's behavioral description of `replace`/`append` unchanged.
-- `test/config/custom-agents.test.ts` — update the two tests that assert the old default (see TDD Order).
-
-No architecture-doc references to the default value were found (`docs/architecture/` describes module layout, not field defaults). `CHANGELOG.md` is owned by release-please and is not edited.
-
-## Test Impact Analysis
-
-This is a behavior fix, not an extraction, so no new test layers are enabled and no tests become redundant.
-Existing tests in `test/config/custom-agents.test.ts` directly exercise the changed line and must be updated to assert the new default:
-
-1. `"uses sensible defaults when frontmatter is empty"` — empty frontmatter currently asserts `promptMode` is `"replace"`; must become `"append"`.
-2. `"defaults unknown prompt_mode to replace"` — feeds `prompt_mode: merge` and asserts `"replace"`; must be renamed to `"defaults unknown prompt_mode to append"` and assert `"append"`.
-3. `"loads a basic agent with all frontmatter fields"` (explicit `prompt_mode: replace`) and `"handles prompt_mode: append"` — both pass an explicit value and stay as-is; they pin the explicit-opt-in behavior.
-4. `"uses sensible defaults when no frontmatter at all"` (the `bare` agent) does not currently assert `promptMode` — add an assertion that it resolves to `"append"` to lock the no-frontmatter path.
-
-## TDD Order
-
-1. Red → Green: update default-mode tests in `test/config/custom-agents.test.ts`.
-   - Change the empty-frontmatter test to expect `promptMode` `"append"`.
-   - Rename the unknown-mode test to `"defaults unknown prompt_mode to append"` and expect `"append"`.
-   - Add a `promptMode` assertion (`"append"`) to the no-frontmatter (`bare`) test.
-   - These fail against the current line 65, then pass after the source fix.
-   - Apply the one-line fix in `src/config/custom-agents.ts` in the same cycle (the test file and source are coupled — the type checker and assertions move together).
-   - Commit (breaking — include the footer):
-
-     ```text
-     fix(pi-subagents)!: default custom agents to append prompt mode (#360)
-
-     BREAKING CHANGE: Custom agents in .pi/agents/*.md that omit the
-     prompt_mode frontmatter key now default to append instead of replace,
-     so they inherit the parent system prompt (AGENTS.md / CLAUDE.md /
-     skills). Add `prompt_mode: replace` explicitly to restore the previous
-     standalone-prompt behavior.
-     ```
-
-2. Docs: update user-facing default documentation.
-   - `src/ui/agent-creation-wizard.ts` — `prompt_mode` `Default: replace` → `Default: append`.
-   - `README.md` — `prompt_mode` default cell → `` `append` ``.
-   - Commit: `docs(pi-subagents): note custom agents default to append prompt mode (#360)`.
-
-(Optional: steps 1 and 2 may be combined into a single `fix!:` commit since the doc updates are part of the same behavioral correction; keeping them split keeps the source/test change isolated from prose.
-If combined, the `BREAKING CHANGE:` footer lives on the single commit.)
-
-## Risks and Mitigations
-
-- Risk: existing users rely on the old implicit-`replace` behavior for custom agents that omit `prompt_mode`.
-  Mitigation: append mode is a superset (it inherits the parent prompt plus the agent body); the worst case is an agent that now sees more context than before, not less.
-  Users who genuinely want a standalone prompt can add `prompt_mode: replace` explicitly.
-  The issue frames the old behavior as a bug, and the maintainer authored it.
-- Risk: the upstream vitest regression canary asserts the old default somewhere.
-  Mitigation: `grep` confirms the only default-asserting tests are in `test/config/custom-agents.test.ts`; run `pnpm --filter @gotgenes/pi-subagents run test` to confirm the full suite stays green.
-
-## Open Questions
-
-None.
-The issue's proposed fix is unambiguous and the change surface is fully enumerated above.