@gotgenes/pi-subagents 6.7.0 → 6.8.0

package/src/agent-manager.ts

@@ -13,11 +13,13 @@ import { AgentRecord } from "./agent-record.js";
 import type { AgentRunner } from "./agent-runner.js";
 import { AgentTypeRegistry } from "./agent-types.js";
 import { debugLog } from "./debug.js";
+import type { ExecutionState } from "./execution-state.js";
 import { buildParentSnapshot } from "./parent-snapshot.js";
 import { subscribeRecordObserver } from "./record-observer.js";
 import type { RunConfig } from "./runtime.js";
 import type { AgentInvocation, IsolationMode, ParentSnapshot, ShellExec, SubagentType, ThinkingLevel } from "./types.js";
 import type { WorktreeManager } from "./worktree.js";
+import { WorktreeState } from "./worktree-state.js";
 
 export type OnAgentComplete = (record: AgentRecord) => void;
 export type OnAgentStart = (record: AgentRecord) => void;
@@ -92,6 +94,8 @@ 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;
@@ -116,6 +120,19 @@ 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.
@@ -173,7 +190,7 @@ export class AgentManager {
           'Initialize git and commit at least once, or omit `isolation`.',
         );
       }
-      record.worktree = wt;
+      record.worktreeState = new WorktreeState(wt);
       worktreeCwd = wt.path;
     }
 
