@gotgenes/pi-subagents 13.2.1 → 13.2.2

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.
  */
 

package/src/lifecycle/workspace.ts

@@ -11,7 +11,7 @@
  * synchronously at run-start. The core has no knowledge of git or worktrees.
  */
 
-import type { AgentStatus } from "#src/lifecycle/agent";
+import type { SubagentStatus } from "#src/lifecycle/subagent";
 import type { AgentInvocation, SubagentType } from "#src/types";
 
 /** Context the core hands a provider when a child run starts. */
@@ -24,7 +24,7 @@ export interface WorkspacePrepareContext {
 
 /** Outcome the core reports to a workspace when the run ends. */
 export interface WorkspaceDisposeOutcome {
-  status: AgentStatus;
+  status: SubagentStatus;
   description: string;
 }
 

package/src/observation/notification.ts

@@ -1,6 +1,6 @@
 import { debugLog } from "#src/debug";
 import { getLifetimeTotal } from "#src/lifecycle/usage";
-import type { Agent } from "#src/types";
+import type { Subagent } from "#src/types";
 import type { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 
 /** Details attached to custom notification messages for visual rendering. */
@@ -42,7 +42,7 @@ export function getStatusLabel(status: string, error?: string): string {
 }
 
 /** Format a structured task notification matching Claude Code's <task-notification> XML. */
-export function formatTaskNotification(record: Agent, resultMaxLen: number): string {
+export function formatTaskNotification(record: Subagent, resultMaxLen: number): string {
   const status = getStatusLabel(record.status, record.error);
   const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
   const totalTokens = getLifetimeTotal(record.lifetimeUsage);
@@ -64,7 +64,7 @@ export function formatTaskNotification(record: Agent, resultMaxLen: number): str
     toolCallId ? `<tool-use-id>${escapeXml(toolCallId)}</tool-use-id>` : null,
     outputFile ? `<output-file>${escapeXml(outputFile)}</output-file>` : null,
     `<status>${escapeXml(status)}</status>`,
-    `<summary>Agent "${escapeXml(record.description)}" ${record.status}</summary>`,
+    `<summary>Subagent "${escapeXml(record.description)}" ${record.status}</summary>`,
     `<result>${escapeXml(resultPreview)}</result>`,
     `<usage><total_tokens>${totalTokens}</total_tokens><tool_uses>${record.toolUses}</tool_uses>${ctxXml}${compactXml}<duration_ms>${durationMs}</duration_ms></usage>`,
     "</task-notification>",
@@ -75,7 +75,7 @@ export function formatTaskNotification(record: Agent, resultMaxLen: number): str
 
 /** Build notification details for the custom message renderer. */
 export function buildNotificationDetails(
-  record: Agent,
+  record: Subagent,
   resultMaxLen: number,
   activity?: AgentActivityTracker,
 ): NotificationDetails {
@@ -100,8 +100,8 @@ export function buildNotificationDetails(
   };
 }
 
-/** Build event data for lifecycle events from an Agent. */
-export function buildEventData(record: Agent) {
+/** Build event data for lifecycle events from a Subagent. */
+export function buildEventData(record: Subagent) {
   const durationMs = record.completedAt ? record.completedAt - record.startedAt : Date.now() - record.startedAt;
   const u = record.lifetimeUsage;
   const total = getLifetimeTotal(u);
@@ -126,7 +126,7 @@ export function buildEventData(record: Agent) {
 
 export interface NotificationSystem {
   cancelNudge: (key: string) => void;
-  sendCompletion: (record: Agent) => void;
+  sendCompletion: (record: Subagent) => void;
   cleanupCompleted: (id: string) => void;
   dispose: () => void;
 }
@@ -154,7 +154,7 @@ export class NotificationManager implements NotificationSystem {
     }
   }
 
-  sendCompletion(record: Agent): void {
+  sendCompletion(record: Subagent): void {
     this.agentActivity.delete(record.id);
     this.markFinished(record.id);
     this.scheduleNudge(record.id, () => this.emitIndividualNudge(record));
@@ -187,7 +187,7 @@ export class NotificationManager implements NotificationSystem {
     );
   }
 
-  private emitIndividualNudge(record: Agent): void {
+  private emitIndividualNudge(record: Subagent): void {
     if (record.notification?.resultConsumed) return;
 
     const notification = formatTaskNotification(record, 500);

package/src/observation/record-observer.ts

@@ -1,19 +1,19 @@
 /**
- * record-observer.ts — Subscribes to session events and updates Agent stats.
+ * record-observer.ts — Subscribes to session events and updates Subagent stats.
  *
- * Replaces the scattered callback-wrapping logic in AgentManager's startAgent()
+ * Replaces the scattered callback-wrapping logic in SubagentManager's startAgent()
  * and resume() with a single direct subscription.
  */
 
-import type { Agent } from "#src/lifecycle/agent";
+import type { Subagent } from "#src/lifecycle/subagent";
 import type { CompactionInfo, SubscribableSession } from "#src/types";
 
-export interface AgentObserverOptions {
-  onCompact?: (record: Agent, info: CompactionInfo) => void;
+export interface SubagentObserverOptions {
+  onCompact?: (record: Subagent, info: CompactionInfo) => void;
 }
 
 /**
- * Subscribe to session events and accumulate stats on the agent record.
+ * Subscribe to session events and accumulate stats on the subagent record.
  *
  * Handles:
  * - `tool_execution_end` → `record.incrementToolUses()`
@@ -22,10 +22,10 @@ export interface AgentObserverOptions {
  *
  * @returns An unsubscribe function.
  */
-export function subscribeAgentObserver(
+export function subscribeSubagentObserver(
   session: SubscribableSession,
-  record: Agent,
-  options?: AgentObserverOptions,
+  record: Subagent,
+  options?: SubagentObserverOptions,
 ): () => void {
   return session.subscribe((event) => {
     if (event.type === "tool_execution_end") {

package/src/runtime.ts

@@ -49,7 +49,7 @@ export class SubagentRuntime {
    */
   readonly agentActivity: Map<string, AgentActivityTracker> = new Map();
   /**
-   * Persistent widget reference. Null until constructed after AgentManager.
+   * Persistent widget reference. Null until constructed after SubagentManager.
    * Delegation methods use optional chaining so callers never need `widget!`.
    */
   widget: WidgetLike | null = null;

package/src/service/service-adapter.ts

@@ -1,5 +1,5 @@
 /**
- * service-adapter.ts — Adapter that wraps AgentManager to satisfy SubagentsService.
+ * service-adapter.ts — Adapter that wraps SubagentManager to satisfy SubagentsService.
  *
  * Handles model resolution at the API boundary, record serialization
  * (stripping non-serializable fields), and session gating.
@@ -9,13 +9,13 @@ import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { WorkspaceProvider } from "#src/lifecycle/workspace";
 import type { SpawnOptions, SubagentRecord, SubagentsService } from "#src/service/service";
 import type { ModelRegistry } from "#src/session/model-resolver";
-import type { Agent, SessionContext } from "#src/types";
+import type { SessionContext, Subagent } from "#src/types";
 
-/** Narrow interface for the AgentManager — avoids coupling to the concrete class. */
-export interface AgentManagerLike {
+/** Narrow interface for the SubagentManager — avoids coupling to the concrete class. */
+export interface SubagentManagerLike {
   spawn(snapshot: ParentSnapshot, type: string, prompt: string, options: unknown): string;
-  getRecord(id: string): Agent | undefined;
-  listAgents(): Agent[];
+  getRecord(id: string): Subagent | undefined;
+  listAgents(): Subagent[];
   abort(id: string): boolean;
   waitForAll(): Promise<void>;
   hasRunning(): boolean;
@@ -31,10 +31,10 @@ export interface ServiceRuntimeLike {
   buildSnapshot(inheritContext: boolean): ParentSnapshot;
 }
 
-/** Adapter that wraps AgentManager to satisfy SubagentsService. */
+/** Adapter that wraps SubagentManager to satisfy SubagentsService. */
 export class SubagentsServiceAdapter implements SubagentsService {
   constructor(
-    private readonly manager: AgentManagerLike,
+    private readonly manager: SubagentManagerLike,
     private readonly resolveModel: (input: string, registry: ModelRegistry) => unknown,
     private readonly runtime: ServiceRuntimeLike,
   ) {}
@@ -108,10 +108,10 @@ export class SubagentsServiceAdapter implements SubagentsService {
 }
 
 /**
- * Convert an internal Agent to a serializable SubagentRecord.
+ * Convert an internal Subagent to a serializable SubagentRecord.
  * Uses an explicit allowlist — new fields must be opted in.
  */
-export function toSubagentRecord(record: Agent): SubagentRecord {
+export function toSubagentRecord(record: Subagent): SubagentRecord {
   const out: SubagentRecord = {
     id: record.id,
     type: record.type,

package/src/service/service.ts

@@ -9,6 +9,7 @@
  *   svc?.spawn("Explore", "Check for stale TODOs");
  */
 
+import type { SubagentStatus } from "#src/lifecycle/subagent";
 import type { LifetimeUsage } from "#src/lifecycle/usage";
 import type {
   Workspace,
@@ -18,6 +19,10 @@ import type {
   WorkspaceProvider,
 } from "#src/lifecycle/workspace";
 
+
+// SubagentStatus is defined in the lifecycle layer (single home) and re-exported
+// here for the public API surface — mirrors the LifetimeUsage / workspace pattern.
+export type { SubagentStatus } from "#src/lifecycle/subagent";
 // Generative extension seam (ADR 0002, Phase 16 Step 2). The provider type
 // and all four collaborator types it references are re-exported by name so
 // consumers can import them directly rather than recovering them via
@@ -31,15 +36,6 @@ export type {
   WorkspaceProvider,
 };
 
-export type SubagentStatus =
-  | "queued"
-  | "running"
-  | "completed"
-  | "steered"
-  | "aborted"
-  | "stopped"
-  | "error";
-
 /** Serializable snapshot of an agent's state — no live session objects. */
 export interface SubagentRecord {
   id: string;

package/src/tools/agent-tool.ts

@@ -4,14 +4,14 @@ import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { AgentTypeRegistry } from "#src/config/agent-types";
-import type { AgentSpawnConfig } from "#src/lifecycle/agent-manager";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import type { AgentSpawnConfig } from "#src/lifecycle/subagent-manager";
 import { spawnBackground } from "#src/tools/background-spawner";
 import { runForeground } from "#src/tools/foreground-runner";
 import { buildDetails, buildTypeListText, textResult } from "#src/tools/helpers";
 import { renderAgentResult } from "#src/tools/result-renderer";
 import { type ModelInfo, resolveSpawnConfig } from "#src/tools/spawn-config";
-import type { Agent, ParentSessionInfo } from "#src/types";
+import type { ParentSessionInfo, Subagent } from "#src/types";
 import { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 import { type UICtx } from "#src/ui/agent-widget";
 import { type AgentDetails, getDisplayName } from "#src/ui/display";
@@ -33,9 +33,9 @@ export interface AgentActivityAccess {
 /** Narrow manager interface — only the methods the Agent tool calls. */
 export interface AgentToolManager {
 	spawn: (snapshot: ParentSnapshot, type: string, prompt: string, opts: AgentSpawnConfig) => string;
-	spawnAndWait: (snapshot: ParentSnapshot, type: string, prompt: string, opts: Omit<AgentSpawnConfig, "isBackground">) => Promise<Agent>;
-	resume: (id: string, prompt: string, signal: AbortSignal) => Promise<Agent | undefined>;
-	getRecord: (id: string) => Agent | undefined;
+	spawnAndWait: (snapshot: ParentSnapshot, type: string, prompt: string, opts: Omit<AgentSpawnConfig, "isBackground">) => Promise<Subagent>;
+	resume: (id: string, prompt: string, signal: AbortSignal) => Promise<Subagent | undefined>;
+	getRecord: (id: string) => Subagent | undefined;
 }
 
 /** Narrow runtime interface — the Agent tool's slice of SubagentRuntime. */

package/src/tools/background-spawner.ts

@@ -1,16 +1,16 @@
-import type { AgentSpawnConfig } from "#src/lifecycle/agent-manager";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import type { AgentSpawnConfig } from "#src/lifecycle/subagent-manager";
 import type { AgentActivityAccess } from "#src/tools/agent-tool";
 import { textResult } from "#src/tools/helpers";
 import type { ResolvedSpawnConfig } from "#src/tools/spawn-config";
-import type { Agent, ParentSessionInfo } from "#src/types";
+import type { ParentSessionInfo, Subagent } from "#src/types";
 import { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 import { subscribeUIObserver } from "#src/ui/ui-observer";
 
 /** Narrow manager interface for the background spawner. */
 export interface BackgroundManagerDeps {
   spawn(snapshot: ParentSnapshot, type: string, prompt: string, opts: AgentSpawnConfig): string;
-  getRecord(id: string): Agent | undefined;
+  getRecord(id: string): Subagent | undefined;
 }
 
 /** Narrow widget interface for the background spawner. */