@gotgenes/pi-subagents 10.0.0 → 10.1.0

package/docs/retro/0242-rename-agent-tool-to-subagent.md

@@ -35,3 +35,48 @@ Pre-completion reviewer returned **PASS**.
 - The general-purpose agent type's `displayName: "Agent"` in `default-agents.ts` and `agent-types.ts` fallback was correctly left unchanged; `display.test.ts` still passes with `"Agent"`.
 - The description body inside the `agent-tool.ts` template literal needed separate edits because the guideline lines are not tab-indented (inside a backtick template literal, tab indentation does not apply).
 - Pre-completion reviewer: PASS — all deterministic checks, conventional commits, documentation, code design, tests, Mermaid diagrams, and dead-code gate all passed.
+
+## Stage: Final Retrospective (2026-05-27T14:07:32Z)
+
+### Session summary
+
+Completed the full plan→TDD→ship→retro lifecycle for #242 in a single session.
+Released as `pi-subagents-v10.0.0` (major bump from `feat!:` breaking change).
+Found and fixed one stale `Agent` tool reference in `.pi/skills/pre-completion/SKILL.md`.
+
+### Observations
+
+#### What went well
+
+- Three-model pipeline (opus for planning, sonnet for TDD, deepseek-flash for shipping) matched task complexity to model capability with no quality issues.
+- The plan's distinction between tool name (`"Agent"`) and agent-type `displayName` (`"Agent"`) prevented false-positive test updates — 8 test files reference `"Agent"` but only 4 needed changes.
+- Pre-completion reviewer caught no issues (PASS), confirming thorough planning.
+
+#### What caused friction (agent side)
+
+1. `missing-context` — Two failed `Edit` calls on `agent-tool.ts` line 175: the template literal's guideline lines have no tab indentation, but the agent initially assumed tab depth from the surrounding function.
+   Impact: 3 extra tool calls (grep to inspect actual indentation, then successful edit); no rework.
+   Self-identified.
+2. `wrong-abstraction` — Retro file edit duplicated Planning observations into the TDD stage because the `Edit` `oldText` matched from the Observations heading and the replacement included both old and new content.
+   Impact: 2 extra tool calls (read file, full `write` to fix); no rework.
+   Self-identified.
+3. `missing-context` — `.pi/skills/pre-completion/SKILL.md` line 32 references the `Agent` tool by name but was not in the plan's scope.
+   The plan checked pi-permission-system docs, `README.md`, and architecture docs but did not grep skill files for the old tool name.
+   Impact: discovered during retro; fixed as a retro change.
+
+#### What caused friction (user side)
+
+- None — the full pipeline ran with zero user corrections.
+
+### Diagnostic details
+
+- **Model-performance correlation** — Pre-completion reviewer ran as a default-model subagent (292.7s, 36 tool uses, 63.9k tokens).
+  Appropriate for the judgment-heavy review task.
+  Ship stage on `deepseek-v4-flash` was notably efficient for purely mechanical work.
+- **Feedback-loop gap analysis** — Verification was incremental: baseline check before TDD, per-file tests after Red and Green phases, full suite after implementation, then check + lint + fallow.
+  No gaps.
+
+### Changes made
+
+1. `.pi/skills/pre-completion/SKILL.md` — updated stale `Agent` tool reference to `subagent` on line 32.
+2. `.pi/agents/pre-completion-reviewer.md` — added rename-grep heuristic to the Skills bullet under Forward documentation checks: "When the change renames a symbol, grep `.pi/skills/` and `.pi/prompts/` for the old name."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "10.0.0",
+  "version": "10.1.0",
   "type": "module",
   "exports": {
     ".": "./src/service.ts"

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-runner.ts

@@ -15,37 +15,22 @@ import { registerChildSession, unregisterChildSession } from "#src/lifecycle/per
 import { extractAssistantContent } from "#src/session/content-items";
 import { extractText } from "#src/session/context";
 import type { EnvInfo } from "#src/session/env";
-import { type AssemblerIO, assembleSessionConfig, type ToolFilterConfig } from "#src/session/session-config";
+import { type AssemblerIO, assembleSessionConfig } from "#src/session/session-config";
 import type { ShellExec, SubagentType, ThinkingLevel } from "#src/types";
 
 /** Names of tools registered by this extension that subagents must NOT inherit. */
 const EXCLUDED_TOOL_NAMES = ["subagent", "get_subagent_result", "steer_subagent"];
 
 /**
- * Filter the session's active tool names according to extension rules.
+ * Filter the session's active tool names: remove recursion-guard tools.
  *
- * Run twice - once before `bindExtensions` (filters built-in tools) and once after
- * (filters extension-registered tools, which only join the active set during
- * `bindExtensions`). Extracting this keeps the two callsites consistent and makes
- * the post-bind re-filter trivial.
+ * Run once after `bindExtensions` so extension-registered tools (added during
+ * `bindExtensions`) are also covered by the guard.
  *
  * @param activeTools  Names currently active on the session.
- * @param config       Tool filtering configuration from the assembled session config.
  */
-function filterActiveTools(
-  activeTools: string[],
-  config: ToolFilterConfig,
-): string[] {
-  const { toolNames, extensions } = config;
-  if (!extensions) {
-    return activeTools;
-  }
-  const builtinToolNameSet = new Set(toolNames);
-  return activeTools.filter((t) => {
-    if (EXCLUDED_TOOL_NAMES.includes(t)) return false;
-    if (builtinToolNameSet.has(t)) return true;
-    return true;
-  });
+function filterActiveTools(activeTools: string[]): string[] {
+  return activeTools.filter((t) => !EXCLUDED_TOOL_NAMES.includes(t));
 }
 
 /** Normalize max turns. undefined or 0 = unlimited, otherwise minimum 1. */
@@ -305,7 +290,7 @@ export async function runAgent(
   const loader = io.createResourceLoader({
     cwd: cfg.effectiveCwd,
     agentDir,
-    noExtensions: !cfg.toolFilter.extensions,
+    noExtensions: !cfg.extensions,
     noSkills: cfg.noSkills,
     noPromptTemplates: true,
     noThemes: true,
@@ -329,18 +314,11 @@ export async function runAgent(
     settingsManager: io.createSettingsManager(cfg.effectiveCwd, agentDir),
     modelRegistry: snapshot.modelRegistry,
     model: cfg.model,
-    tools: cfg.toolFilter.toolNames,
+    tools: cfg.toolNames,
     resourceLoader: loader,
     thinkingLevel: cfg.thinkingLevel,
   });
 
-  // Filter active tools: remove our own tools to prevent nesting.
-  // First pass - over built-in tools, before bindExtensions registers extension tools.
-  if (cfg.toolFilter.extensions) {
-    const filtered = filterActiveTools(session.getActiveToolNames(), cfg.toolFilter);
-    session.setActiveToolsByName(filtered);
-  }
-
   // Register with pi-permission-system's SubagentSessionRegistry before
   // bindExtensions() so isSubagentExecutionContext() hits the registry on the
   // first check during child extension initialization. Unregistered in the
@@ -356,14 +334,13 @@ export async function runAgent(
   // respect the active tool set. All ExtensionBindings fields are optional.
   await session.bindExtensions({});
 
-  // Patch 2 (RepOne #443): re-filter active tools after bindExtensions.
-  // Extension-registered tools (added during bindExtensions) are not in the
-  // session's active set when the first filter pass runs above. Without this
-  // re-filter, EXCLUDED_TOOL_NAMES would not be applied to extension-registered
-  // tools. Run the same filter against the post-bind active set.
-  if (cfg.toolFilter.extensions) {
-    const refiltered = filterActiveTools(session.getActiveToolNames(), cfg.toolFilter);
-    session.setActiveToolsByName(refiltered);
+  // Apply recursion guard: remove our own tools from the child's active set.
+  // Runs after bindExtensions so extension-registered tools are included in the
+  // post-bind active set. Only needed when extensions are loaded (extensions: false
+  // means no extension tools were registered, so the guard is a no-op).
+  if (cfg.extensions) {
+    const filtered = filterActiveTools(session.getActiveToolNames());
+    session.setActiveToolsByName(filtered);
   }
 
   options.onSessionCreated?.(session);

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