@gotgenes/pi-subagents 7.2.0 → 7.2.2

package/docs/retro/0195-convert-tool-factories-to-classes.md

@@ -0,0 +1,42 @@
+---
+issue: 195
+issue_title: "Convert tool factories to classes"
+---
+
+# Retro: #195 — Convert tool factories to classes
+
+## Stage: Planning (2026-05-24T12:00:00Z)
+
+### Session summary
+
+Produced a 5-step TDD plan converting `createAgentTool`, `createGetResultTool`, and `createSteerTool` to classes with constructor-injected dependencies.
+Verified both prerequisites (#193, #194) are closed and their effects visible in the current source.
+Designed narrow interfaces (`AgentToolRuntime`, `GetResultToolManager`, `SteerToolManager`, `SteerToolEvents`, etc.) that `SubagentRuntime`, `AgentManager`, and `NotificationManager` satisfy structurally.
+
+### Observations
+
+- The conversion is mechanical — no behavioral changes, just structural.
+  Existing tests cover all paths; only test helpers need updating.
+- `steerAgent` and `getAgentConversation` are pure functions that can be imported directly by the classes rather than injected — simplifies the constructor signature.
+- `agentDir` doesn't fit neatly on any existing collaborator, so it remains a constructor param for `AgentTool`.
+- The `AgentToolWidget` interface may become redundant once `AgentToolRuntime` replaces it as the type passed to `spawnBackground`/`runForeground`, but this is deferred to implementation.
+- Ordered TDD steps from smallest (SteerTool) to largest (AgentTool) to build confidence incrementally.
+
+## Stage: Implementation — TDD (2026-05-24T21:26:00Z)
+
+### Session summary
+
+Completed all 5 planned TDD cycles (SteerTool → GetResultTool → AgentTool → `index.ts` wiring → architecture doc).
+All 854 tests pass; type check and lint clean.
+Total: 5 commits across source + test files, plus 1 cleanup fix commit.
+
+### Observations
+
+- `steerAgent` was inlined as `session.steer(message)` directly in `SteerTool.execute()` rather than imported as a module function.
+  This eliminated the dep entirely — the mock session's `steer` vi.fn() handles it in tests without `vi.mock`.
+- The `verbose` test in `get-result-tool.test.ts` was upgraded to drive the real `getAgentConversation` function via `createMockSession({ messages: [...] })` overrides, making it a stronger integration test.
+- `AgentToolWidget` was eliminated: `AgentToolRuntime` (a superset) replaced it, and `background-spawner` and `foreground-runner` already define their own narrow `BackgroundWidgetDeps`/`ForegroundWidgetDeps` interfaces.
+- `createToolDeps()` changed shape from `AgentToolDeps` bag to `AgentToolFixture` (`{ manager, runtime, settings, registry, agentDir }`).
+  This required updating `background-spawner.test.ts` and `foreground-runner.test.ts` (not listed in the plan) to destructure `{ manager, runtime }` instead of `{ manager, widget, agentActivity }`.
+- Biome flagged an unused `import type { AgentSession }` in `get-result-tool.ts` (left by ESLint's cast removal in step 2) — caught by `pnpm run lint` and fixed in a separate commit.
+- The `ReturnType<typeof vi.fn>` annotation on `makeNotifications()` in the get-result-tool test triggered a TypeScript error; fixed by removing the return type annotation entirely (per testing skill guidance).

package/package.json

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

package/src/index.ts

@@ -15,7 +15,6 @@ import { join } from "node:path";
 import {
   createAgentSession,
   DefaultResourceLoader,
-  defineTool,
   type ExtensionAPI,
   getAgentDir,
   SettingsManager as SdkSettingsManager,
@@ -25,7 +24,7 @@ import { AgentTypeRegistry } from "#src/config/agent-types";
 import { loadCustomAgents } from "#src/config/custom-agents";
 import { SessionLifecycleHandler, ToolStartHandler } from "#src/handlers/index";
 import { AgentManager, type AgentManagerObserver } from "#src/lifecycle/agent-manager";
-import { createAgentRunner, getAgentConversation, type RunnerIO, steerAgent } from "#src/lifecycle/agent-runner";
+import { createAgentRunner, type RunnerIO } from "#src/lifecycle/agent-runner";
 import { buildParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import { GitWorktreeManager } from "#src/lifecycle/worktree";
 import { buildEventData, type NotificationDetails, NotificationManager } from "#src/observation/notification";
@@ -40,16 +39,13 @@ import { buildAgentPrompt } from "#src/session/prompts";
 import { deriveSubagentSessionDir } from "#src/session/session-dir";
 import { preloadSkills } from "#src/session/skill-loader";
 import { SettingsManager } from "#src/settings";
-import { createAgentTool } from "#src/tools/agent-tool";
-import { createGetResultTool } from "#src/tools/get-result-tool";
+import { AgentTool } from "#src/tools/agent-tool";
+import { GetResultTool } from "#src/tools/get-result-tool";
 import { getModelLabelFromConfig } from "#src/tools/helpers";
-import { createSteerTool } from "#src/tools/steer-tool";
+import { SteerTool } from "#src/tools/steer-tool";
 import { FsAgentFileOps } from "#src/ui/agent-file-ops";
 import { createAgentsMenuHandler } from "#src/ui/agent-menu";
-import {
-  AgentWidget,
-  type UICtx,
-} from "#src/ui/agent-widget";
+import { AgentWidget } from "#src/ui/agent-widget";
 
 export default function (pi: ExtensionAPI) {
   // ---- Register custom notification renderer ----
@@ -67,7 +63,7 @@ export default function (pi: ExtensionAPI) {
     (msg, opts) => pi.sendMessage(msg, opts),
     runtime.agentActivity,
     (id) => runtime.markFinished(id),
-    () => runtime.updateWidget(),
+    () => runtime.update(),
   );
 
   // Settings: owns all three in-memory values and handles load/save/emit.
@@ -185,46 +181,15 @@ export default function (pi: ExtensionAPI) {
 
   // ---- Agent tool ----
 
-  pi.registerTool(defineTool(createAgentTool({
-    manager: {
-      spawn: (snapshot, type, prompt, opts) => manager.spawn(snapshot, type, prompt, opts),
-      spawnAndWait: (snapshot, type, prompt, opts) => manager.spawnAndWait(snapshot, type, prompt, opts),
-      resume: (id, prompt, signal) => manager.resume(id, prompt, signal),
-      getRecord: (id) => manager.getRecord(id),
-      getMaxConcurrent: () => settings.maxConcurrent,
-    },
-    widget: {
-      setUICtx: (ctx) => runtime.setUICtx(ctx as UICtx),
-      ensureTimer: () => runtime.ensureTimer(),
-      update: () => runtime.updateWidget(),
-      markFinished: (id) => runtime.markFinished(id),
-    },
-    agentActivity: runtime.agentActivity,
-    registry,
-    agentDir: getAgentDir(),
-    settings,
-    buildSnapshot: runtime.buildSnapshot.bind(runtime),
-    getModelInfo: runtime.getModelInfo.bind(runtime),
-    getSessionInfo: runtime.getSessionInfo.bind(runtime),
-  })));
+  pi.registerTool(new AgentTool(manager, runtime, settings, registry, getAgentDir()).toToolDefinition());
 
   // ---- get_subagent_result tool ----
 
-  pi.registerTool(defineTool(createGetResultTool(
-    (id) => manager.getRecord(id),
-    (key) => notifications.cancelNudge(key),
-    (session) => getAgentConversation(session),
-    registry,
-  )));
+  pi.registerTool(new GetResultTool(manager, notifications, registry).toToolDefinition());
 
   // ---- steer_subagent tool ----
 
-  pi.registerTool(defineTool(createSteerTool(
-    (id) => manager.getRecord(id),
-    (name, data) => pi.events.emit(name, data),
-    (session, message) => steerAgent(session, message),
-    (id, message) => manager.queueSteer(id, message),
-  )));
+  pi.registerTool(new SteerTool(manager, pi.events).toToolDefinition());
 
   // ---- /agents interactive menu ----
 

package/src/runtime.ts

@@ -109,7 +109,7 @@ export class SubagentRuntime {
   }
 
   /** Delegate to widget.update — no-op when widget is null. */
-  updateWidget(): void {
+  update(): void {
     this.widget?.update();
   }
 

package/src/tools/agent-tool.ts

@@ -1,5 +1,6 @@
 /* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-base-to-string, @typescript-eslint/restrict-template-expressions -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
 import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
+import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { AgentTypeRegistry } from "#src/config/agent-types";
@@ -15,72 +16,149 @@ import { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 import { type UICtx } from "#src/ui/agent-widget";
 import { type AgentDetails, getDisplayName } from "#src/ui/display";
 
-// ---- Deps interface ----
-
-/** 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;
-  getMaxConcurrent: () => number;
-}
-
-/** Narrow widget interface — only the methods the Agent tool calls. */
-export interface AgentToolWidget {
-  setUICtx: (ctx: unknown) => void;
-  ensureTimer: () => void;
-  update: () => void;
-  markFinished: (id: string) => void;
-}
+// ---- Shared interfaces (also used by background-spawner and foreground-runner) ----
 
 /**
  * Narrow read/write interface for the agent-tool's agentActivity access.
  * The full Map satisfies this structurally — no wrapper needed.
  */
 export interface AgentActivityAccess {
-  get(id: string): AgentActivityTracker | undefined;
-  set(id: string, tracker: AgentActivityTracker): void;
-  delete(id: string): void;
+	get(id: string): AgentActivityTracker | undefined;
+	set(id: string, tracker: AgentActivityTracker): void;
+	delete(id: string): void;
 }
 
-export interface AgentToolDeps {
-  manager: AgentToolManager;
-  widget: AgentToolWidget;
-  agentActivity: AgentActivityAccess;
-  registry: AgentTypeRegistry;
-  agentDir: string;
-  /** Narrow settings accessor — only the default max turns is needed here. */
-  settings: { readonly defaultMaxTurns: number | undefined };
-  /** Build a ParentSnapshot from the current session context. */
-  buildSnapshot: (inheritContext: boolean) => ParentSnapshot;
-  /** Model info from the current session context. */
-  getModelInfo: () => ModelInfo;
-  /** Parent session identity from the current session context. */
-  getSessionInfo: () => { parentSessionFile: string; parentSessionId: string };
+// ---- Deps interfaces ----
+
+/** 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;
+}
+
+/** Narrow runtime interface — the Agent tool's slice of SubagentRuntime. */
+export interface AgentToolRuntime {
+	readonly agentActivity: AgentActivityAccess;
+	setUICtx(ctx: UICtx): void;
+	ensureTimer(): void;
+	update(): void;
+	markFinished(id: string): void;
+	buildSnapshot(inheritContext: boolean): ParentSnapshot;
+	getModelInfo(): ModelInfo;
+	getSessionInfo(): { parentSessionFile: string; parentSessionId: string };
 }
 
-// ---- Factory ----
+/** Narrow settings accessor — only the fields the Agent tool reads. */
+export type AgentToolSettings = {
+	readonly defaultMaxTurns: number | undefined;
+	readonly maxConcurrent: number;
+};
+
+// ---- Class ----
+
+export class AgentTool {
+	private readonly typeListText: string;
+	private readonly availableTypesText: string;
+
+	constructor(
+		private readonly manager: AgentToolManager,
+		private readonly runtime: AgentToolRuntime,
+		private readonly settings: AgentToolSettings,
+		private readonly registry: AgentTypeRegistry,
+		private readonly agentDir: string,
+	) {
+		this.typeListText = buildTypeListText(registry, agentDir);
+		this.availableTypesText = registry.getAvailableTypes().join(", ");
+	}
+
+	async execute(
+		toolCallId: string,
+		params: Record<string, unknown>,
+		signal: AbortSignal | undefined,
+		onUpdate: ((update: AgentToolResult<any>) => void) | undefined,
+		ctx: any,
+	) {
+		// Ensure we have UI context for widget rendering
+		this.runtime.setUICtx(ctx.ui as UICtx);
 
-/** Create the Agent tool definition (without Pi SDK wrapper). */
-export function createAgentTool({
-  manager,
-  widget,
-  agentActivity,
-  registry,
-  agentDir,
-  settings,
-  buildSnapshot,
-  getModelInfo,
-  getSessionInfo,
-}: AgentToolDeps) {
-  const typeListText = buildTypeListText(registry, agentDir);
-  const availableTypesText = registry.getAvailableTypes().join(", ");
-  return {
-    name: "Agent" as const,
-    label: "Agent",
-    promptSnippet: "Agent: Launch a specialized agent for complex, multi-step tasks.",
-    description: `Launch a new agent to handle complex, multi-step tasks autonomously.
+		// Reload custom agents so new .pi/agents/*.md files are picked up without restart
+		this.registry.reload();
+
+		// ---- Config resolution (pure) ----
+		const config = resolveSpawnConfig(
+			params,
+			this.registry,
+			this.runtime.getModelInfo(),
+			this.settings,
+		);
+		if ("error" in config) return textResult(config.error);
+
+		// ---- Boundary extraction (after config so inheritContext is resolved) ----
+		const snapshot = this.runtime.buildSnapshot(config.execution.inheritContext);
+		const { parentSessionFile, parentSessionId } = this.runtime.getSessionInfo();
+		const parentSession: ParentSessionInfo = { parentSessionFile, parentSessionId, toolCallId };
+
+		// ---- Resume existing agent ----
+		if (params.resume) {
+			const existing = this.manager.getRecord(params.resume as string);
+			if (!existing) {
+				return textResult(
+					`Agent not found: "${params.resume}". It may have been cleaned up.`,
+				);
+			}
+			if (!existing.session) {
+				return textResult(
+					`Agent "${params.resume}" has no active session to resume.`,
+				);
+			}
+			const record = await this.manager.resume(
+				params.resume as string,
+				params.prompt as string,
+				signal ?? new AbortController().signal,
+			);
+			if (!record) {
+				return textResult(`Failed to resume agent "${params.resume}".`);
+			}
+			return textResult(
+				record.result?.trim() ?? record.error?.trim() ?? "No output.",
+				buildDetails(config.presentation.detailBase, record),
+			);
+		}
+
+		// ---- Background execution ----
+		if (config.execution.runInBackground) {
+			return spawnBackground(
+				this.manager,
+				this.runtime,
+				this.runtime.agentActivity,
+				{ config, snapshot, parentSession, settings: this.settings },
+			);
+		}
+
+		// ---- Foreground execution — stream progress via onUpdate ----
+		return runForeground(
+			this.manager,
+			this.runtime,
+			this.runtime.agentActivity,
+			{ config, snapshot, parentSession },
+			signal,
+			onUpdate,
+		);
+	}
+
+	toToolDefinition() {
+		const typeListText = this.typeListText;
+		const availableTypesText = this.availableTypesText;
+		const agentDir = this.agentDir;
+		const registry = this.registry;
+
+		return defineTool({
+			name: "Agent" as const,
+			label: "Agent",
+			promptSnippet: "Agent: Launch a specialized agent for complex, multi-step tasks.",
+			description: `Launch a new agent to handle complex, multi-step tasks autonomously.
 
 The Agent tool launches specialized agents that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
 
@@ -101,170 +179,102 @@ Guidelines:
 - Use thinking to control extended thinking level.
 - Use inherit_context if the agent needs the parent conversation history.
 - Use isolation: "worktree" to run the agent in an isolated git worktree (safe parallel file modifications).`,
-    parameters: Type.Object({
-      prompt: Type.String({
-        description: "The task for the agent to perform.",
-      }),
-      description: Type.String({
-        description: "A short (3-5 word) description of the task (shown in UI).",
-      }),
-      subagent_type: Type.String({
-        description: `The type of specialized agent to use. Available types: ${availableTypesText}. Custom agents from .pi/agents/<name>.md (project) or ${agentDir}/agents/<name>.md (global) are also available.`,
-      }),
-      model: Type.Optional(
-        Type.String({
-          description:
-            'Optional model override. Accepts "provider/modelId" or fuzzy name (e.g. "haiku", "sonnet"). Omit to use the agent type\'s default.',
-        }),
-      ),
-      thinking: Type.Optional(
-        Type.String({
-          description:
-            "Thinking level: off, minimal, low, medium, high, xhigh. Overrides agent default.",
-        }),
-      ),
-      max_turns: Type.Optional(
-        Type.Number({
-          description:
-            "Maximum number of agentic turns before stopping. Omit for unlimited (default).",
-          minimum: 1,
-        }),
-      ),
-      run_in_background: Type.Optional(
-        Type.Boolean({
-          description:
-            "Set to true to run in background. Returns agent ID immediately. You will be notified on completion.",
-        }),
-      ),
-      resume: Type.Optional(
-        Type.String({
-          description: "Optional agent ID to resume from. Continues from previous context.",
-        }),
-      ),
-      isolated: Type.Optional(
-        Type.Boolean({
-          description: "If true, agent gets no extension/MCP tools — only built-in tools.",
-        }),
-      ),
-      inherit_context: Type.Optional(
-        Type.Boolean({
-          description:
-            "If true, fork parent conversation into the agent. Default: false (fresh context).",
-        }),
-      ),
-      isolation: Type.Optional(
-        Type.Literal("worktree", {
-          description:
-            'Set to "worktree" to run the agent in a temporary git worktree (isolated copy of the repo). Changes are saved to a branch on completion.',
-        }),
-      ),
-    }),
-
-    // ---- Custom rendering: Claude Code style ----
-
-    renderCall(args: Record<string, unknown>, theme: any) {
-      const displayName = args.subagent_type
-        ? getDisplayName(args.subagent_type as string, registry)
-        : "Agent";
-      const desc = (args.description as string | undefined) ?? "";
-      return new Text(
-        "▸ " +
-          theme.fg("toolTitle", theme.bold(displayName)) +
-          (desc ? "  " + theme.fg("muted", desc) : ""),
-        0,
-        0,
-      );
-    },
-
-    renderResult(result: any, { expanded, isPartial }: any, theme: any) {
-      const details = result.details as AgentDetails | undefined;
-      if (!details) {
-        const text = result.content[0]?.type === "text" ? result.content[0].text : "";
-        return new Text(text, 0, 0);
-      }
-      const resultText = result.content[0]?.type === "text" ? result.content[0].text : "";
-      return new Text(
-        renderAgentResult(details, resultText, expanded, isPartial, theme),
-        0,
-        0,
-      );
-    },
-
-    // ---- Execute ----
-
-    execute: async (
-      toolCallId: string,
-      params: Record<string, unknown>,
-      signal: AbortSignal | undefined,
-      onUpdate: ((update: AgentToolResult<any>) => void) | undefined,
-      ctx: any,
-    ) => {
-      // Ensure we have UI context for widget rendering
-      widget.setUICtx(ctx.ui as UICtx);
-
-      // Reload custom agents so new .pi/agents/*.md files are picked up without restart
-      registry.reload();
-
-      // ---- Config resolution (pure) ----
-      const config = resolveSpawnConfig(
-        params,
-        registry,
-        getModelInfo(),
-        settings,
-      );
-      if ("error" in config) return textResult(config.error);
+			parameters: Type.Object({
+				prompt: Type.String({
+					description: "The task for the agent to perform.",
+				}),
+				description: Type.String({
+					description: "A short (3-5 word) description of the task (shown in UI).",
+				}),
+				subagent_type: Type.String({
+					description: `The type of specialized agent to use. Available types: ${availableTypesText}. Custom agents from .pi/agents/<name>.md (project) or ${agentDir}/agents/<name>.md (global) are also available.`,
+				}),
+				model: Type.Optional(
+					Type.String({
+						description:
+							'Optional model override. Accepts "provider/modelId" or fuzzy name (e.g. "haiku", "sonnet"). Omit to use the agent type\'s default.',
+					}),
+				),
+				thinking: Type.Optional(
+					Type.String({
+						description:
+							"Thinking level: off, minimal, low, medium, high, xhigh. Overrides agent default.",
+					}),
+				),
+				max_turns: Type.Optional(
+					Type.Number({
+						description:
+							"Maximum number of agentic turns before stopping. Omit for unlimited (default).",
+						minimum: 1,
+					}),
+				),
+				run_in_background: Type.Optional(
+					Type.Boolean({
+						description:
+							"Set to true to run in background. Returns agent ID immediately. You will be notified when it completes.",
+					}),
+				),
+				resume: Type.Optional(
+					Type.String({
+						description: "Optional agent ID to resume from. Continues from previous context.",
+					}),
+				),
+				isolated: Type.Optional(
+					Type.Boolean({
+						description: "If true, agent gets no extension/MCP tools — only built-in tools.",
+					}),
+				),
+				inherit_context: Type.Optional(
+					Type.Boolean({
+						description:
+							"If true, fork parent conversation into the agent. Default: false (fresh context).",
+					}),
+				),
+				isolation: Type.Optional(
+					Type.Literal("worktree", {
+						description:
+							'Set to "worktree" to run the agent in a temporary git worktree (isolated copy of the repo). Changes are saved to a branch on completion.',
+					}),
+				),
+			}),
 
-      // ---- Boundary extraction (after config so inheritContext is resolved) ----
-      const snapshot = buildSnapshot(config.execution.inheritContext);
-      const { parentSessionFile, parentSessionId } = getSessionInfo();
-      const parentSession: ParentSessionInfo = { parentSessionFile, parentSessionId, toolCallId };
+			// ---- Custom rendering: Claude Code style ----
 
-      // ---- Resume existing agent ----
-      if (params.resume) {
-        const existing = manager.getRecord(params.resume as string);
-        if (!existing) {
-          return textResult(
-            `Agent not found: "${params.resume}". It may have been cleaned up.`,
-          );
-        }
-        if (!existing.session) {
-          return textResult(
-            `Agent "${params.resume}" has no active session to resume.`,
-          );
-        }
-        const record = await manager.resume(
-          params.resume as string,
-          params.prompt as string,
-          signal ?? new AbortController().signal,
-        );
-        if (!record) {
-          return textResult(`Failed to resume agent "${params.resume}".`);
-        }
-        return textResult(
-          record.result?.trim() ?? record.error?.trim() ?? "No output.",
-          buildDetails(config.presentation.detailBase, record),
-        );
-      }
+			renderCall(args: Record<string, unknown>, theme: any) {
+				const displayName = args.subagent_type
+					? getDisplayName(args.subagent_type as string, registry)
+					: "Agent";
+				const desc = (args.description as string | undefined) ?? "";
+				return new Text(
+					"▸ " +
+						theme.fg("toolTitle", theme.bold(displayName)) +
+						(desc ? "  " + theme.fg("muted", desc) : ""),
+					0,
+					0,
+				);
+			},
 
-      // ---- Background execution ----
-      if (config.execution.runInBackground) {
-        return spawnBackground(
-          manager,
-          widget,
-          agentActivity,
-          { config, snapshot, parentSession },
-        );
-      }
+			renderResult(result: any, { expanded, isPartial }: any, theme: any) {
+				const details = result.details as AgentDetails | undefined;
+				if (!details) {
+					const text = result.content[0]?.type === "text" ? result.content[0].text : "";
+					return new Text(text, 0, 0);
+				}
+				const resultText = result.content[0]?.type === "text" ? result.content[0].text : "";
+				return new Text(
+					renderAgentResult(details, resultText, expanded, isPartial, theme),
+					0,
+					0,
+				);
+			},
 
-      // ---- Foreground execution — stream progress via onUpdate ----
-      return runForeground(
-        manager,
-        widget,
-        agentActivity,
-        { config, snapshot, parentSession },
-        signal,
-        onUpdate,
-      );
-    },
-  };
+			execute: (
+				toolCallId: string,
+				params: Record<string, unknown>,
+				signal: AbortSignal | undefined,
+				onUpdate: ((update: AgentToolResult<any>) => void) | undefined,
+				ctx: any,
+			) => this.execute(toolCallId, params, signal, onUpdate, ctx),
+		});
+	}
 }

package/src/tools/background-spawner.ts

@@ -11,7 +11,6 @@ import { subscribeUIObserver } from "#src/ui/ui-observer";
 export interface BackgroundManagerDeps {
   spawn(snapshot: ParentSnapshot, type: string, prompt: string, opts: AgentSpawnConfig): string;
   getRecord(id: string): AgentRecord | undefined;
-  getMaxConcurrent(): number;
 }
 
 /** Narrow widget interface for the background spawner. */
@@ -25,6 +24,7 @@ export interface BackgroundParams {
   config: ResolvedSpawnConfig;
   snapshot: ParentSnapshot;
   parentSession: ParentSessionInfo;
+  settings: { readonly maxConcurrent: number };
 }
 
 /**
@@ -77,7 +77,7 @@ export function spawnBackground(
       `Description: ${execution.description}\n` +
       (record?.outputFile ? `Output file: ${record.outputFile}\n` : "") +
       (isQueued
-        ? `Position: queued (max ${manager.getMaxConcurrent()} concurrent)\n`
+        ? `Position: queued (max ${params.settings.maxConcurrent} concurrent)\n`
         : "") +
       `\nYou will be notified when this agent completes.\n` +
       `Use get_subagent_result to retrieve full results, or steer_subagent to send it messages.\n` +