@gotgenes/pi-subagents 10.0.1 → 10.1.0

package/src/lifecycle/agent-manager.ts

@@ -1,5 +1,5 @@
 /**
- * agent-manager.ts — Tracks agents, background execution, resume support.
+ * agent-manager.ts - Tracks agents, 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.
@@ -11,23 +11,23 @@ import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import { AgentTypeRegistry } from "#src/config/agent-types";
 import { debugLog } from "#src/debug";
-import { AgentRecord } from "#src/lifecycle/agent-record";
+import { Agent } from "#src/lifecycle/agent";
 import type { AgentRunner, RunResult } from "#src/lifecycle/agent-runner";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { WorktreeManager } from "#src/lifecycle/worktree";
-import { WorktreeState } from "#src/lifecycle/worktree-state";
+
 import { NotificationState } from "#src/observation/notification-state";
-import { subscribeRecordObserver } from "#src/observation/record-observer";
+import { subscribeAgentObserver } from "#src/observation/record-observer";
 import type { RunConfig } from "#src/runtime";
 import type { AgentInvocation, IsolationMode, ShellExec, SubagentType, ThinkingLevel } from "#src/types";
 
 /**
- * RunHandle — per-run lifecycle object that owns cleanup state.
+ * RunHandle - per-run lifecycle object that owns cleanup state.
  *
  * Owns the observer unsubscribe and parent-signal detach handles acquired during
  * a run. Exposes `complete()` and `fail()` as the only way to finish a run,
  * eliminating mutable closure variables from `startAgent`.
- * `fireOnFinished` is idempotent — safe to call from both success and error paths.
+ * `fireOnFinished` is idempotent - safe to call from both success and error paths.
  */
 class RunHandle {
   private unsub?: () => void;
@@ -35,7 +35,7 @@ class RunHandle {
   private onFinished?: () => void;
 
   constructor(
-    private readonly record: AgentRecord,
+    private readonly record: Agent,
     private readonly worktrees: WorktreeManager,
     onFinished?: () => void,
   ) {
@@ -55,7 +55,7 @@ class RunHandle {
     this.unsub = unsub;
   }
 
-  /** Complete a run successfully — clean up, transition record, fire onFinished. */
+  /** Complete a run successfully - clean up, transition record, fire onFinished. */
   complete(result: RunResult): string {
     this.releaseListeners();
 
@@ -81,7 +81,7 @@ class RunHandle {
     return result.responseText;
   }
 
-  /** Fail a run — mark error, best-effort worktree cleanup, fire onFinished. */
+  /** Fail a run - mark error, best-effort worktree cleanup, fire onFinished. */
   fail(err: unknown): void {
     this.record.markError(err);
     this.releaseListeners();
@@ -114,11 +114,11 @@ export type CompactionInfo = { reason: "manual" | "threshold" | "overflow"; toke
 
 /** Observer interface for agent lifecycle notifications. */
 export interface AgentManagerObserver {
-  onAgentStarted(record: AgentRecord): void;
-  onAgentCompleted(record: AgentRecord): void;
-  onAgentCompacted(record: AgentRecord, info: CompactionInfo): void;
+  onAgentStarted(record: Agent): void;
+  onAgentCompleted(record: Agent): void;
+  onAgentCompacted(record: Agent, info: CompactionInfo): void;
   /** Fires synchronously after a background agent record is created (before startAgent). */
-  onAgentCreated(record: AgentRecord): void;
+  onAgentCreated(record: Agent): void;
 }
 
 /** Default max concurrent background agents. */
@@ -129,7 +129,7 @@ export interface AgentManagerOptions {
   worktrees: WorktreeManager;
   exec: ShellExec;
   registry: AgentTypeRegistry;
-  /** Injected getter for the concurrency limit — owned by SettingsManager. */
+  /** Injected getter for the concurrency limit - owned by SettingsManager. */
   getMaxConcurrent?: () => number;
   getRunConfig?: () => RunConfig;
   observer?: AgentManagerObserver;
@@ -160,25 +160,25 @@ export interface AgentSpawnConfig {
   thinkingLevel?: ThinkingLevel;
   isBackground?: boolean;
   /**
-   * Skip the maxConcurrent queue check for this spawn — start immediately even
+   * Skip the maxConcurrent queue check for this spawn - start immediately even
    * if the configured concurrency limit would otherwise queue it. Useful for
    * callers (e.g. cross-extension RPC) that must not be deferred by the queue.
    */
   bypassQueue?: boolean;
-  /** Isolation mode — "worktree" creates a temp git worktree for the agent. */
+  /** Isolation mode - "worktree" creates a temp git worktree for the agent. */
   isolation?: IsolationMode;
   /** Resolved invocation snapshot captured for UI display. */
   invocation?: AgentInvocation;
-  /** Parent abort signal — when aborted, the subagent is also stopped. */
+  /** Parent abort signal - when aborted, the subagent is also stopped. */
   signal?: AbortSignal;
-  /** Called when the agent session is created — receives the session and the agent's record. */
-  onSessionCreated?: (session: AgentSession, record: AgentRecord) => void;
-  /** Parent session identity — grouped fields that travel together from the tool boundary. */
+  /** Called when the agent session is created - receives the session and the agent's record. */
+  onSessionCreated?: (session: AgentSession, record: Agent) => void;
+  /** Parent session identity - grouped fields that travel together from the tool boundary. */
   parentSession?: ParentSessionInfo;
 }
 
 export class AgentManager {
-  private agents = new Map<string, AgentRecord>();
+  private agents = new Map<string, Agent>();
   private cleanupInterval: ReturnType<typeof setInterval>;
   private readonly observer?: AgentManagerObserver;
   private readonly runner: AgentRunner;
@@ -192,9 +192,6 @@ export class AgentManager {
   private queue: { id: string; args: SpawnArgs }[] = [];
   /** Number of currently running background agents. */
   private runningBackground = 0;
-  /** Steers buffered for agents whose session hasn’t been created yet. */
-  private pendingSteers = new Map<string, string[]>();
-
   constructor(options: AgentManagerOptions) {
     this.runner = options.runner;
     this.worktrees = options.worktrees;
@@ -216,19 +213,6 @@ export class AgentManager {
     this.drainQueue();
   }
 
-  /**
-   * Buffer a steer message for an agent whose session isn’t ready yet.
-   * Returns false if the agent id is not tracked (already cleaned up or unknown).
-   * Called by steer-tool and service-adapter when record.execution is undefined.
-   */
-  queueSteer(id: string, message: string): boolean {
-    if (!this.agents.has(id)) return false;
-    const steers = this.pendingSteers.get(id) ?? [];
-    steers.push(message);
-    this.pendingSteers.set(id, steers);
-    return true;
-  }
-
   /**
    * Spawn an agent and return its ID immediately (for background use).
    * If the concurrency limit is reached, the agent is queued.
@@ -241,7 +225,7 @@ export class AgentManager {
   ): string {
     const id = randomUUID().slice(0, 17);
     const abortController = new AbortController();
-    const record = new AgentRecord({
+    const record = new Agent({
       id,
       type,
       description: options.description,
@@ -263,12 +247,12 @@ export class AgentManager {
     const args: SpawnArgs = { snapshot, type, prompt, options };
 
     if (options.isBackground && !options.bypassQueue && this.runningBackground >= this._getMaxConcurrent()) {
-      // Queue it — will be started when a running agent completes
+      // Queue it - will be started when a running agent completes
       this.queue.push({ id, args });
       return id;
     }
 
-    // startAgent can throw (e.g. strict worktree-isolation failure) — clean
+    // startAgent can throw (e.g. strict worktree-isolation failure) - clean
     // up the record so callers don't see an orphan in `listAgents()`.
     try {
       this.startAgent(id, record, args);
@@ -280,8 +264,8 @@ export class AgentManager {
   }
 
   /** Actually start an agent (called immediately or from queue drain). */
-  private startAgent(id: string, record: AgentRecord, { snapshot, type, prompt, options }: SpawnArgs) {
-    const worktreeCwd = this.setupWorktree(id, record, options.isolation);
+  private startAgent(id: string, record: Agent, { snapshot, type, prompt, options }: SpawnArgs) {
+    const worktreeCwd = record.setupWorktree(this.worktrees, options.isolation);
 
     record.markRunning(Date.now());
     if (options.isBackground) this.runningBackground++;
@@ -314,8 +298,8 @@ export class AgentManager {
         // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- sessionManager is typed as always present but Pi SDK may not provide it
         const outputFile = session.sessionManager?.getSessionFile?.() ?? undefined;
         record.execution = { session, outputFile };
-        this.flushPendingSteers(id, session);
-        handle.attachObserver(subscribeRecordObserver(session, record, {
+        record.flushPendingSteers(session);
+        handle.attachObserver(subscribeAgentObserver(session, record, {
           onCompact: (r, info) => this.observer?.onAgentCompacted(r, info),
         }));
         options.onSessionCreated?.(session, record);
@@ -325,34 +309,8 @@ export class AgentManager {
       .catch((err: unknown) => { handle.fail(err); return ""; });
   }
 
-  /** Create a worktree for isolated agents. Throws (strict) if isolation is requested but impossible. */
-  private setupWorktree(
-    id: string, record: AgentRecord, isolation: IsolationMode | undefined,
-  ): string | undefined {
-    if (isolation !== "worktree") return undefined;
-    const wt = this.worktrees.create(id);
-    if (!wt) {
-      throw new Error(
-        'Cannot run with isolation: "worktree" — not a git repo, no commits yet, or `git worktree add` failed. ' +
-        'Initialize git and commit at least once, or omit `isolation`.',
-      );
-    }
-    record.worktreeState = new WorktreeState(wt);
-    return wt.path;
-  }
-
-  /** Flush any steers buffered before the session was ready. */
-  private flushPendingSteers(id: string, session: AgentSession): void {
-    const buffered = this.pendingSteers.get(id);
-    if (!buffered?.length) return;
-    for (const msg of buffered) {
-      session.steer(msg).catch(() => {});
-    }
-    this.pendingSteers.delete(id);
-  }
-
   /** Decrement background counter, notify observer (crash-safe), and drain the queue. */
-  private finalizeBackgroundRun(record: AgentRecord): void {
+  private finalizeBackgroundRun(record: Agent): void {
     this.runningBackground--;
     try { this.observer?.onAgentCompleted(record); } catch (err) { debugLog("onAgentCompleted observer", err); }
     this.drainQueue();
@@ -367,7 +325,7 @@ export class AgentManager {
       try {
         this.startAgent(next.id, record, next.args);
       } catch (err) {
-        // Late failure (e.g. strict worktree-isolation) — surface on the record
+        // Late failure (e.g. strict worktree-isolation) - surface on the record
         // so the user/agent can see it via /agents, then keep draining.
         record.markError(err);
         this.observer?.onAgentCompleted(record);
@@ -384,7 +342,7 @@ export class AgentManager {
     type: SubagentType,
     prompt: string,
     options: Omit<AgentSpawnConfig, "isBackground">,
-  ): Promise<AgentRecord> {
+  ): Promise<Agent> {
     const id = this.spawn(snapshot, type, prompt, { ...options, isBackground: false });
     const record = this.agents.get(id)!;
     await record.promise;
@@ -398,14 +356,14 @@ export class AgentManager {
     id: string,
     prompt: string,
     signal?: AbortSignal,
-  ): Promise<AgentRecord | undefined> {
+  ): Promise<Agent | undefined> {
     const record = this.agents.get(id);
     const session = record?.session;
     if (!session) return undefined;
 
     record.resetForResume(Date.now());
 
-    const unsubResume = subscribeRecordObserver(session, record, {
+    const unsubResume = subscribeAgentObserver(session, record, {
       onCompact: (r, info) => this.observer?.onAgentCompacted(r, info),
     });
 
@@ -423,11 +381,11 @@ export class AgentManager {
     return record;
   }
 
-  getRecord(id: string): AgentRecord | undefined {
+  getRecord(id: string): Agent | undefined {
     return this.agents.get(id);
   }
 
-  listAgents(): AgentRecord[] {
+  listAgents(): Agent[] {
     return [...this.agents.values()].sort(
       (a, b) => b.startedAt - a.startedAt,
     );
@@ -444,18 +402,14 @@ export class AgentManager {
       return true;
     }
 
-    if (record.status !== "running") return false;
-    record.abortController?.abort();
-    record.markStopped();
-    return true;
+    return record.abort();
   }
 
   /** Dispose a record's session and remove it from the map. */
-  private removeRecord(id: string, record: AgentRecord): void {
+  private removeRecord(id: string, record: Agent): void {
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- dispose may not exist on all session implementations
     record.session?.dispose?.();
     this.agents.delete(id);
-    this.pendingSteers.delete(id);
   }
 
   private cleanup() {
@@ -501,11 +455,7 @@ export class AgentManager {
     this.queue = [];
     // Abort running agents
     for (const record of this.agents.values()) {
-      if (record.status === "running") {
-        record.abortController?.abort();
-        record.markStopped();
-        count++;
-      }
+      if (record.abort()) count++;
     }
     return count;
   }
@@ -513,7 +463,7 @@ export class AgentManager {
   /** Wait for all running and queued agents to complete (including queued ones). */
   // fallow-ignore-next-line unused-class-member
   async waitForAll(): Promise<void> {
-    // Loop because drainQueue respects the concurrency limit — as running
+    // Loop because drainQueue respects the concurrency limit - as running
     // agents finish they start queued ones, which need awaiting too.
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- intentional infinite loop with explicit break
     while (true) {

package/src/lifecycle/{agent-record.ts → agent.ts}

@@ -1,5 +1,5 @@
 /**
- * agent-record.ts — AgentRecord class with encapsulated status-transition logic.
+ * agent.ts — Agent class with encapsulated status-transition logic and per-agent behavior.
  *
  * Status transitions (status, result, error, startedAt, completedAt) are owned
  * by the class and exposed via transition methods. External code reads these
@@ -8,6 +8,9 @@
  * Stats (toolUses, lifetimeUsage, compactionCount) are owned by the class and
  * accumulated via mutation methods (incrementToolUses, addUsage, incrementCompactions).
  *
+ * Behavior (abort, steer buffering, worktree setup) lives on the agent
+ * rather than on AgentManager — each agent manages its own lifecycle concerns.
+ *
  * Phase-specific collaborators (execution, worktreeState, notification) are attached
  * after construction as lifecycle information becomes available.
  */
@@ -16,11 +19,12 @@ import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import type { ExecutionState } from "#src/lifecycle/execution-state";
 import type { LifetimeUsage } from "#src/lifecycle/usage";
 import { addUsage } from "#src/lifecycle/usage";
-import type { WorktreeState } from "#src/lifecycle/worktree-state";
+import type { WorktreeManager } from "#src/lifecycle/worktree";
+import { WorktreeState } from "#src/lifecycle/worktree-state";
 import type { NotificationState } from "#src/observation/notification-state";
-import type { AgentInvocation, SubagentType } from "#src/types";
+import type { AgentInvocation, IsolationMode, SubagentType } from "#src/types";
 
-export type AgentRecordStatus =
+export type AgentStatus =
 	| "queued"
 	| "running"
 	| "completed"
@@ -29,11 +33,11 @@ export type AgentRecordStatus =
 	| "stopped"
 	| "error";
 
-export interface AgentRecordInit {
+export interface AgentInit {
 	id: string;
 	type: SubagentType;
 	description: string;
-	status?: AgentRecordStatus;
+	status?: AgentStatus;
 	startedAt?: number;
 	completedAt?: number;
 	result?: string;
@@ -43,7 +47,7 @@ export interface AgentRecordInit {
 	promise?: Promise<string>;
 }
 
-export class AgentRecord {
+export class Agent {
 	// Identity — set once at construction
 	readonly id: string;
 	readonly type: SubagentType;
@@ -51,8 +55,8 @@ export class AgentRecord {
 	readonly invocation?: AgentInvocation;
 
 	// Transition state — encapsulated behind getters, mutated only via transition methods
-	private _status: AgentRecordStatus;
-	get status(): AgentRecordStatus { return this._status; }
+	private _status: AgentStatus;
+	get status(): AgentStatus { return this._status; }
 
 	private _result?: string;
 	get result(): string | undefined { return this._result; }
@@ -86,6 +90,29 @@ export class AgentRecord {
 	worktreeState?: WorktreeState;
 	notification?: NotificationState;
 
+	/**
+	 * Create a git worktree for isolated execution, set worktreeState, and return the worktree path.
+	 * Returns undefined if isolation is not "worktree".
+	 * Throws if worktree creation fails (strict isolation).
+	 */
+	setupWorktree(worktrees: WorktreeManager, isolation: IsolationMode | undefined): string | undefined {
+		if (isolation !== "worktree") return undefined;
+		const wt = worktrees.create(this.id);
+		if (!wt) {
+			throw new Error(
+				'Cannot run with isolation: "worktree" — not a git repo, no commits yet, or `git worktree add` failed. ' +
+				'Initialize git and commit at least once, or omit `isolation`.',
+			);
+		}
+		this.worktreeState = new WorktreeState(wt);
+		return wt.path;
+	}
+
+	// Steer buffer — messages queued before the session is ready
+	private _pendingSteers: string[] = [];
+	/** Number of steer messages waiting to be delivered. */
+	get pendingSteerCount(): number { return this._pendingSteers.length; }
+
 	/** The active agent session, or undefined before the session is created. */
 	get session(): AgentSession | undefined {
 		return this.execution?.session;
@@ -96,7 +123,7 @@ export class AgentRecord {
 		return this.execution?.outputFile;
 	}
 
-	constructor(init: AgentRecordInit) {
+	constructor(init: AgentInit) {
 		this.id = init.id;
 		this.type = init.type;
 		this.description = init.description;
@@ -190,6 +217,37 @@ export class AgentRecord {
 		this._completedAt = completedAt ?? Date.now();
 	}
 
+	/**
+	 * Abort a running agent: fire AbortController and transition to stopped.
+	 * Returns false if the agent is not running.
+	 * Queue removal stays on AgentManager until #230 extracts ConcurrencyQueue.
+	 */
+	abort(): boolean {
+		if (this._status !== "running") return false;
+		this.abortController?.abort();
+		this.markStopped();
+		return true;
+	}
+
+	/**
+	 * Buffer a steer message for delivery once the session is ready.
+	 * Called when steer is requested before onSessionCreated fires.
+	 */
+	queueSteer(message: string): void {
+		this._pendingSteers.push(message);
+	}
+
+	/**
+	 * Flush all buffered steer messages to the session and clear the buffer.
+	 * Called from onSessionCreated once the session is available.
+	 */
+	flushPendingSteers(session: AgentSession): void {
+		for (const msg of this._pendingSteers) {
+			session.steer(msg).catch(() => {});
+		}
+		this._pendingSteers = [];
+	}
+
 	/** Reset for resume: running status, new startedAt, clear completedAt/result/error. */
 	resetForResume(startedAt: number): void {
 		this._status = "running";

package/src/lifecycle/execution-state.ts

@@ -1,9 +1,9 @@
 /**
  * execution-state.ts — ExecutionState: execution-phase state for a running agent.
  *
- * Constructed and attached to AgentRecord when onSessionCreated fires inside startAgent().
+ * Constructed and attached to Agent when onSessionCreated fires inside startAgent().
  * Contains the session and output file — the two fields that become known once the
- * runner creates the session. promise stays as a separate AgentRecord field because
+ * runner creates the session. promise stays as a separate Agent field because
  * it is set at a different moment (after runner.run() returns).
  */
 

package/src/observation/notification.ts

@@ -1,6 +1,6 @@
 import { debugLog } from "#src/debug";
 import { getLifetimeTotal, getSessionContextPercent } from "#src/lifecycle/usage";
-import type { AgentRecord } from "#src/types";
+import type { Agent } 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: AgentRecord, resultMaxLen: number): string {
+export function formatTaskNotification(record: Agent, resultMaxLen: number): string {
   const status = getStatusLabel(record.status, record.error);
   const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
   const totalTokens = getLifetimeTotal(record.lifetimeUsage);
@@ -75,7 +75,7 @@ export function formatTaskNotification(record: AgentRecord, resultMaxLen: number
 
 /** Build notification details for the custom message renderer. */
 export function buildNotificationDetails(
-  record: AgentRecord,
+  record: Agent,
   resultMaxLen: number,
   activity?: AgentActivityTracker,
 ): NotificationDetails {
@@ -100,8 +100,8 @@ export function buildNotificationDetails(
   };
 }
 
-/** Build event data for lifecycle events from an AgentRecord. */
-export function buildEventData(record: AgentRecord) {
+/** Build event data for lifecycle events from an Agent. */
+export function buildEventData(record: Agent) {
   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: AgentRecord) {
 
 export interface NotificationSystem {
   cancelNudge: (key: string) => void;
-  sendCompletion: (record: AgentRecord) => void;
+  sendCompletion: (record: Agent) => void;
   cleanupCompleted: (id: string) => void;
   dispose: () => void;
 }
@@ -154,7 +154,7 @@ export class NotificationManager implements NotificationSystem {
     }
   }
 
-  sendCompletion(record: AgentRecord): void {
+  sendCompletion(record: Agent): 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: AgentRecord): void {
+  private emitIndividualNudge(record: Agent): void {
     if (record.notification?.resultConsumed) return;
 
     const notification = formatTaskNotification(record, 500);

package/src/observation/record-observer.ts

@@ -1,16 +1,16 @@
 /**
- * record-observer.ts — Subscribes to session events and updates AgentRecord stats.
+ * record-observer.ts — Subscribes to session events and updates Agent stats.
  *
  * Replaces the scattered callback-wrapping logic in AgentManager's startAgent()
  * and resume() with a single direct subscription.
  */
 
+import type { Agent } from "#src/lifecycle/agent";
 import type { CompactionInfo } from "#src/lifecycle/agent-manager";
-import type { AgentRecord } from "#src/lifecycle/agent-record";
 import type { SubscribableSession } from "#src/types";
 
-export interface RecordObserverOptions {
-  onCompact?: (record: AgentRecord, info: CompactionInfo) => void;
+export interface AgentObserverOptions {
+  onCompact?: (record: Agent, info: CompactionInfo) => void;
 }
 
 /**
@@ -23,10 +23,10 @@ export interface RecordObserverOptions {
  *
  * @returns An unsubscribe function.
  */
-export function subscribeRecordObserver(
+export function subscribeAgentObserver(
   session: SubscribableSession,
-  record: AgentRecord,
-  options?: RecordObserverOptions,
+  record: Agent,
+  options?: AgentObserverOptions,
 ): () => void {
   return session.subscribe((event) => {
     if (event.type === "tool_execution_end") {

package/src/service/service-adapter.ts

@@ -8,17 +8,16 @@
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { SpawnOptions, SubagentRecord, SubagentsService } from "#src/service/service";
 import type { ModelRegistry } from "#src/session/model-resolver";
-import type { AgentRecord, SessionContext } from "#src/types";
+import type { Agent, SessionContext } from "#src/types";
 
 /** Narrow interface for the AgentManager — avoids coupling to the concrete class. */
 export interface AgentManagerLike {
   spawn(snapshot: ParentSnapshot, type: string, prompt: string, options: unknown): string;
-  getRecord(id: string): AgentRecord | undefined;
-  listAgents(): AgentRecord[];
+  getRecord(id: string): Agent | undefined;
+  listAgents(): Agent[];
   abort(id: string): boolean;
   waitForAll(): Promise<void>;
   hasRunning(): boolean;
-  queueSteer(id: string, message: string): boolean;
 }
 
 /**
@@ -93,8 +92,9 @@ export class SubagentsServiceAdapter implements SubagentsService {
     }
     const session = record.session;
     if (!session) {
-      // Session not ready yet — queue via manager for delivery once initialized
-      return this.manager.queueSteer(id, message);
+      // Session not ready yet — buffer on the agent for delivery once initialized
+      record.queueSteer(message);
+      return true;
     }
     await session.steer(message);
     return true;
@@ -110,10 +110,10 @@ export class SubagentsServiceAdapter implements SubagentsService {
 }
 
 /**
- * Convert an internal AgentRecord to a serializable SubagentRecord.
+ * Convert an internal Agent to a serializable SubagentRecord.
  * Uses an explicit allowlist — new fields must be opted in.
  */
-export function toSubagentRecord(record: AgentRecord): SubagentRecord {
+export function toSubagentRecord(record: Agent): SubagentRecord {
   const out: SubagentRecord = {
     id: record.id,
     type: record.type,

package/src/tools/agent-tool.ts

@@ -11,7 +11,7 @@ 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 { AgentRecord } from "#src/types";
+import type { Agent } 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<AgentRecord>;
-	resume: (id: string, prompt: string, signal: AbortSignal) => Promise<AgentRecord | undefined>;
-	getRecord: (id: string) => AgentRecord | undefined;
+	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;
 }
 
 /** Narrow runtime interface — the Agent tool's slice of SubagentRuntime. */

package/src/tools/background-spawner.ts

@@ -3,14 +3,14 @@ import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { AgentActivityAccess } from "#src/tools/agent-tool";
 import { textResult } from "#src/tools/helpers";
 import type { ResolvedSpawnConfig } from "#src/tools/spawn-config";
-import type { AgentRecord } from "#src/types";
+import type { Agent } 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): AgentRecord | undefined;
+  getRecord(id: string): Agent | undefined;
 }
 
 /** Narrow widget interface for the background spawner. */