@gotgenes/pi-subagents 13.2.0 → 13.2.2

package/docs/retro/0264-remove-extension-lifecycle-control.md

@@ -9,7 +9,7 @@ issue_title: "Remove isolated / extensions:false / noSkills from core"
 
 ### Session summary
 
-Planned Phase 16, Step 4: removing the extension-lifecycle-control axis (`isolated`, `extensions: false`, `noSkills`) from the pi-subagents core per ADR 0002.
+Planned Phase 16, Step 4: removing the extension-lifecycle-control axis (`isolated`, `extensions: false`, `noSkills`) from the pi-subagents core per [ADR-0002].
 Confirmed all three prerequisite Phase 16 steps (#261, #262, #263) are closed, so the explicit "deny-at-use" dependency is satisfied.
 Produced a four-cycle TDD plan (`isolated` → `extensions` → `skills`/`noSkills`/preload → docs) and committed it.
 
@@ -87,3 +87,5 @@ The run had zero rework and a PASS pre-completion review; test count moved 1016
 1. Appended this Final Retrospective stage entry to `packages/pi-subagents/docs/retro/0264-remove-extension-lifecycle-control.md`.
 2. Considered but **declined** (user: "too narrow") a removal-coupling detection rule for `.pi/prompts/plan-issue.md` — the heuristic that a field named for removal may be the mechanism behind a separate surviving feature.
    No prompt or `AGENTS.md` changes were made this retro.
+
+[ADR-0002]: ../decisions/0002-extensions-on-a-minimal-core.md

package/docs/retro/0270-type-consumable-public-surface.md

@@ -34,7 +34,7 @@ The plan adds a `rollup-plugin-dts` build that bundles `src/service/service.ts`
 
 ### Session summary
 
-Executed all four build-order steps: added `rollup` + `rollup-plugin-dts` and a `build:types` script that bundles `src/service/service.ts` into a self-contained `dist/public.d.ts`; wired conditional `exports` (`types` + `default`, fixing the stale path) with a `prepack` hook and a `files` allowlist; added a `pnpm pack` → throwaway-consumer → `tsc` verification harness (`scripts/verify-public-types.sh`) plus a CI step; and recorded ADR 0003.
+Executed all four build-order steps: added `rollup` + `rollup-plugin-dts` and a `build:types` script that bundles `src/service/service.ts` into a self-contained `dist/public.d.ts`; wired conditional `exports` (`types` + `default`, fixing the stale path) with a `prepack` hook and a `files` allowlist; added a `pnpm pack` → throwaway-consumer → `tsc` verification harness (`scripts/verify-public-types.sh`) plus a CI step; and recorded [ADR-0003].
 A fifth commit documented the new build step in the `package-pi-subagents` skill (reviewer WARN).
 Root `pnpm run check`, root `pnpm run lint`, and `verify:public-types` all pass.
 
@@ -91,7 +91,7 @@ Two CI failures during the ship stage — a pre-existing `pnpm fallow dead-code`
 - The "pi-subagents-* extensions should use the released, npm-installed version, no workspace trickery" directive arrived mid-planning, after initial exploration.
   Surfacing the consumption-model constraint at kickoff would have framed the scope question earlier.
   Opportunity, not criticism — the same exchange produced the high-value chicken-and-egg catch (the registry version with the fix cannot exist until #270 publishes) that correctly deferred the worktrees flip to #263.
-- A brief "there is no ADR 0003" → "My mistake" exchange; no rework.
+- A brief "there is no [ADR-0003]" → "My mistake" exchange; no rework.
 
 ### Diagnostic details
 
@@ -104,3 +104,5 @@ Two CI failures during the ship stage — a pre-existing `pnpm fallow dead-code`
 
 1. `.pi/prompts/ship-issue.md` — renamed Step 2 to "Pre-push checks" and added `pnpm fallow dead-code` alongside `pnpm run lint`, with a one-line note that the gate is `main`-only and blocks pushes regardless of who introduced the failure.
 2. `AGENTS.md` (§ Code Style pnpm rules) — added a rule to run `pnpm install` and commit the updated `pnpm-lock.yaml` in the same commit when a `package.json` dependency changes, since CI installs with `--frozen-lockfile`.
+
+[ADR-0003]: ../decisions/0003-publish-bundled-type-declarations.md

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

@@ -37,3 +37,44 @@ Test count went from 960 → 973 (+13 net: +18 new tests, −5 removed tests for
 - The `get-result-tool.test.ts` verbose conversation test needed updating: previously built a mock session with messages and passed it directly; now the stub's `getConversation` must return the expected text via `mockReturnValue`.
 - Pre-completion reviewer returned **WARN** for two stale `architecture.md` passages: (1) conversation-viewer description still said "subscribes directly to `AgentSession`"; (2) `Agent` classDiagram still listed `queueSteer`/`flushPendingSteers` as public and omitted the 6 new public members.
   Both fixed in a `docs:` commit before closing.
+
+## Stage: Final Retrospective (2026-05-30T16:00:00Z)
+
+### Session summary
+
+Issue #277 shipped across three sessions (planning, TDD, ship) in a single day.
+All 8 TDD steps completed cleanly, 13 implementation commits landed, and `pi-subagents-v13.2.0` released.
+
+### Observations
+
+#### What went well
+
+- Planning correctly identified scope beyond the issue's three proposed methods: `getContextPercent()`, `subscribeToUpdates()`, and `messages` were needed to satisfy the "no production module outside `lifecycle/` references `AgentSession`" acceptance criterion.
+  This prevented mid-TDD design revisions.
+- The discovery that `subscribeAgentObserver` already accepted `SubscribableSession` meant adding `subscribe()` to `SubagentSession` was sufficient for observer wiring — no type cast or adapter needed.
+- Lift-and-shift execution was precise: new methods added first (steps 1-2), callers migrated by concern (steps 3-6), old getter removed last (step 7).
+  No step broke any other step's tests.
+- Pre-completion reviewer caught two stale `architecture.md` passages (classDiagram with removed public methods, conversation-viewer description) that the implementation steps missed.
+  Both fixed in a `docs:` commit before closing.
+
+#### What caused friction (agent side)
+
+1. `missing-context` — `MockSession` interface lacked `messages`.
+   The field existed at runtime (via `createMockSession`'s spread + `Record<string, unknown>` return type) but the `MockSession` interface didn't declare it.
+   Adding `messages` to `createSubagentSessionStub` triggered a type error.
+   Impact: 2 extra edits to `mock-session.ts` (add field to interface, add to `base` object), no rework.
+2. `missing-context` — `get-result-tool.test.ts` conversation test relied on raw mock session messages.
+   After migrating to `record.getConversation()`, the stub's `getConversation` returned `""` by default.
+   The test needed `stub.getConversation.mockReturnValue("...")` instead.
+   Impact: 1 test update, caught immediately by `pnpm vitest run`.
+3. `missing-context` — `foreground-runner.test.ts` called `onSessionCreated(record, mockSess)` with 2 args.
+   After narrowing the callback to `(agent: Agent)`, the first test lacked `record.subagentSession` setup.
+   Impact: 2 test blocks updated, caught by `pnpm vitest run`.
+4. `missing-context` — First `get-result-tool.ts` edit left a double-nested `if (conversation)` block.
+   The multi-edit replaced the outer `if (params.verbose && record.session)` but preserved the inner guard, creating `if (conversation) { if (conversation) { ... } }`.
+   Impact: Self-caught on immediate read-back; fixed in the same commit, no rework.
+
+#### What caused friction (user side)
+
+- None observed.
+  The user's involvement was limited to the `/plan-issue`, `/tdd-plan`, `/ship-issue`, and `/retro` prompts — no mid-session corrections or redirections were needed.

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

@@ -0,0 +1,96 @@
+---
+issue: 280
+issue_title: "Rename the internal Agent class to Subagent"
+---
+
+# Retro: #280 — Rename the internal `Agent` class to `Subagent`
+
+## Stage: Planning (2026-05-31T00:09:51Z)
+
+### Session summary
+
+Produced a numbered implementation plan to rename the subagent-instance cluster in `src/lifecycle/` from the bare `Agent*` family to `Subagent*`, consolidate the duplicate `AgentStatus` union into the public `SubagentStatus`, and update the architecture doc.
+The plan is a 7-step refactor (no behavior change), each step an atomic language-service rename that leaves the tree green.
+
+### Observations
+
+- Scope decisions confirmed with the user via `ask_user`: (1) rename the module files too (`agent.ts` → `subagent.ts`, `agent-manager.ts` → `subagent-manager.ts`, plus test/helper files), and (2) full-consistency rename of adjacent identifiers — `subscribeAgentObserver`, the `SubagentManagerObserver` `onAgent*` methods, and the `createTestAgent` helper.
+- Layering catch: pointing `WorkspaceDisposeOutcome.status` directly at `service.ts`'s `SubagentStatus` would create a `lifecycle → service` cycle (`service.ts` already imports the workspace collaborator types).
+  Resolution: keep the union's single home in the lifecycle layer (`subagent.ts`) and have `service.ts` re-export it, mirroring the existing `LifetimeUsage` / workspace re-export pattern.
+- Acceptance-grep catch: the issue's `grep src/lifecycle/` for bare `Agent` matches comments and string literals (e.g. the two `"Agent not configured …"` error messages), not just symbols.
+  The language-service rename does not touch those, so each step must sweep residual comment/string occurrences; step 7 has a final grep gate.
+- Compound names (`AgentSession`, `AgentInvocation`, `AgentTypeRegistry`, `AgentTool`, `AgentSpawnConfig`) are not bare-word matches and are explicitly out of scope.
+- Non-breaking — `refactor:` commits throughout; `verify:public-types` runs after the status consolidation and the final step since the public bundle (`dist/public.d.ts`) is rolled from `src/service/service.ts`.
+- Also flagged the `package-pi-subagents` SKILL.md for an internals-naming update (it references `AgentManager`, `Agent`, `make-agent`).
+
+## Stage: Implementation — TDD (2026-05-31T00:38:55Z)
+
+### Session summary
+
+Completed 6 refactor commits (steps 1–6 from the plan, with step 5 folded into step 3) plus a `test:` commit for the helper rename and a `docs:` commit for the architecture doc update.
+All 973 tests pass across 59 test files with no test count delta.
+Pre-completion reviewer returned PASS with all 5 acceptance criteria verified.
+
+### Observations
+
+- Step 5 (`AgentManagerLike` → `SubagentManagerLike`) was automatically folded into step 3 because the bulk-rename Python script replaced all `AgentManager*` compounds at once — no separate commit was needed or appropriate.
+- The acceptance grep (`grep -rnE '\bAgent(Manager|Init)?\b' src/lifecycle/`) also flags bare `Agent` in comments and error strings; each rename step swept those manually since the language-service rename does not touch non-symbol text.
+- `sed` with negative lookaheads failed on macOS for the `notification.ts` file; fell back to a two-pass approach (sed for the import, then `perl -i -0pe` with negative lookahead for the body).
+- `describe("Agent — ...)` test block names used em-dashes (Unicode U+2014); `sed` with `\u2014` escape did not match on macOS — required Python `re.sub` with the literal character.
+- The `SubagentStatus` type definition was kept in `src/lifecycle/subagent.ts` (single home) and re-exported from `src/service/service.ts`, matching the existing `LifetimeUsage` / workspace re-export pattern and avoiding a `lifecycle → service` cycle.
+- Docs: the architecture doc's session-encapsulation table had misaligned Markdown table columns after the rename (cell widths changed); `rumdl fmt` auto-fixed them.
+- Pre-completion reviewer: PASS — all deterministic checks, all 5 acceptance criteria, conventional commits, docs, Mermaid diagrams, and dead-code gate confirmed clean.
+
+## Stage: Final Retrospective (2026-05-31T01:05:57Z)
+
+### Session summary
+
+Shipped the full Planning → TDD → Ship lifecycle for the internal `Agent` → `Subagent` rename across `@gotgenes/pi-subagents`: 7 implementation commits (6 `refactor:`/`test:` + 1 `docs:`), 973 tests green throughout, CI passed on `27abb5aa`, and issue #280 closed.
+No release was triggered (all `refactor:`/`test:`/`docs:` commits), so no release-please PR appeared — expected.
+
+### Observations
+
+#### What went well
+
+- Two planning-stage catches prevented downstream rework: the `lifecycle → service` import cycle (resolved by keeping `SubagentStatus`'s single home in `subagent.ts` and re-exporting from `service.ts`) and the acceptance grep matching bare `Agent` in comments/strings (so each step swept non-symbol text).
+  Both were anticipated in the plan and held during execution.
+- Incremental verification carried the rename safely: `pnpm run check` plus the affected test files ran after every step, so the text-based substitution mistakes were caught instantly and never reached a commit.
+  The pre-completion reviewer then returned a clean PASS with nothing to fix.
+- The status re-export needed a follow-up `import type { SubagentStatus }` because `export type { … } from` does not create a local binding for `SubagentRecord` to reference — `pnpm run check` flagged it immediately, a one-edit fix.
+
+#### What caused friction (agent side)
+
+- `wrong-abstraction` — The plan specified each rename as a "scope-aware language-service pass" (`findRenameLocations`), but the execution toolkit has no LSP-rename tool — only `Edit`, `Bash` (`sed`/`perl`/`python`), and `grep`.
+  Execution fell back to text substitution, which is exactly why the comment/string sweep was needed and why the regex gymnastics below happened.
+  Impact: added friction but no rework — `tsc` + tests caught every gap; no incorrect commit landed.
+- `other` (cross-platform tooling) — Repeated silent failures from BSD `sed` / `perl` one-liners: BSD `sed` lacks `\b` and lookahead; `perl -i ''` is malformed (the `-i ''` form is a `sed`-ism); neither interprets `\uXXXX` escapes, so em-dash `describe("Agent — …")` blocks and `notification.ts` body renames did not match.
+  Each failure forced a grep-verify-redo loop, ultimately resolved by switching to Python `re.sub`.
+  Impact: roughly 5–8 extra tool calls across the TDD stage; no rework beyond the redo cycles.
+
+#### What caused friction (user side)
+
+- None.
+  The user's two `ask_user` answers at planning time (file renames + full-consistency adjacent identifiers) front-loaded every scope decision, so the TDD and Ship stages ran without a single mid-course correction.
+
+### Diagnostic details
+
+- **Model-performance correlation** — One subagent dispatched (`pre-completion-reviewer`) on judgment-heavy review work (acceptance verification, Mermaid validation via `mmdc`, dead-code gate); appropriate match, no mismatch.
+- **Escalation-delay tracking** — The `notification.ts` body rename cycled ~4–5 consecutive `sed`/`perl`/`grep` calls on the same substitution before switching to `perl -i -0pe`; under the 5-call threshold but the closest the session came.
+  The general lesson (prefer Python `re.sub`) generalizes the fix.
+- **Unused-tool detection** — No Explore/`colgrep` gap: the codebase was already understood from planning, and an exact symbol rename is not a semantic-search task.
+  The only "missing capability" is a language-service rename tool, which is not in the toolkit — a genuine gap, not an unused option.
+- **Feedback-loop gap analysis** — No gap: `pnpm run check` and affected tests ran after each step (incremental); `pnpm run lint`, `pnpm fallow dead-code`, and `verify:public-types` ran as the final batch.
+  Verification cadence was correct.
+
+### Changes made
+
+1. Appended this Final Retrospective stage entry to `packages/pi-subagents/docs/retro/0280-rename-agent-to-subagent.md`.
+2. Strengthened the global `APPEND_SYSTEM.md` "Shell Commands" rule to name the literal absolute-path `cd` form (e.g. `cd /Users/you/project &&`), not just `cd $CWD &&` — the existing rule failed to catch the literal-path form that agents actually emit.
+   This file is global (`~/.pi/agent/APPEND_SYSTEM.md`), outside the repo, so it is not committed here.
+3. Added a monorepo-specific line to `AGENTS.md` § Monorepo Structure: prefer `pnpm --filter @gotgenes/<pkg> run <script>` (or `pnpm -C packages/<pkg> run <script>`) from the root over `cd packages/<pkg> && pnpm run <script>`.
+   Prompted by excessive `cd` chaining observed across this session's Ship and Retro stages.
+
+### Follow-ups considered (not applied)
+
+1. Proposed adding a bulk-substitution tooling rule (prefer Python `re.sub` over `sed`/`perl` one-liners, since BSD `sed` lacks `\b`/lookahead and `\uXXXX` is uninterpreted) to the `code-design` skill's Tooling section.
+   The user opted to record the observation here only and skip the skill change.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "13.2.0",
+  "version": "13.2.2",
   "type": "module",
   "exports": {
     ".": {

package/src/index.ts

@@ -23,11 +23,11 @@ import {
 import { AgentTypeRegistry } from "#src/config/agent-types";
 import { loadCustomAgents } from "#src/config/custom-agents";
 import { SessionLifecycleHandler, ToolStartHandler } from "#src/handlers/index";
-import { AgentManager, type AgentManagerObserver } from "#src/lifecycle/agent-manager";
 import { createChildLifecyclePublisher } from "#src/lifecycle/child-lifecycle";
 import { ConcurrencyQueue } from "#src/lifecycle/concurrency-queue";
 import { createSubagentSession, type SubagentSessionDeps } from "#src/lifecycle/create-subagent-session";
 import { buildParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import { SubagentManager, type SubagentManagerObserver } from "#src/lifecycle/subagent-manager";
 import { buildEventData, type NotificationDetails, NotificationManager } from "#src/observation/notification";
 import { createNotificationRenderer } from "#src/observation/renderer";
 import { createSubagentRuntime } from "#src/runtime";
@@ -56,7 +56,7 @@ export default function (pi: ExtensionAPI) {
   const runtime = createSubagentRuntime();
 
   // ---- Notification system ----
-  // runtime.widget is assigned after AgentManager construction; arrow closures
+  // runtime.widget is assigned after SubagentManager construction; arrow closures
   // capture `runtime` by reference so they always read the current value.
   const notifications = new NotificationManager(
     (msg, opts) => pi.sendMessage(msg, opts),
@@ -76,8 +76,8 @@ export default function (pi: ExtensionAPI) {
   settings.load();
 
   // Observer: receives agent lifecycle notifications and dispatches events/notifications.
-  const observer: AgentManagerObserver = {
-    onAgentStarted(record) {
+  const observer: SubagentManagerObserver = {
+    onSubagentStarted(record) {
       // Emit started event when agent transitions to running (including from queue).
       pi.events.emit("subagents:started", {
         id: record.id,
@@ -85,7 +85,7 @@ export default function (pi: ExtensionAPI) {
         description: record.description,
       });
     },
-    onAgentCompleted(record) {
+    onSubagentCompleted(record) {
       // Emit lifecycle event based on terminal status.
       const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
       const eventData = buildEventData(record);
@@ -110,7 +110,7 @@ export default function (pi: ExtensionAPI) {
 
       notifications.sendCompletion(record);
     },
-    onAgentCompacted(record, info) {
+    onSubagentCompacted(record, info) {
       // Emit compacted event when agent's session compacts (preserves count on record).
       pi.events.emit("subagents:compacted", {
         id: record.id,
@@ -121,7 +121,7 @@ export default function (pi: ExtensionAPI) {
         compactionCount: record.compactionCount,
       });
     },
-    onAgentCreated(record) {
+    onSubagentCreated(record) {
       // Emit created event for background agents (before startAgent / queue drain).
       pi.events.emit("subagents:created", {
         id: record.id,
@@ -150,7 +150,7 @@ export default function (pi: ExtensionAPI) {
     lifecycle: createChildLifecyclePublisher((channel, data) => pi.events.emit(channel, data)),
   };
 
-  // ConcurrencyQueue: scheduling extracted from AgentManager.
+  // ConcurrencyQueue: scheduling extracted from SubagentManager.
   // startAgent callback forward-references manager via closure (safe — drain is never called during construction).
   const queue = new ConcurrencyQueue(
     () => settings.maxConcurrent,
@@ -161,7 +161,7 @@ export default function (pi: ExtensionAPI) {
     },
   );
 
-  const manager = new AgentManager({
+  const manager = new SubagentManager({
     createSubagentSession: (params) => createSubagentSession(params, subagentSessionDeps),
     baseCwd: process.cwd(),
     observer,

package/src/lifecycle/create-subagent-session.ts

@@ -5,7 +5,7 @@
  * `runAgent()` did up front: detect the environment, assemble the session config,
  * create the SDK session, publish `spawning`/`session-created`, bind extensions,
  * and apply the recursion guard. It returns a fully usable `SubagentSession` —
- * `Agent` then only coordinates (turn loop, steer, dispose).
+ * `Subagent` then only coordinates (turn loop, steer, dispose).
  *
  * The factory takes a resolved `cwd` value, never the WorkspaceProvider: `cwd`
  * is a value the factory consumes directly (detectEnv, assembleSessionConfig,

package/src/lifecycle/{agent-manager.ts → subagent-manager.ts}

@@ -1,5 +1,5 @@
 /**
- * agent-manager.ts - Tracks agents, background execution, resume support.
+ * subagent-manager.ts - Tracks subagents, background execution, resume support.
  *
  * Background agents are subject to a configurable concurrency limit (default: 4).
  * Excess agents are queued and auto-started as running agents complete.
@@ -9,10 +9,10 @@
 import { randomUUID } from "node:crypto";
 import type { Model } from "@earendil-works/pi-ai";
 import { debugLog } from "#src/debug";
-import { Agent, type AgentLifecycleObserver } from "#src/lifecycle/agent";
 import type { ConcurrencyQueue } from "#src/lifecycle/concurrency-queue";
 import type { CreateSubagentSessionParams } from "#src/lifecycle/create-subagent-session";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import { Subagent, type SubagentLifecycleObserver } from "#src/lifecycle/subagent";
 import type { SubagentSession } from "#src/lifecycle/subagent-session";
 import type { WorkspaceProvider } from "#src/lifecycle/workspace";
 
@@ -20,15 +20,15 @@ import type { RunConfig } from "#src/runtime";
 import type { AgentInvocation, CompactionInfo, ParentSessionInfo, SubagentType, ThinkingLevel } from "#src/types";
 
 /** Observer interface for agent lifecycle notifications. */
-export interface AgentManagerObserver {
-  onAgentStarted(record: Agent): void;
-  onAgentCompleted(record: Agent): void;
-  onAgentCompacted(record: Agent, info: CompactionInfo): void;
+export interface SubagentManagerObserver {
+  onSubagentStarted(record: Subagent): void;
+  onSubagentCompleted(record: Subagent): void;
+  onSubagentCompacted(record: Subagent, info: CompactionInfo): void;
   /** Fires synchronously after a background agent record is created (before run). */
-  onAgentCreated(record: Agent): void;
+  onSubagentCreated(record: Subagent): void;
 }
 
-export interface AgentManagerOptions {
+export interface SubagentManagerOptions {
   /** Assembly factory that produces a born-complete SubagentSession per spawn. */
   createSubagentSession: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
   /** Concurrency queue — owns scheduling, limit checks, and drain logic. */
@@ -36,7 +36,7 @@ export interface AgentManagerOptions {
   /** Base working directory handed to a workspace provider (the parent cwd). */
   baseCwd: string;
   getRunConfig?: () => RunConfig;
-  observer?: AgentManagerObserver;
+  observer?: SubagentManagerObserver;
 }
 
 export interface AgentSpawnConfig {
@@ -56,16 +56,16 @@ export interface AgentSpawnConfig {
   invocation?: AgentInvocation;
   /** Parent abort signal - when aborted, the subagent is also stopped. */
   signal?: AbortSignal;
-  /** Per-agent lifecycle observer — replaces onSessionCreated callback. */
-  observer?: AgentLifecycleObserver;
+  /** Per-subagent lifecycle observer — replaces onSessionCreated callback. */
+  observer?: SubagentLifecycleObserver;
   /** Parent session identity - grouped fields that travel together from the tool boundary. */
   parentSession?: ParentSessionInfo;
 }
 
-export class AgentManager {
-  private agents = new Map<string, Agent>();
+export class SubagentManager {
+  private agents = new Map<string, Subagent>();
   private cleanupInterval: ReturnType<typeof setInterval>;
-  private readonly observer?: AgentManagerObserver;
+  private readonly observer?: SubagentManagerObserver;
   private readonly createSubagentSession: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
   private readonly queue: ConcurrencyQueue;
   private readonly baseCwd: string;
@@ -77,7 +77,7 @@ export class AgentManager {
     return this._workspaceProvider;
   }
 
-  constructor(options: AgentManagerOptions) {
+  constructor(options: SubagentManagerOptions) {
     this.createSubagentSession = options.createSubagentSession;
     this.queue = options.queue;
     this.baseCwd = options.baseCwd;
@@ -106,11 +106,11 @@ export class AgentManager {
   }
 
   /** Compose a per-agent lifecycle observer from manager and spawn-config concerns. */
-  private buildObserver(options: AgentSpawnConfig): AgentLifecycleObserver {
+  private buildObserver(options: AgentSpawnConfig): SubagentLifecycleObserver {
     return {
       onStarted: (agent) => {
         if (options.isBackground) this.queue.markStarted();
-        this.observer?.onAgentStarted(agent);
+        this.observer?.onSubagentStarted(agent);
       },
       onSessionCreated: options.observer?.onSessionCreated
         ? (agent) => options.observer!.onSessionCreated!(agent)
@@ -118,11 +118,11 @@ export class AgentManager {
       onRunFinished: (agent) => {
         if (options.isBackground) {
           this.queue.markFinished();
-          try { this.observer?.onAgentCompleted(agent); } catch (err) { debugLog("onAgentCompleted observer", err); }
+          try { this.observer?.onSubagentCompleted(agent); } catch (err) { debugLog("onSubagentCompleted observer", err); }
         }
       },
       onCompacted: (agent, info) => {
-        this.observer?.onAgentCompacted(agent, info);
+        this.observer?.onSubagentCompacted(agent, info);
       },
     };
   }
@@ -138,7 +138,7 @@ export class AgentManager {
     options: AgentSpawnConfig,
   ): string {
     const id = randomUUID().slice(0, 17);
-    const record = new Agent({
+    const record = new Subagent({
       id,
       type,
       description: options.description,
@@ -163,7 +163,7 @@ export class AgentManager {
     this.agents.set(id, record);
 
     if (options.isBackground) {
-      this.observer?.onAgentCreated(record);
+      this.observer?.onSubagentCreated(record);
     }
 
     if (options.isBackground && !options.bypassQueue && this.queue.isFull()) {
@@ -185,7 +185,7 @@ export class AgentManager {
     type: SubagentType,
     prompt: string,
     options: Omit<AgentSpawnConfig, "isBackground">,
-  ): Promise<Agent> {
+  ): Promise<Subagent> {
     const id = this.spawn(snapshot, type, prompt, { ...options, isBackground: false });
     const record = this.agents.get(id)!;
     await record.promise;
@@ -194,24 +194,24 @@ export class AgentManager {
 
   /**
    * Resume an existing agent session with a new prompt.
-   * Delegates to Agent.resume(), which owns the observer subscription lifecycle.
+   * Delegates to Subagent.resume(), which owns the observer subscription lifecycle.
    */
   async resume(
     id: string,
     prompt: string,
     signal?: AbortSignal,
-  ): Promise<Agent | undefined> {
+  ): Promise<Subagent | undefined> {
     const agent = this.agents.get(id);
     if (!agent?.isSessionReady()) return undefined;
     await agent.resume(prompt, signal);
     return agent;
   }
 
-  getRecord(id: string): Agent | undefined {
+  getRecord(id: string): Subagent | undefined {
     return this.agents.get(id);
   }
 
-  listAgents(): Agent[] {
+  listAgents(): Subagent[] {
     return [...this.agents.values()].sort(
       (a, b) => b.startedAt - a.startedAt,
     );
@@ -232,7 +232,7 @@ export class AgentManager {
   }
 
   /** Dispose a record's session and remove it from the map. */
-  private removeRecord(id: string, record: Agent): void {
+  private removeRecord(id: string, record: Subagent): void {
     record.disposeSession();
     this.agents.delete(id);
   }

package/src/lifecycle/subagent-session.ts

@@ -4,10 +4,10 @@
  * A SubagentSession wraps one SDK AgentSession plus its turn-driving and teardown.
  * It is born complete: `createSubagentSession()` returns a fully usable instance
  * (session created, extensions bound, recursion guard applied), so the only thing
- * left for `Agent` to do is coordinate — drive the turn loop, steer, dispose.
+ * left for `Subagent` to do is coordinate — drive the turn loop, steer, dispose.
  *
  * Turn driving lives here, on the object that owns the AgentSession, rather than
- * reaching through `subagentSession.session` from `Agent` (Law of Demeter).
+ * reaching through `subagentSession.session` from `Subagent` (Law of Demeter).
  */
 
 import {

package/src/lifecycle/{agent.ts → subagent.ts}

@@ -1,5 +1,5 @@
 /**
- * agent.ts — Agent class with encapsulated status-transition logic and per-agent behavior.
+ * 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
@@ -8,8 +8,8 @@
  * 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.
+ * 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.
@@ -28,23 +28,23 @@ import type { LifetimeUsage } from "#src/lifecycle/usage";
 import { addUsage } from "#src/lifecycle/usage";
 import type { Workspace, WorkspaceProvider } from "#src/lifecycle/workspace";
 import { NotificationState } from "#src/observation/notification-state";
-import { subscribeAgentObserver } from "#src/observation/record-observer";
+import { subscribeSubagentObserver } from "#src/observation/record-observer";
 import type { RunConfig } from "#src/runtime";
 import type { AgentInvocation, CompactionInfo, ParentSessionInfo, SubagentType, ThinkingLevel } from "#src/types";
 
-/** Per-agent lifecycle observer — created by AgentManager for each spawn. */
-export interface AgentLifecycleObserver {
-	/** Fires when the agent transitions to running (inside run(), after markRunning). */
-	onStarted?(agent: Agent): void;
-	/** Fires once the session is created — the agent's subagentSession is now available. */
-	onSessionCreated?(agent: Agent): void;
+/** Per-subagent lifecycle observer — created by SubagentManager for each spawn. */
+export interface SubagentLifecycleObserver {
+	/** Fires when the subagent transitions to running (inside run(), after markRunning). */
+	onStarted?(agent: Subagent): void;
+	/** Fires once the session is created — the subagent's subagentSession is now available. */
+	onSessionCreated?(agent: Subagent): void;
 	/** Fires once when the run completes or fails (for concurrency drain). */
-	onRunFinished?(agent: Agent): void;
+	onRunFinished?(agent: Subagent): void;
 	/** Fires on compaction events during the run. */
-	onCompacted?(agent: Agent, info: CompactionInfo): void;
+	onCompacted?(agent: Subagent, info: CompactionInfo): void;
 }
 
-export type AgentStatus =
+export type SubagentStatus =
 	| "queued"
 	| "running"
 	| "completed"
@@ -53,7 +53,7 @@ export type AgentStatus =
 	| "stopped"
 	| "error";
 
-export interface AgentInit {
+export interface SubagentInit {
 	// Identity
 	id: string;
 	type: SubagentType;
@@ -61,7 +61,7 @@ export interface AgentInit {
 	invocation?: AgentInvocation;
 
 	// Status (for tests and restore scenarios)
-	status?: AgentStatus;
+	status?: SubagentStatus;
 	startedAt?: number;
 	completedAt?: number;
 	result?: string;
@@ -70,7 +70,7 @@ export interface AgentInit {
 	// Shared deps (required for run(), optional for tests)
 	/** Assembly factory that produces a born-complete SubagentSession. */
 	createSubagentSession?: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
-	observer?: AgentLifecycleObserver;
+	observer?: SubagentLifecycleObserver;
 	getRunConfig?: () => RunConfig;
 	/** Resolves the registered workspace provider (if any) at run-start. */
 	getWorkspaceProvider?: () => WorkspaceProvider | undefined;
@@ -88,7 +88,7 @@ export interface AgentInit {
 	signal?: AbortSignal;
 }
 
-export class Agent {
+export class Subagent {
 	// Identity — set once at construction
 	readonly id: string;
 	readonly type: SubagentType;
@@ -96,8 +96,8 @@ export class Agent {
 	readonly invocation?: AgentInvocation;
 
 	// Transition state — encapsulated behind getters, mutated only via transition methods
-	private _status: AgentStatus;
-	get status(): AgentStatus { return this._status; }
+	private _status: SubagentStatus;
+	get status(): SubagentStatus { return this._status; }
 
 	private _result?: string;
 	get result(): string | undefined { return this._result; }
@@ -128,7 +128,7 @@ export class Agent {
 
 	// Shared deps — optional (required for run())
 	private readonly _createSubagentSession?: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
-	readonly observer?: AgentLifecycleObserver;
+	readonly observer?: SubagentLifecycleObserver;
 	private readonly _getRunConfig?: () => RunConfig;
 	private readonly _getWorkspaceProvider?: () => WorkspaceProvider | undefined;
 	private readonly _baseCwd: string;
@@ -200,7 +200,7 @@ export class Agent {
 		return this.subagentSession?.messages ?? [];
 	}
 
-	constructor(init: AgentInit) {
+	constructor(init: SubagentInit) {
 		// Identity
 		this.id = init.id;
 		this.type = init.type;
@@ -254,10 +254,10 @@ export class Agent {
 	 */
 	async run(): Promise<void> {
 		if (!this._createSubagentSession) {
-			throw new Error("Agent not configured for execution — missing session factory");
+			throw new Error("Subagent not configured for execution — missing session factory");
 		}
 		if (!this._snapshot || !this._prompt) {
-			throw new Error("Agent not configured for execution — missing snapshot or prompt");
+			throw new Error("Subagent not configured for execution — missing snapshot or prompt");
 		}
 
 		this.markRunning(Date.now());
@@ -301,7 +301,7 @@ export class Agent {
 		}
 
 		this.flushPendingSteers();
-		this.attachObserver(subscribeAgentObserver(this.subagentSession, this, {
+		this.attachObserver(subscribeSubagentObserver(this.subagentSession, this, {
 			onCompact: (r, info) => this.observer?.onCompacted?.(r, info),
 		}));
 		this.observer?.onSessionCreated?.(this);
@@ -332,11 +332,11 @@ export class Agent {
 	async resume(prompt: string, signal?: AbortSignal): Promise<void> {
 		const subagentSession = this.subagentSession;
 		if (!subagentSession) {
-			throw new Error("Agent not configured for resume — missing session");
+			throw new Error("Subagent not configured for resume — missing session");
 		}
 
 		this.resetForResume(Date.now());
-		this.attachObserver(subscribeAgentObserver(subagentSession, this, {
+		this.attachObserver(subscribeSubagentObserver(subagentSession, this, {
 			onCompact: (r, info) => this.observer?.onCompacted?.(r, info),
 		}));
 
@@ -428,7 +428,7 @@ export class Agent {
 	/**
 	 * Abort a running agent: fire AbortController and transition to stopped.
 	 * Returns false if the agent is not running.
-	 * Queue removal is handled by AgentManager via ConcurrencyQueue.dequeue().
+	 * Queue removal is handled by SubagentManager via ConcurrencyQueue.dequeue().
 	 */
 	abort(): boolean {
 		if (this._status !== "running") return false;
@@ -497,7 +497,7 @@ export class Agent {
 
 		let finalResult = result.responseText;
 		if (this._workspace) {
-			const finalStatus: AgentStatus = result.aborted
+			const finalStatus: SubagentStatus = result.aborted
 				? "aborted"
 				: result.steered
 					? "steered"

package/src/lifecycle/turn-limits.ts

@@ -2,7 +2,7 @@
  * turn-limits.ts — Pure turn-limit normalization for subagent execution.
  *
  * Extracted from agent-runner.ts (issue #265) so the turn-counting policy has a
- * focused home independent of session assembly. Consumed by the Agent tool's
+ * focused home independent of session assembly. Consumed by the subagent tool's
  * spawn-config resolution and by the turn loop in SubagentSession.
  */