@@ -207,17 +224,18 @@ export class AgentManager {
       signal: record.abortController!.signal,
       registry: this.registry,
       onSessionCreated: (session) => {
-        record.session = session;
         // Capture the session file path early so it's available for display
         // before the run completes (e.g. in background agent status messages).
-        const file = session.sessionManager?.getSessionFile?.();
-        if (file) record.outputFile = file;
+        const outputFile = session.sessionManager?.getSessionFile?.() ?? undefined;
+        // Set the execution-state collaborator — born complete at session creation.
+        record.execution = { session, outputFile };
         // Flush any steers that arrived before the session was ready
-        if (record.pendingSteers?.length) {
-          for (const msg of record.pendingSteers) {
+        const buffered = this.pendingSteers.get(id);
+        if (buffered?.length) {
+          for (const msg of buffered) {
             session.steer(msg).catch(() => {});
           }
-          record.pendingSteers = undefined;
+          this.pendingSteers.delete(id);
         }
         // Subscribe record observer for stats accumulation
         unsubRecordObserver = subscribeRecordObserver(session, record, {
@@ -232,9 +250,9 @@ export class AgentManager {
 
         // Clean up worktree before transition so the final result includes branch text
         let finalResult = responseText;
-        if (record.worktree) {
-          const wtResult = this.worktrees.cleanup(record.worktree, options.description);
-          record.worktreeResult = wtResult;
+        if (record.worktreeState) {
+          const wtResult = this.worktrees.cleanup(record.worktreeState, options.description);
+          record.worktreeState.recordCleanup(wtResult);
           if (wtResult.hasChanges && wtResult.branch) {
             finalResult += `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
           }
@@ -245,8 +263,8 @@ export class AgentManager {
         else if (steered) record.markSteered(finalResult);
         else record.markCompleted(finalResult);
 
-        record.session = session;
-        if (sessionFile) record.outputFile = sessionFile;
+        // Update execution collaborator with final session/outputFile from runner
+        record.execution = { session, outputFile: sessionFile ?? record.execution?.outputFile };
 
         if (options.isBackground) {
           this.runningBackground--;
@@ -262,10 +280,11 @@ export class AgentManager {
         detach();
 
         // Best-effort worktree cleanup on error
-        if (record.worktree) {
+        if (record.worktreeState) {
           try {
-            const wtResult = this.worktrees.cleanup(record.worktree, options.description);
-            record.worktreeResult = wtResult;
+            const wtResult = this.worktrees.cleanup(record.worktreeState, options.description);
+            record.worktreeState.recordCleanup(wtResult);
+
           } catch (err) { debugLog("cleanupWorktree on agent error", err); }
         }
 
@@ -322,16 +341,17 @@ export class AgentManager {
     signal?: AbortSignal,
   ): Promise<AgentRecord | undefined> {
     const record = this.agents.get(id);
-    if (!record?.session) return undefined;
+    const session = record?.execution?.session;
+    if (!session) return undefined;
 
     record.resetForResume(Date.now());
 
-    const unsubResume = subscribeRecordObserver(record.session, record, {
+    const unsubResume = subscribeRecordObserver(session, record, {
       onCompact: (r, info) => this.onCompact?.(r, info),
     });
 
     try {
-      const responseText = await this.runner.resume(record.session, prompt, {
+      const responseText = await this.runner.resume(session, prompt, {
         signal,
       });
       record.markCompleted(responseText);
@@ -373,9 +393,9 @@ export class AgentManager {
 
   /** Dispose a record's session and remove it from the map. */
   private removeRecord(id: string, record: AgentRecord): void {
-    record.session?.dispose?.();
-    record.session = undefined;
+    record.execution?.session?.dispose?.();
     this.agents.delete(id);
+    this.pendingSteers.delete(id);
   }
 
   private cleanup() {
@@ -448,7 +468,7 @@ export class AgentManager {
     // Clear queue
     this.queue = [];
     for (const record of this.agents.values()) {
-      record.session?.dispose();
+      record.execution?.session?.dispose();
     }
     this.agents.clear();
     // Prune any orphaned git worktrees (crash recovery)

package/src/agent-record.ts

@@ -5,12 +5,19 @@
  * by the class and exposed via transition methods. External code reads these
  * fields through public properties but cannot write them directly.
  *
- * Non-transition state (session, toolUses, lifetimeUsage, etc.) remains public.
+ * Stats (toolUses, lifetimeUsage, compactionCount) are owned by the class and
+ * accumulated via mutation methods (incrementToolUses, addUsage, incrementCompactions).
+ *
+ * Phase-specific collaborators (execution, worktreeState, notification) are attached
+ * after construction as lifecycle information becomes available.
  */
 
-import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import type { ExecutionState } from "./execution-state.js";
+import type { NotificationState } from "./notification-state.js";
 import type { AgentInvocation, SubagentType } from "./types.js";
 import type { LifetimeUsage } from "./usage.js";
+import { addUsage } from "./usage.js";
+import type { WorktreeState } from "./worktree-state.js";
 
 export type AgentRecordStatus =
 	| "queued"
@@ -30,19 +37,9 @@ export interface AgentRecordInit {
 	completedAt?: number;
 	result?: string;
 	error?: string;
-	toolUses?: number;
-	lifetimeUsage?: LifetimeUsage;
-	compactionCount?: number;
 	abortController?: AbortController;
 	invocation?: AgentInvocation;
-	session?: AgentSession;
 	promise?: Promise<string>;
-	resultConsumed?: boolean;
-	pendingSteers?: string[];
-	worktree?: { path: string; branch: string };
-	worktreeResult?: { hasChanges: boolean; branch?: string };
-	toolCallId?: string;
-	outputFile?: string;
 }
 
 export class AgentRecord {
@@ -68,19 +65,25 @@ export class AgentRecord {
 	private _completedAt?: number;
 	get completedAt(): number | undefined { return this._completedAt; }
 
-	// Non-transition mutable state
-	toolUses: number;
-	lifetimeUsage: LifetimeUsage;
-	compactionCount: number;
-	session?: AgentSession;
-	abortController?: AbortController;
+	// Stats — accumulated via mutation methods, readable via getters
+	private _toolUses: number;
+	get toolUses(): number { return this._toolUses; }
+
+	private _lifetimeUsage: LifetimeUsage;
+	get lifetimeUsage(): Readonly<LifetimeUsage> { return this._lifetimeUsage; }
+
+	private _compactionCount: number;
+	get compactionCount(): number { return this._compactionCount; }
+
+	/** AbortController for cancelling this agent. Set at construction; used only by AgentManager. */
+	readonly abortController?: AbortController;
+	/** Promise for the full agent run (including post-processing). Set once by AgentManager. */
 	promise?: Promise<string>;
-	resultConsumed?: boolean;
-	pendingSteers?: string[];
-	worktree?: { path: string; branch: string };
-	worktreeResult?: { hasChanges: boolean; branch?: string };
-	toolCallId?: string;
-	outputFile?: string;
+
+	// Phase-specific collaborators — each born complete when their info becomes available
+	execution?: ExecutionState;
+	worktreeState?: WorktreeState;
+	notification?: NotificationState;
 
 	constructor(init: AgentRecordInit) {
 		this.id = init.id;
@@ -94,18 +97,26 @@ export class AgentRecord {
 		this._startedAt = init.startedAt ?? Date.now();
 		this._completedAt = init.completedAt;
 
-		this.toolUses = init.toolUses ?? 0;
-		this.lifetimeUsage = init.lifetimeUsage ?? { input: 0, output: 0, cacheWrite: 0 };
-		this.compactionCount = init.compactionCount ?? 0;
+		this._toolUses = 0;
+		this._lifetimeUsage = { input: 0, output: 0, cacheWrite: 0 };
+		this._compactionCount = 0;
 		this.abortController = init.abortController;
-		this.session = init.session;
 		this.promise = init.promise;
-		this.resultConsumed = init.resultConsumed;
-		this.pendingSteers = init.pendingSteers;
-		this.worktree = init.worktree;
-		this.worktreeResult = init.worktreeResult;
-		this.toolCallId = init.toolCallId;
-		this.outputFile = init.outputFile;
+	}
+
+	/** Increment tool use count. Called by record-observer on tool_execution_end. */
+	incrementToolUses(): void {
+		this._toolUses++;
+	}
+
+	/** Accumulate a usage delta into lifetimeUsage. Called by record-observer on message_end. */
+	addUsage(delta: { input: number; output: number; cacheWrite: number }): void {
+		addUsage(this._lifetimeUsage, delta);
+	}
+
+	/** Increment compaction count. Called by record-observer on compaction_end. */
+	incrementCompactions(): void {
+		this._compactionCount++;
 	}
 
 	/** Transition to running state. Sets status and startedAt. */

package/src/execution-state.ts

@@ -0,0 +1,17 @@
+/**
+ * execution-state.ts — ExecutionState: execution-phase state for a running agent.
+ *
+ * Constructed and attached to AgentRecord 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
+ * it is set at a different moment (after runner.run() returns).
+ */
+
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+
+export interface ExecutionState {
+	/** The active agent session — available from the moment the session is created. */
+	readonly session: AgentSession;
+	/** Path to the agent's session JSONL file, or undefined if not yet available. */
+	readonly outputFile: string | undefined;
+}

package/src/index.ts

@@ -88,7 +88,7 @@ export default function (pi: ExtensionAPI) {
       });
 
       // Skip notification if result was already consumed via get_subagent_result
-      if (record.resultConsumed) {
+      if (record.notification?.resultConsumed) {
         notifications.cleanupCompleted(record.id);
         return;
       }
@@ -215,6 +215,7 @@ export default function (pi: ExtensionAPI) {
     getRecord: (id) => manager.getRecord(id),
     emitEvent: (name, data) => pi.events.emit(name, data),
     steerAgent: (session, message) => steerAgent(session, message),
+    queueSteer: (id, message) => manager.queueSteer(id, message),
   })));
 
   // ---- /agents interactive menu ----

package/src/notification-state.ts

@@ -0,0 +1,27 @@
+/**
+ * notification-state.ts — NotificationState: notification-scoped tracking per background agent.
+ *
+ * Constructed once when agent-tool assigns the tool call ID (background agents only).
+ * Foreground agents never get a NotificationState — record.notification stays undefined.
+ */
+
+export class NotificationState {
+	/** The tool call ID that spawned this background agent. Used in task-notification XML. */
+	readonly toolCallId: string;
+
+	private _resultConsumed = false;
+
+	constructor(toolCallId: string) {
+		this.toolCallId = toolCallId;
+	}
+
+	/** Whether the parent agent has already consumed this result (suppresses duplicate notifications). */
+	get resultConsumed(): boolean {
+		return this._resultConsumed;
+	}
+
+	/** Mark the result as consumed — suppresses the completion notification. */
+	markConsumed(): void {
+		this._resultConsumed = true;
+	}
+}

package/src/notification.ts

@@ -31,7 +31,7 @@ export function formatTaskNotification(record: AgentRecord, resultMaxLen: number
   const status = getStatusLabel(record.status, record.error);
   const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
   const totalTokens = getLifetimeTotal(record.lifetimeUsage);
-  const contextPercent = getSessionContextPercent(record.session);
+  const contextPercent = getSessionContextPercent(record.execution?.session);
   const ctxXml = contextPercent !== null ? `<context_percent>${Math.round(contextPercent)}</context_percent>` : "";
   const compactXml = record.compactionCount ? `<compactions>${record.compactionCount}</compactions>` : "";
 
@@ -41,11 +41,13 @@ export function formatTaskNotification(record: AgentRecord, resultMaxLen: number
       : record.result
     : "No output.";
 
+  const toolCallId = record.notification?.toolCallId;
+  const outputFile = record.execution?.outputFile;
   return [
     "<task-notification>",
     `<task-id>${record.id}</task-id>`,
-    record.toolCallId ? `<tool-use-id>${escapeXml(record.toolCallId)}</tool-use-id>` : null,
-    record.outputFile ? `<output-file>${escapeXml(record.outputFile)}</output-file>` : null,
+    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>`,
     `<result>${escapeXml(resultPreview)}</result>`,
@@ -73,7 +75,7 @@ export function buildNotificationDetails(
     maxTurns: activity?.maxTurns,
     totalTokens,
     durationMs: record.completedAt ? record.completedAt - record.startedAt : 0,
-    outputFile: record.outputFile,
+    outputFile: record.execution?.outputFile,
     error: record.error,
     resultPreview: record.result
       ? record.result.length > resultMaxLen
@@ -154,10 +156,11 @@ export function createNotificationSystem(deps: NotificationDeps): NotificationSy
   }
 
   function emitIndividualNudge(record: AgentRecord) {
-    if (record.resultConsumed) return;
+    if (record.notification?.resultConsumed) return;
 
     const notification = formatTaskNotification(record, 500);
-    const footer = record.outputFile ? `\nFull transcript available at: ${record.outputFile}` : "";
+    const outputFile = record.execution?.outputFile;
+    const footer = outputFile ? `\nFull transcript available at: ${outputFile}` : "";
 
     deps.sendMessage(
       {

package/src/record-observer.ts

@@ -7,7 +7,6 @@
 
 import type { CompactionInfo } from "./agent-manager.js";
 import type { AgentRecord } from "./agent-record.js";
-import { addUsage } from "./usage.js";
 
 /** Narrow session interface — only the subscribe method needed by the observer. */
 interface SubscribableSession {
@@ -22,9 +21,9 @@ export interface RecordObserverOptions {
  * Subscribe to session events and accumulate stats on the agent record.
  *
  * Handles:
- * - `tool_execution_end` → `record.toolUses++`
- * - `message_end` (assistant, with usage) → `addUsage(record.lifetimeUsage, …)`
- * - `compaction_end` (not aborted) → `record.compactionCount++`, call `onCompact`
+ * - `tool_execution_end` → `record.incrementToolUses()`
+ * - `message_end` (assistant, with usage) → `record.addUsage(…)`
+ * - `compaction_end` (not aborted) → `record.incrementCompactions()`, call `onCompact`
  *
  * @returns An unsubscribe function.
  */
@@ -35,13 +34,13 @@ export function subscribeRecordObserver(
 ): () => void {
   return session.subscribe((event: any) => {
     if (event.type === "tool_execution_end") {
-      record.toolUses++;
+      record.incrementToolUses();
     }
 
     if (event.type === "message_end" && event.message?.role === "assistant") {
       const u = event.message.usage;
       if (u) {
-        addUsage(record.lifetimeUsage, {
+        record.addUsage({
           input: u.input ?? 0,
           output: u.output ?? 0,
           cacheWrite: u.cacheWrite ?? 0,
@@ -50,7 +49,7 @@ export function subscribeRecordObserver(
     }
 
     if (event.type === "compaction_end" && !event.aborted && event.result) {
-      record.compactionCount++;
+      record.incrementCompactions();
       options?.onCompact?.(record, {
         reason: event.reason,
         tokensBefore: event.result.tokensBefore,

package/src/service-adapter.ts

@@ -17,6 +17,7 @@ export interface AgentManagerLike {
   abort(id: string): boolean;
   waitForAll(): Promise<void>;
   hasRunning(): boolean;
+  queueSteer(id: string, message: string): boolean;
 }
 
 /** Dependencies injected into the adapter factory. */
@@ -85,13 +86,12 @@ export function createSubagentsService(deps: AdapterDeps): SubagentsService {
       if (!record || record.status !== "running") {
         return false;
       }
-      if (!record.session) {
-        // Session not ready yet — queue for delivery once initialized
-        if (!record.pendingSteers) record.pendingSteers = [];
-        record.pendingSteers.push(message);
-        return true;
+      const session = record.execution?.session;
+      if (!session) {
+        // Session not ready yet — queue via manager for delivery once initialized
+        return manager.queueSteer(id, message);
       }
-      await record.session.steer(message);
+      await session.steer(message);
       return true;
     },
 
@@ -124,7 +124,8 @@ export function toSubagentRecord(record: AgentRecord): SubagentRecord {
   if (record.result !== undefined) out.result = record.result;
   if (record.error !== undefined) out.error = record.error;
   if (record.completedAt !== undefined) out.completedAt = record.completedAt;
-  if (record.worktreeResult !== undefined) out.worktreeResult = record.worktreeResult;
+  const worktreeResult = record.worktreeState?.cleanupResult;
+  if (worktreeResult !== undefined) out.worktreeResult = worktreeResult;
 
   return out;
 }

package/src/tools/agent-tool.ts

@@ -7,6 +7,7 @@ import { AgentTypeRegistry } from "../agent-types.js";
 import { resolveAgentInvocationConfig } from "../invocation-config.js";
 import { resolveInvocationModel } from "../model-resolver.js";
 
+import { NotificationState } from "../notification-state.js";
 import type { AgentInvocation, AgentRecord, SubagentType } from "../types.js";
 import { AgentActivityTracker } from "../ui/agent-activity-tracker.js";
 import {
@@ -381,7 +382,7 @@ Guidelines:
             `Agent not found: "${params.resume}". It may have been cleaned up.`,
           );
         }
-        if (!existing.session) {
+        if (!existing.execution?.session) {
           return textResult(
             `Agent "${params.resume}" has no active session to resume.`,
           );
@@ -430,7 +431,8 @@ Guidelines:
 
         const record = deps.manager.getRecord(id);
         if (record) {
-          record.toolCallId = toolCallId;
+          // Born complete: notification-state object owns toolCallId + resultConsumed.
+          record.notification = new NotificationState(toolCallId);
         }
 
         deps.agentActivity.set(id, bgState);
@@ -451,7 +453,7 @@ Guidelines:
             `Agent ID: ${id}\n` +
             `Type: ${displayName}\n` +
             `Description: ${params.description}\n` +
-            (record?.outputFile ? `Output file: ${record.outputFile}\n` : "") +
+            (record?.execution?.outputFile ? `Output file: ${record.execution.outputFile}\n` : "") +
             (isQueued
               ? `Position: queued (max ${deps.manager.getMaxConcurrent()} concurrent)\n`
               : "") +
@@ -525,7 +527,7 @@ Guidelines:
               fgState.setSession(session);
               unsubUI = subscribeUIObserver(session, fgState, streamUpdate);
               for (const a of deps.manager.listAgents()) {
-                if (a.session === session) {
+                if (a.execution?.session === session) {
                   fgId = a.id;
                   deps.agentActivity.set(a.id, fgState);
                   deps.widget.ensureTimer();

package/src/tools/get-result-tool.ts

@@ -54,7 +54,9 @@ export function createGetResultTool(deps: GetResultDeps) {
       // (attached earlier at spawn time) and always runs before this await resumes.
       // Setting the flag here prevents a redundant follow-up notification.
       if (params.wait && record.status === "running" && record.promise) {
-        record.resultConsumed = true;
+        // Pre-mark consumed BEFORE awaiting — onComplete fires inside .then() and
+        // always runs before this await resumes. Prevents a redundant notification.
+        record.notification?.markConsumed();
         deps.cancelNudge(params.agent_id);
         await record.promise;
       }
@@ -62,7 +64,7 @@ export function createGetResultTool(deps: GetResultDeps) {
       const displayName = getDisplayName(record.type, deps.registry);
       const duration = formatDuration(record.startedAt, record.completedAt);
       const tokens = formatLifetimeTokens(record);
-      const contextPercent = getSessionContextPercent(record.session);
+      const contextPercent = getSessionContextPercent(record.execution?.session);
       const statsParts = [`Tool uses: ${record.toolUses}`];
       if (tokens) statsParts.push(tokens);
       if (contextPercent !== null) statsParts.push(`Context: ${Math.round(contextPercent)}%`);
@@ -84,13 +86,13 @@ export function createGetResultTool(deps: GetResultDeps) {
 
       // Mark result as consumed — suppresses the completion notification
       if (record.status !== "running" && record.status !== "queued") {
-        record.resultConsumed = true;
+        record.notification?.markConsumed();
         deps.cancelNudge(params.agent_id);
       }
 
       // Verbose: include full conversation
-      if (params.verbose && record.session) {
-        const conversation = deps.getConversation(record.session);
+      if (params.verbose && record.execution?.session) {
+        const conversation = deps.getConversation(record.execution.session);
         if (conversation) {
           output += `\n\n--- Agent Conversation ---\n${conversation}`;
         }

package/src/tools/steer-tool.ts

@@ -9,6 +9,8 @@ export interface SteerToolDeps {
   getRecord: (id: string) => AgentRecord | undefined;
   emitEvent: (name: string, data: unknown) => void;
   steerAgent: (session: AgentSession, message: string) => Promise<void>;
+  /** Buffer a steer for an agent whose session isn't ready yet. */
+  queueSteer: (id: string, message: string) => boolean;
 }
 
 /** Create the steer_subagent tool definition (without Pi SDK wrapper). */
@@ -46,10 +48,10 @@ export function createSteerTool(deps: SteerToolDeps) {
           `Agent "${params.agent_id}" is not running (status: ${record.status}). Cannot steer a non-running agent.`,
         );
       }
-      if (!record.session) {
-        // Session not ready yet — queue the steer for delivery once initialized
-        if (!record.pendingSteers) record.pendingSteers = [];
-        record.pendingSteers.push(params.message);
+      const session = record.execution?.session;
+      if (!session) {
+        // Session not ready yet — queue via manager for delivery once initialized
+        deps.queueSteer(record.id, params.message);
         deps.emitEvent("subagents:steered", { id: record.id, message: params.message });
         return textResult(
           `Steering message queued for agent ${record.id}. It will be delivered once the session initializes.`,
@@ -57,10 +59,10 @@ export function createSteerTool(deps: SteerToolDeps) {
       }
 
       try {
-        await deps.steerAgent(record.session, params.message);
+        await deps.steerAgent(session, params.message);
         deps.emitEvent("subagents:steered", { id: record.id, message: params.message });
         const tokens = formatLifetimeTokens(record);
-        const contextPercent = getSessionContextPercent(record.session);
+        const contextPercent = getSessionContextPercent(session);
         const stateParts: string[] = [];
         if (tokens) stateParts.push(tokens);
         stateParts.push(`${record.toolUses} tool ${record.toolUses === 1 ? "use" : "uses"}`);

package/src/ui/agent-menu.ts

@@ -197,7 +197,8 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
   }
 
   async function viewAgentConversation(ctx: ExtensionContext, record: AgentRecord) {
-    if (!record.session) {
+    const session = record.execution?.session;
+    if (!session) {
       ctx.ui.notify(
         `Agent is ${record.status === "queued" ? "queued" : "expired"} — no session available.`,
         "info",
@@ -208,7 +209,6 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
     const { ConversationViewer, VIEWPORT_HEIGHT_PCT } = await import(
       "./conversation-viewer.js"
     );
-    const session = record.session;
     const activity = deps.agentActivity.get(record.id);
 
     await ctx.ui.custom<undefined>(

package/src/worktree-state.ts

@@ -0,0 +1,35 @@
+/**
+ * worktree-state.ts — WorktreeState: lifecycle-phase object for worktree-isolated agents.
+ *
+ * Constructed once when the worktree is set up (before the run begins).
+ * Only exists for agents with isolation: "worktree".
+ * cleanupResult is recorded once at completion or error — it is not set at construction.
+ */
+
+import type { WorktreeCleanupResult, WorktreeInfo } from "./worktree.js";
+
+export type { WorktreeCleanupResult, WorktreeInfo };
+
+export class WorktreeState {
+	/** Absolute path to the worktree directory. */
+	readonly path: string;
+	/** Branch name created for this worktree. */
+	readonly branch: string;
+
+	private _cleanupResult?: WorktreeCleanupResult;
+
+	constructor(info: WorktreeInfo) {
+		this.path = info.path;
+		this.branch = info.branch;
+	}
+
+	/** Result of the worktree cleanup — undefined until recordCleanup is called. */
+	get cleanupResult(): WorktreeCleanupResult | undefined {
+		return this._cleanupResult;
+	}
+
+	/** Record the cleanup result. Called once on agent completion or error. */
+	recordCleanup(result: WorktreeCleanupResult): void {
+		this._cleanupResult = result;
+	}
+}