@gotgenes/pi-subagents 5.5.0 → 5.7.0

package/docs/plans/0087-evolve-subagent-runtime-methods.md

@@ -0,0 +1,240 @@
+---
+issue: 87
+issue_title: "refactor: evolve SubagentRuntime from data bag to object with methods"
+---
+
+# Evolve SubagentRuntime from data bag to object with methods
+
+## Problem Statement
+
+`SubagentRuntime` (introduced in #69) consolidates all mutable extension state into one object, but it remains a plain data bag — an interface with public mutable fields and no methods.
+This causes two structural smells in `index.ts`:
+
+1. **Output arguments** — handlers write raw fields on the runtime instead of calling methods:
+   `runtime.currentCtx = { pi, ctx }` and `runtime.currentCtx = undefined`.
+2. **Law of Demeter violations** — 8 occurrences of `runtime.widget!.method()` across 4 call sites in `index.ts`, where callers reach through the runtime to talk to the widget with unsafe `!` non-null assertions.
+
+Issue #70 (extract event handlers) explicitly lists this issue as a prerequisite.
+Without these methods, extracted handlers would just move the output-argument and LoD smells from `index.ts` into handler classes.
+
+## Goals
+
+- Convert `SubagentRuntime` from an interface + factory to a class with methods.
+- Add session-context methods: `setSessionContext(pi, ctx)` and `clearSessionContext()`.
+- Add widget delegation methods that absorb the `runtime.widget!` reach-throughs: `setUICtx()`, `onTurnStart()`, `markFinished()`, `updateWidget()`, `ensureTimer()`.
+- Update all 10 call sites in `index.ts` to use the new methods — eliminate raw `currentCtx` field writes and `widget!` assertions.
+- No behavior change; pure structural refactor.
+
+## Non-Goals
+
+- Extracting event handlers into separate files (that is #70).
+- Adding methods for `defaultMaxTurns` / `graceTurns` writes — those field writes remain as-is; the issue scope covers `currentCtx` and `widget!` only.
+- Changing the `SubagentsService` interface.
+- Making `widget` private — `index.ts` still assigns `runtime.widget = new AgentWidget(...)` after construction.
+- Adding new features.
+
+## Background
+
+### Prior art
+
+`pi-permission-system`'s `PermissionSession` is a class with lifecycle methods (`refreshConfig`, `resetForNewSession`, `shutdown`).
+Lifecycle handlers in `src/handlers/lifecycle.ts` call those methods instead of writing fields.
+This issue brings `SubagentRuntime` to the same level.
+
+### Current runtime shape
+
+`src/runtime.ts` exports a `SubagentRuntime` interface and a `createSubagentRuntime()` factory:
+
+```typescript
+export interface SubagentRuntime {
+  defaultMaxTurns: number | undefined;
+  graceTurns: number;
+  currentCtx: { pi: unknown; ctx: unknown } | undefined;
+  readonly agentActivity: Map<string, AgentActivity>;
+  widget: AgentWidget | null;
+}
+```
+
+### Call sites to migrate
+
+Two `currentCtx` writes (output arguments):
+
+| Line | Current                            | After                                |
+| ---- | ---------------------------------- | ------------------------------------ |
+| 126  | `runtime.currentCtx = { pi, ctx }` | `runtime.setSessionContext(pi, ctx)` |
+| 138  | `runtime.currentCtx = undefined`   | `runtime.clearSessionContext()`      |
+
+Eight `widget!` reach-throughs (LoD violations):
+
+| Line | Current                                     | After                               |
+| ---- | ------------------------------------------- | ----------------------------------- |
+| 60   | `runtime.widget!.markFinished(id)`          | `runtime.markFinished(id)`          |
+| 61   | `runtime.widget!.update()`                  | `runtime.updateWidget()`            |
+| 149  | `runtime.widget!.setUICtx(ctx.ui as UICtx)` | `runtime.setUICtx(ctx.ui as UICtx)` |
+| 150  | `runtime.widget!.onTurnStart()`             | `runtime.onTurnStart()`             |
+| 204  | `runtime.widget!.setUICtx(ctx as UICtx)`    | `runtime.setUICtx(ctx as UICtx)`    |
+| 205  | `runtime.widget!.ensureTimer()`             | `runtime.ensureTimer()`             |
+| 206  | `runtime.widget!.update()`                  | `runtime.updateWidget()`            |
+| 207  | `runtime.widget!.markFinished(id)`          | `runtime.markFinished(id)`          |
+
+### Dependency chain
+
+Issue #69 (SubagentRuntime) is closed/implemented.
+This issue (#87) is a prerequisite for #70 (extract event handlers).
+The #70 plan defines narrow handler interfaces (`LifecycleRuntime`, `ToolStartRuntime`) that the runtime class satisfies structurally.
+
+### Relevant constraints from AGENTS.md / code-style skill
+
+- Keep modules focused and composable (one concern per file).
+- Do not pass a shared dependency bag to functions that only use a subset — define narrow interfaces per consumer.
+- Do not write back into a received dependency bag (output arguments).
+- Do not reach through an injected collaborator to talk to a stranger (Law of Demeter).
+- When multiple callers perform the same reach-through, the missing abstraction is a method on the intermediate object that delegates internally.
+
+## Design Overview
+
+### Class conversion
+
+Convert `SubagentRuntime` from an interface to a class.
+Public fields stay as-is — callers that read `runtime.defaultMaxTurns`, `runtime.currentCtx`, `runtime.agentActivity`, etc. continue to work.
+The `createSubagentRuntime()` factory becomes a thin alias returning `new SubagentRuntime()`, preserving backward compatibility for `index.ts` and existing tests during the transition.
+
+```typescript
+export class SubagentRuntime {
+  defaultMaxTurns: number | undefined = undefined;
+  graceTurns: number = 5;
+  currentCtx: { pi: unknown; ctx: unknown } | undefined = undefined;
+  readonly agentActivity: Map<string, AgentActivity> = new Map();
+  widget: AgentWidget | null = null;
+
+  setSessionContext(pi: unknown, ctx: unknown): void {
+    this.currentCtx = { pi, ctx };
+  }
+
+  clearSessionContext(): void {
+    this.currentCtx = undefined;
+  }
+
+  setUICtx(ctx: UICtx): void {
+    this.widget?.setUICtx(ctx);
+  }
+
+  onTurnStart(): void {
+    this.widget?.onTurnStart();
+  }
+
+  markFinished(id: string): void {
+    this.widget?.markFinished(id);
+  }
+
+  updateWidget(): void {
+    this.widget?.update();
+  }
+
+  ensureTimer(): void {
+    this.widget?.ensureTimer();
+  }
+}
+```
+
+### Widget delegation null safety
+
+Current code uses `runtime.widget!.method()` — an unsafe non-null assertion that would throw if widget were null.
+The delegation methods use optional chaining (`this.widget?.method()`), which silently no-ops when widget is null.
+This is safe and intentional: widget is always assigned before any agent can complete, so the null path is unreachable in practice, but the delegation removes the assertion smell.
+The #70 plan explicitly expects this behavior: "Widget null safety: after #87, the runtime's delegation methods handle null internally."
+
+### UICtx type import
+
+`runtime.ts` already imports `AgentActivity` and `AgentWidget` from `ui/agent-widget.ts`.
+Adding `UICtx` to the same type import is consistent with the existing dependency.
+`UICtx` is a lean local interface (two method signatures), not a Pi SDK type.
+
+### What stays unchanged
+
+- `RunConfig` interface — remains as-is.
+- `defaultMaxTurns` / `graceTurns` field writes from settings appliers — out of scope per non-goals.
+- `runtime.currentCtx` reads via getter callbacks (`getCtx: () => runtime.currentCtx`) — reads are not output arguments.
+- `runtime.widget = new AgentWidget(...)` assignment — `widget` stays public.
+- `agentActivity` map usage across notification, tool, and menu deps — unchanged.
+
+## Module-Level Changes
+
+### `src/runtime.ts` (modified)
+
+- Convert `SubagentRuntime` from `export interface` to `export class` with field initializers.
+- Add `setSessionContext(pi, ctx)` and `clearSessionContext()` methods.
+- Add `setUICtx(ctx)`, `onTurnStart()`, `markFinished(id)`, `updateWidget()`, `ensureTimer()` delegation methods.
+- Add `UICtx` to the existing type import from `./ui/agent-widget.js`.
+- Keep `createSubagentRuntime()` as `() => new SubagentRuntime()` for backward compat.
+- Keep `RunConfig` interface unchanged.
+
+### `src/index.ts` (modified)
+
+- Replace `runtime.currentCtx = { pi, ctx }` with `runtime.setSessionContext(pi, ctx)` (line 126).
+- Replace `runtime.currentCtx = undefined` with `runtime.clearSessionContext()` (line 138).
+- Replace all 8 `runtime.widget!.method()` reach-throughs with `runtime.method()` delegation calls (lines 60, 61, 149, 150, 204–207).
+- No import changes needed — `runtime` is already imported via the factory.
+
+### `test/runtime.test.ts` (modified)
+
+- Add tests for `setSessionContext` / `clearSessionContext` methods.
+- Add tests for each widget delegation method using duck-typed widget stubs.
+- Add test verifying delegation methods no-op when widget is null.
+- Existing tests remain — factory defaults, field mutability, instance isolation, and widget assignment all still apply.
+
+## Test Impact Analysis
+
+### New unit tests enabled
+
+1. `test/runtime.test.ts` additions — `setSessionContext` sets `currentCtx` correctly; `clearSessionContext` resets it to `undefined`.
+2. `test/runtime.test.ts` additions — Each widget delegation method forwards to the widget's corresponding method; all delegation methods silently no-op when widget is null.
+
+### Existing tests that become redundant
+
+None.
+The existing `runtime.test.ts` tests cover factory defaults, field mutability, and instance isolation — all still valid with the class conversion.
+The "fields are independently mutable" test exercises direct field writes, which remain supported.
+
+### Existing tests that stay as-is
+
+- `test/runtime.test.ts` — All 5 existing tests pass unchanged (the class satisfies the same structural contract as the previous interface-based object).
+- `test/print-mode.test.ts` — Calls `session_shutdown` via the extension's handler map; transparent to runtime internals.
+- All other test files — No dependency on `SubagentRuntime` fields or methods.
+
+## TDD Order
+
+1. **Convert `SubagentRuntime` to a class; add session-context methods.**
+   Convert the interface to a class with field initializers matching current defaults.
+   Add `setSessionContext(pi, ctx)` and `clearSessionContext()` methods.
+   Update `createSubagentRuntime()` to return `new SubagentRuntime()`.
+   Add tests in `runtime.test.ts`: `setSessionContext` sets `currentCtx`; `clearSessionContext` resets to `undefined`; round-trip set→clear.
+   Run existing tests to verify no regressions.
+   Commit: `feat: add session-context methods to SubagentRuntime`
+
+2. **Add widget delegation methods; add tests.**
+   Add `setUICtx(ctx)`, `onTurnStart()`, `markFinished(id)`, `updateWidget()`, `ensureTimer()` methods to the class.
+   Add `UICtx` to the type import from `./ui/agent-widget.js`.
+   Add tests in `runtime.test.ts`: each delegation method forwards to the widget stub; all methods no-op when widget is null.
+   Commit: `feat: add widget delegation methods to SubagentRuntime`
+
+3. **Migrate all call sites in `index.ts` to use the new methods.**
+   Replace the 2 `currentCtx` writes with `setSessionContext` / `clearSessionContext`.
+   Replace the 8 `widget!` reach-throughs with delegation methods.
+   Run full test suite and `pnpm run check`.
+   Commit: `refactor: use SubagentRuntime methods in extension factory (#87)`
+
+## Risks and Mitigations
+
+| Risk                                                                                                  | Mitigation                                                                                                                                                                                                  |
+| ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Class conversion breaks code that constructs `SubagentRuntime` as a plain object                      | Only `createSubagentRuntime()` constructs runtime instances (in `index.ts` and tests). The factory is updated to return `new SubagentRuntime()`. No code constructs a `{ ... } as SubagentRuntime` literal. |
+| Widget delegation silently swallows errors when widget is null (changes behavior from throw to no-op) | The null path is unreachable in practice — widget is always assigned before any agent completes. The silent no-op is strictly safer than the `!` assertion. The #70 plan explicitly expects this behavior.  |
+| Adding `UICtx` import to `runtime.ts` increases coupling to the widget module                         | `runtime.ts` already imports `AgentActivity` and `AgentWidget` from the same module. `UICtx` is a lean 2-method interface, not a Pi SDK type. Coupling is minimal and consistent.                           |
+| Remaining output-argument writes (`defaultMaxTurns`, `graceTurns`) are left unaddressed               | Explicitly out of scope per the issue's acceptance criteria. Can be addressed in a follow-up if the pattern becomes painful.                                                                                |
+
+## Open Questions
+
+- Should `createSubagentRuntime()` be removed in favor of `new SubagentRuntime()` directly?
+  The factory adds no value over a no-arg constructor, but removing it widens the blast radius without benefit.
+  Defer — remove it as part of #70 or a future cleanup if it feels redundant.

package/docs/retro/0072-inject-agent-manager-collaborators.md

@@ -0,0 +1,46 @@
+---
+issue: 72
+issue_title: "refactor: dependency-inject AgentManager's collaborators"
+---
+
+# Retro: #72 — dependency-inject AgentManager's collaborators
+
+## Final Retrospective (2026-05-20T17:50:00Z)
+
+### Session summary
+
+Defined `AgentRunner` and `WorktreeManager` interfaces, converted `AgentManager`'s 6-positional-parameter constructor to an options bag with injected collaborators, migrated all 19 test sites from `vi.mock()` to `vi.fn()` stubs, and added 7 new DI-enabled tests.
+The planning phase required significant user redirection to arrive at the right abstractions; the TDD execution phase was clean with zero rework.
+Released as `pi-subagents-v5.6.0`.
+
+### Observations
+
+#### What went well
+
+- The `ask_user` interactions during planning surfaced genuine design decisions (options bag vs positional constructor, lifecycle callback grouping) that the issue body left open.
+  The user's responses were substantive and redirecting.
+- The user's "make the change that makes the change easy" framing identified #84 (`GitWorktreeManager` extraction) as a prerequisite, which made #72's implementation clean — zero type-shuffling needed.
+- The lift-and-shift test migration (Phase B → Phase C) worked exactly as planned: introduce `createManager()` helper under the old constructor, then switch it to the options bag atomically.
+  All 19 test sites migrated with no logic changes.
+- `Promise.withResolvers` (ES2024) in the new queueing test made controlled async coordination clean — no manual resolve/reject wiring.
+
+#### What caused friction (agent side)
+
+- `wrong-abstraction` — Spent ~4 analysis cycles on "how to move types between files" (`ToolActivity`, `RunOptions`, `WorktreeInfo` → `types.ts`) when the real question was "what objects want to exist?"
+  The user had to redirect three times: "are there real objects with state?", "what state IS in AgentRunner?", and "we haven't pulled all the threads."
+  Impact: added ~10 minutes of back-and-forth during planning, but ultimately produced a better design (stateful `WorktreeManager` vs stateless `AgentRunner` seam, plus #84 as prep).
+  The dependency-graph analysis itself was sound — it confirmed no circular deps — but it answered a question nobody was asking.
+
+- `premature-convergence` — First draft of the plan included `WorktreeManager` extraction as "Phase A step 1" inside #72.
+  The user asked "did we create another issue that we need to tackle first?"
+  — pointing out that the prep work should be its own issue.
+  Impact: minor rework to update the plan and file #84; no code rework since it was caught during planning. (User-caught.)
+
+#### What caused friction (user side)
+
+- The user's early redirect ("take a step back — does the AgentManager really need six params?") could have been even more direct — e.g., "before we discuss constructor shape, what higher-level abstractions are missing?"
+  That said, the Socratic approach ultimately led to a better shared understanding of why `WorktreeManager` is a real object and `AgentRunner` is a seam.
+
+### Changes made
+
+1. Retro file created at `packages/pi-subagents/docs/retro/0072-inject-agent-manager-collaborators.md`.

package/docs/retro/0084-extract-git-worktree-manager.md

@@ -0,0 +1,37 @@
+---
+issue: 84
+issue_title: "refactor: extract GitWorktreeManager class from worktree.ts free functions"
+---
+
+# Retro: #84 — extract GitWorktreeManager class from worktree.ts free functions
+
+## Final Retrospective (2026-05-20T13:31:00Z)
+
+### Session summary
+
+Extracted a `WorktreeManager` interface and `GitWorktreeManager` class from the three free functions in `worktree.ts`.
+The two-step TDD cycle (add tests → add implementation) executed cleanly with no rework or deviations from the plan.
+Released as `pi-subagents-v5.5.0`.
+
+### Observations
+
+#### What went well
+
+- The issue body included an exact "Proposed Interface" section with TypeScript code, which made the plan nearly mechanical and eliminated all design ambiguity.
+  The `ask-user` step was correctly skipped.
+- The two-step TDD cycle was appropriately minimal for a thin delegation extraction — no over-engineering of the test or commit structure.
+- The full pipeline (plan → TDD → ship → release) completed in a single pass with zero corrections.
+
+#### What caused friction (agent side)
+
+No friction observed.
+The issue was well-scoped and the existing pipeline instructions handled every step.
+
+#### What caused friction (user side)
+
+No friction observed.
+The pipeline was driven cleanly with `/plan-issue` → `/tdd-plan` → `/ship-issue`.
+
+### Changes made
+
+1. Retro file created at `packages/pi-subagents/docs/retro/0084-extract-git-worktree-manager.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "5.5.0",
+  "version": "5.7.0",
   "exports": {
     ".": "./src/service.ts"
   },

package/src/agent-manager.ts

@@ -9,12 +9,12 @@
 import { randomUUID } from "node:crypto";
 import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { resumeAgent, runAgent, type ToolActivity } from "./agent-runner.js";
+import type { AgentRunner, ToolActivity } from "./agent-runner.js";
 import { debugLog } from "./debug.js";
 import type { RunConfig } from "./runtime.js";
 import type { AgentInvocation, AgentRecord, IsolationMode, SubagentType, ThinkingLevel } from "./types.js";
 import { addUsage } from "./usage.js";
-import { cleanupWorktree, createWorktree, pruneWorktrees, } from "./worktree.js";
+import type { WorktreeManager } from "./worktree.js";
 
 export type OnAgentComplete = (record: AgentRecord) => void;
 export type OnAgentStart = (record: AgentRecord) => void;
@@ -24,6 +24,16 @@ export type CompactionInfo = { reason: "manual" | "threshold" | "overflow"; toke
 /** Default max concurrent background agents. */
 const DEFAULT_MAX_CONCURRENT = 4;
 
+export interface AgentManagerOptions {
+  runner: AgentRunner;
+  worktrees: WorktreeManager;
+  maxConcurrent?: number;
+  getRunConfig?: () => RunConfig;
+  onStart?: OnAgentStart;
+  onComplete?: OnAgentComplete;
+  onCompact?: OnAgentCompact;
+}
+
 interface SpawnArgs {
   pi: ExtensionAPI;
   ctx: ExtensionContext;
@@ -72,7 +82,8 @@ export class AgentManager {
   private onComplete?: OnAgentComplete;
   private onStart?: OnAgentStart;
   private onCompact?: OnAgentCompact;
-  private readonly cwd: string;
+  private readonly runner: AgentRunner;
+  private readonly worktrees: WorktreeManager;
   private maxConcurrent: number;
   private getRunConfig?: () => RunConfig;
 
@@ -81,20 +92,14 @@ export class AgentManager {
   /** Number of currently running background agents. */
   private runningBackground = 0;
 
-  constructor(
-    cwd: string,
-    onComplete?: OnAgentComplete,
-    maxConcurrent = DEFAULT_MAX_CONCURRENT,
-    onStart?: OnAgentStart,
-    onCompact?: OnAgentCompact,
-    getRunConfig?: () => RunConfig,
-  ) {
-    this.cwd = cwd;
-    this.onComplete = onComplete;
-    this.onStart = onStart;
-    this.onCompact = onCompact;
-    this.getRunConfig = getRunConfig;
-    this.maxConcurrent = maxConcurrent;
+  constructor(options: AgentManagerOptions) {
+    this.runner = options.runner;
+    this.worktrees = options.worktrees;
+    this.onComplete = options.onComplete;
+    this.onStart = options.onStart;
+    this.onCompact = options.onCompact;
+    this.getRunConfig = options.getRunConfig;
+    this.maxConcurrent = options.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
     // Cleanup completed agents after 10 minutes (but keep sessions for resume)
     this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
     this.cleanupInterval.unref();
@@ -164,7 +169,7 @@ export class AgentManager {
     // BEFORE state mutation so a throw doesn't leave the record half-running.
     let worktreeCwd: string | undefined;
     if (options.isolation === "worktree") {
-      const wt = createWorktree(ctx.cwd, id);
+      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. ' +
@@ -190,7 +195,7 @@ export class AgentManager {
     const detach = () => { detachParentSignal?.(); detachParentSignal = undefined; };
 
     const runConfig = this.getRunConfig?.();
-    const promise = runAgent(ctx, type, prompt, {
+    const promise = this.runner.run(ctx, type, prompt, {
       pi,
       model: options.model,
       maxTurns: options.maxTurns,
@@ -247,7 +252,7 @@ export class AgentManager {
 
         // Clean up worktree if used
         if (record.worktree) {
-          const wtResult = cleanupWorktree(ctx.cwd, record.worktree, options.description);
+          const wtResult = this.worktrees.cleanup(record.worktree, options.description);
           record.worktreeResult = wtResult;
           if (wtResult.hasChanges && wtResult.branch) {
             record.result = (record.result ?? "") +
@@ -281,7 +286,7 @@ export class AgentManager {
         // Best-effort worktree cleanup on error
         if (record.worktree) {
           try {
-            const wtResult = cleanupWorktree(ctx.cwd, record.worktree, options.description);
+            const wtResult = this.worktrees.cleanup(record.worktree, options.description);
             record.worktreeResult = wtResult;
           } catch (err) { debugLog("cleanupWorktree on agent error", err); }
         }
@@ -351,7 +356,7 @@ export class AgentManager {
     record.error = undefined;
 
     try {
-      const responseText = await resumeAgent(record.session, prompt, {
+      const responseText = await this.runner.resume(record.session, prompt, {
         onToolActivity: (activity) => {
           if (activity.type === "end") record.toolUses++;
         },
@@ -488,6 +493,6 @@ export class AgentManager {
     }
     this.agents.clear();
     // Prune any orphaned git worktrees (crash recovery)
-    try { pruneWorktrees(this.cwd); } catch (err) { debugLog("pruneWorktrees on dispose", err); }
+    try { this.worktrees.prune(); } catch (err) { debugLog("pruneWorktrees on dispose", err); }
   }
 }

package/src/agent-runner.ts

@@ -129,6 +129,23 @@ export interface RunResult {
   steered: boolean;
 }
 
+/** Options for resuming an existing agent session. */
+export interface ResumeOptions {
+  onToolActivity?: (activity: ToolActivity) => void;
+  onAssistantUsage?: (usage: { input: number; output: number; cacheWrite: number }) => void;
+  onCompaction?: (info: { reason: "manual" | "threshold" | "overflow"; tokensBefore: number }) => void;
+  signal?: AbortSignal;
+}
+
+/**
+ * Execution boundary: decouples AgentManager (lifecycle management) from the
+ * SDK session orchestration in runAgent/resumeAgent.
+ */
+export interface AgentRunner {
+  run(ctx: ExtensionContext, type: SubagentType, prompt: string, options: RunOptions): Promise<RunResult>;
+  resume(session: AgentSession, prompt: string, options?: ResumeOptions): Promise<string>;
+}
+
 /**
  * Subscribe to a session and collect the last assistant message text.
  * Returns an object with a `getText()` getter and an `unsubscribe` function.
@@ -375,19 +392,7 @@ export async function runAgent(
 export async function resumeAgent(
   session: AgentSession,
   prompt: string,
-  options: {
-    onToolActivity?: (activity: ToolActivity) => void;
-    onAssistantUsage?: (usage: {
-      input: number;
-      output: number;
-      cacheWrite: number;
-    }) => void;
-    onCompaction?: (info: {
-      reason: "manual" | "threshold" | "overflow";
-      tokensBefore: number;
-    }) => void;
-    signal?: AbortSignal;
-  } = {},
+  options: ResumeOptions = {},
 ): Promise<string> {
   const collector = collectResponseText(session);
   const cleanupAbort = forwardAbortSignal(session, options.signal);

package/src/index.ts

@@ -13,7 +13,7 @@
 import { join } from "node:path";
 import { defineTool, type ExtensionAPI, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { AgentManager } from "./agent-manager.js";
-import { getAgentConversation, normalizeMaxTurns, steerAgent } from "./agent-runner.js";
+import { getAgentConversation, normalizeMaxTurns, resumeAgent, runAgent, steerAgent } from "./agent-runner.js";
 import { getAvailableTypes, getDefaultAgentNames, getUserAgentNames, registerAgents, resolveAgentConfig, } from "./agent-types.js";
 import { loadCustomAgents } from "./custom-agents.js";
 import { type ModelRegistry, resolveModel } from "./model-resolver.js";
@@ -33,6 +33,7 @@ import {
   AgentWidget,
   type UICtx,
 } from "./ui/agent-widget.js";
+import { GitWorktreeManager } from "./worktree.js";
 
 export default function (pi: ExtensionAPI) {
   // ---- Register custom notification renderer ----
@@ -56,54 +57,60 @@ export default function (pi: ExtensionAPI) {
   const notifications = createNotificationSystem({
     sendMessage: (msg, opts) => pi.sendMessage(msg as any, opts as any),
     agentActivity: runtime.agentActivity,
-    markFinished: (id) => runtime.widget!.markFinished(id),
-    updateWidget: () => runtime.widget!.update(),
+    markFinished: (id) => runtime.markFinished(id),
+    updateWidget: () => runtime.updateWidget(),
   });
 
   // Background completion: emit lifecycle event and delegate to notification system
-  const manager = new AgentManager(process.cwd(), (record) => {
-    // Emit lifecycle event based on terminal status
-    const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
-    const eventData = buildEventData(record);
-    if (isError) {
-      pi.events.emit("subagents:failed", eventData);
-    } else {
-      pi.events.emit("subagents:completed", eventData);
-    }
+  const manager = new AgentManager({
+    runner: { run: runAgent, resume: resumeAgent },
+    worktrees: new GitWorktreeManager(process.cwd()),
+    onComplete: (record) => {
+      // Emit lifecycle event based on terminal status
+      const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
+      const eventData = buildEventData(record);
+      if (isError) {
+        pi.events.emit("subagents:failed", eventData);
+      } else {
+        pi.events.emit("subagents:completed", eventData);
+      }
 
-    // Persist final record for cross-extension history reconstruction
-    pi.appendEntry("subagents:record", {
-      id: record.id, type: record.type, description: record.description,
-      status: record.status, result: record.result, error: record.error,
-      startedAt: record.startedAt, completedAt: record.completedAt,
-    });
+      // Persist final record for cross-extension history reconstruction
+      pi.appendEntry("subagents:record", {
+        id: record.id, type: record.type, description: record.description,
+        status: record.status, result: record.result, error: record.error,
+        startedAt: record.startedAt, completedAt: record.completedAt,
+      });
 
-    // Skip notification if result was already consumed via get_subagent_result
-    if (record.resultConsumed) {
-      notifications.cleanupCompleted(record.id);
-      return;
-    }
+      // Skip notification if result was already consumed via get_subagent_result
+      if (record.resultConsumed) {
+        notifications.cleanupCompleted(record.id);
+        return;
+      }
 
-    notifications.sendCompletion(record);
-  }, undefined, (record) => {
-    // Emit started event when agent transitions to running (including from queue)
-    pi.events.emit("subagents:started", {
-      id: record.id,
-      type: record.type,
-      description: record.description,
-    });
-  }, (record, info) => {
-    // Emit compacted event when agent's session compacts (preserves count on record).
-    pi.events.emit("subagents:compacted", {
-      id: record.id,
-      type: record.type,
-      description: record.description,
-      reason: info.reason,
-      tokensBefore: info.tokensBefore,
-      compactionCount: record.compactionCount,
-    });
-  },
-  () => ({ defaultMaxTurns: runtime.defaultMaxTurns, graceTurns: runtime.graceTurns }));
+      notifications.sendCompletion(record);
+    },
+    onStart: (record) => {
+      // Emit started event when agent transitions to running (including from queue)
+      pi.events.emit("subagents:started", {
+        id: record.id,
+        type: record.type,
+        description: record.description,
+      });
+    },
+    onCompact: (record, info) => {
+      // Emit compacted event when agent's session compacts (preserves count on record).
+      pi.events.emit("subagents:compacted", {
+        id: record.id,
+        type: record.type,
+        description: record.description,
+        reason: info.reason,
+        tokensBefore: info.tokensBefore,
+        compactionCount: record.compactionCount,
+      });
+    },
+    getRunConfig: () => ({ defaultMaxTurns: runtime.defaultMaxTurns, graceTurns: runtime.graceTurns }),
+  });
 
   // Typed service published via Symbol.for() for cross-extension access.
   // Consumers: const { getSubagentsService } = await import("@gotgenes/pi-subagents");
@@ -116,7 +123,7 @@ export default function (pi: ExtensionAPI) {
   publishSubagentsService(service);
 
   pi.on("session_start", async (_event, ctx) => {
-    runtime.currentCtx = { pi, ctx };
+    runtime.setSessionContext(pi, ctx);
     manager.clearCompleted();
   });
 
@@ -128,7 +135,7 @@ export default function (pi: ExtensionAPI) {
   // If the session is going down, there's nothing left to consume agent results.
   pi.on("session_shutdown", async () => {
     unpublishSubagentsService();
-    runtime.currentCtx = undefined;
+    runtime.clearSessionContext();
     manager.abortAll();
     notifications.dispose();
     manager.dispose();
@@ -139,8 +146,8 @@ export default function (pi: ExtensionAPI) {
 
   // Grab UI context from first tool execution + clear lingering widget on new turn
   pi.on("tool_execution_start", async (_event, ctx) => {
-    runtime.widget!.setUICtx(ctx.ui as UICtx);
-    runtime.widget!.onTurnStart();
+    runtime.setUICtx(ctx.ui as UICtx);
+    runtime.onTurnStart();
   });
 
   /** Build the full type list text dynamically from the unified registry. */
@@ -194,10 +201,10 @@ export default function (pi: ExtensionAPI) {
       listAgents: () => manager.listAgents(),
     },
     widget: {
-      setUICtx: (ctx) => runtime.widget!.setUICtx(ctx as UICtx),
-      ensureTimer: () => runtime.widget!.ensureTimer(),
-      update: () => runtime.widget!.update(),
-      markFinished: (id) => runtime.widget!.markFinished(id),
+      setUICtx: (ctx) => runtime.setUICtx(ctx as UICtx),
+      ensureTimer: () => runtime.ensureTimer(),
+      update: () => runtime.updateWidget(),
+      markFinished: (id) => runtime.markFinished(id),
     },
     agentActivity: runtime.agentActivity,
     emitEvent: (name, data) => pi.events.emit(name, data),