@gotgenes/pi-subagents 7.2.1 → 7.2.2

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [7.2.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.2.1...pi-subagents-v7.2.2) (2026-05-25)
+
+
+### Bug Fixes
+
+* remove unused AgentSession import and over-annotated mock return type in get-result-tool ([c3bc590](https://github.com/gotgenes/pi-packages/commit/c3bc59015e766d961422f4a7ecd23643c4cabefd))
+
+
+### Documentation
+
+* mark [#195](https://github.com/gotgenes/pi-packages/issues/195) tool factory conversions complete in architecture roadmap ([cb5562b](https://github.com/gotgenes/pi-packages/commit/cb5562b57ef613ab0c1e136c9d9712c71e831bcd))
+* plan convert tool factories to classes ([#195](https://github.com/gotgenes/pi-packages/issues/195)) ([ec916c2](https://github.com/gotgenes/pi-packages/commit/ec916c22a9d5f3453fba5784e3d2f5ecdc68740d))
+* **retro:** add planning stage notes for issue [#195](https://github.com/gotgenes/pi-packages/issues/195) ([2ca0c96](https://github.com/gotgenes/pi-packages/commit/2ca0c964f8e73b0b0247daf9834986a9344be060))
+* **retro:** add retro notes for issue [#194](https://github.com/gotgenes/pi-packages/issues/194) ([d7d973f](https://github.com/gotgenes/pi-packages/commit/d7d973f88ca48cf1a19b24bd396ef15a606a98bc))
+* **retro:** add TDD stage notes for issue [#195](https://github.com/gotgenes/pi-packages/issues/195) ([921b1f8](https://github.com/gotgenes/pi-packages/commit/921b1f8e500baf9b2fffeb140336d4561bdaebf1))
+
 ## [7.2.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.2.0...pi-subagents-v7.2.1) (2026-05-25)
 
 

package/docs/architecture/architecture.md

@@ -457,7 +457,7 @@ Bags with 10+ fields are the highest priority for decomposition.
 | `ResourceLoaderOptions`     | 10                                                     | agent-runner (SDK bridge)                         | Medium   |
 | `RunnerIO`                  | split → `EnvironmentIO` (3) + `SessionFactoryIO` (5+1) | agent-runner                                      | ✓ done   |
 | `CreateSessionOptions`      | 9                                                      | agent-runner (SDK bridge)                         | Medium   |
-| `AgentToolDeps`             | 8                                                      | agent-tool                                        | Low      |
+| `AgentToolDeps`             | 8                                                      | agent-tool                                        | ✓ done   |
 | `AgentMenuDeps`             | 8                                                      | agent-menu                                        | Low      |
 | `ConversationViewerOptions` | 8                                                      | conversation-viewer                               | Low      |
 | `AgentRecordInit`           | 8                                                      | agent-record                                      | Low      |
@@ -688,13 +688,13 @@ After this step, `AgentManager` structurally satisfies `AgentToolManager` and `S
 
 ### Layer 3: Convert closure factories to classes ([#195][195], [#196][196])
 
-With Layers 0–2 complete, each factory is a mechanical conversion:
+With Layers 0–2 complete, each factory is a mechanical conversion. ✓ Tool factories converted in [#195][195]:
 
 | Factory                          | Class                          | Constructor params                                  |
 | -------------------------------- | ------------------------------ | --------------------------------------------------- |
-| `createAgentTool({...})`         | `AgentTool`                    | `manager`, `runtime`, `settings`, `registry`        |
-| `createGetResultTool(...)`       | `GetResultTool`                | `manager`, `notifications`, `registry`              |
-| `createSteerTool(...)`           | `SteerTool`                    | `manager`, `events`                                 |
+| `createAgentTool({...})`         | `AgentTool` ✓                  | `manager`, `runtime`, `settings`, `registry`        |
+| `createGetResultTool(...)`       | `GetResultTool` ✓              | `manager`, `notifications`, `registry`              |
+| `createSteerTool(...)`           | `SteerTool` ✓                  | `manager`, `events`                                 |
 | `createAgentRunner(runnerIO)`    | `AgentRunner` (concrete class) | `io: RunnerIO`                                      |
 | `createAgentsMenuHandler({...})` | `AgentsMenuHandler`            | `manager`, `registry`, `settings`, `fileOps`, paths |
 

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

@@ -0,0 +1,264 @@
+---
+issue: 195
+issue_title: "Convert tool factories to classes"
+---
+
+# Convert tool factories to classes
+
+## Problem Statement
+
+`createAgentTool`, `createGetResultTool`, and `createSteerTool` are closure factories that capture dependencies and return tool definitions.
+This pattern hides dependencies in closures, forces `index.ts` to build narrow adapter objects at each call site, and prevents direct structural typing between real objects and tool interfaces.
+With #193 (runtime owns queries) and #194 (interfaces aligned) both complete, the conversions are mechanical.
+
+## Goals
+
+- Convert all three tool factories to classes with constructor-injected dependencies.
+- Each class exposes a `toToolDefinition()` method that wraps the tool with `defineTool()`.
+- `index.ts` passes real objects directly — no adapter closures for tool wiring.
+- Eliminate 16+ adapter closures from `index.ts`.
+
+## Non-Goals
+
+- Converting `createAgentRunner` or `createAgentsMenuHandler` — those belong to #196.
+- Simplifying `index.ts` beyond tool wiring — that's #196 Layer 4.
+- Changing tool behavior or parameters — this is a purely structural refactoring.
+
+## Background
+
+### Dependencies (both closed)
+
+- Issue #193 moved context queries (`buildSnapshot`, `getModelInfo`, `getSessionInfo`) onto `SubagentRuntime`.
+- Issue #194 aligned tool interfaces so `AgentManager` and `SubagentRuntime` structurally satisfy the narrow tool interfaces without adapters.
+
+### Existing module layout
+
+The three factory functions live in:
+
+- `src/tools/agent-tool.ts` — `createAgentTool(deps: AgentToolDeps)`
+- `src/tools/get-result-tool.ts` — `createGetResultTool(getRecord, cancelNudge, getConversation, registry)`
+- `src/tools/steer-tool.ts` — `createSteerTool(getRecord, emitEvent, steerAgent, queueSteer)`
+
+Each returns a plain object with `name`, `label`, `description`, `parameters`, `execute`, and optional render methods.
+`index.ts` wraps each in `defineTool()` at registration time.
+
+### Architecture doc reference
+
+Phase 11, Layer 3 in `docs/architecture/architecture.md` (lines 689–709).
+
+## Design Overview
+
+### Class structure
+
+Each class stores constructor-injected dependencies as instance fields and exposes:
+
+1. A `toToolDefinition()` method that calls `defineTool(this.buildToolSpec())` (or similar) — returning the Pi SDK tool registration object.
+2. Private methods that correspond to the existing function body sections.
+
+### Constructor signatures
+
+| Class           | Constructor params                                                                                                                         |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `AgentTool`     | `manager: AgentToolManager`, `runtime: AgentToolRuntime`, `settings: AgentToolSettings`, `registry: AgentTypeRegistry`, `agentDir: string` |
+| `GetResultTool` | `manager: GetResultToolManager`, `notifications: GetResultToolNotifications`, `registry: AgentConfigLookup`                                |
+| `SteerTool`     | `manager: SteerToolManager`, `events: SteerToolEvents`                                                                                     |
+
+### Narrow interfaces
+
+Each class defines its own narrow interface for the collaborators it uses.
+These already exist (e.g., `AgentToolManager`, `BackgroundManagerDeps`) — they stay as-is; the class uses them directly.
+
+#### `AgentTool`
+
+The existing `AgentToolDeps` interface (8 fields) collapses into 5 constructor params.
+The `widget`, `agentActivity`, `buildSnapshot`, `getModelInfo`, and `getSessionInfo` fields merge into a single `runtime` param because `SubagentRuntime` structurally satisfies all of them after #193/#194.
+
+New narrow interface for the runtime slice:
+
+```typescript
+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 };
+}
+```
+
+`SubagentRuntime` satisfies this structurally — no adapter needed in `index.ts`.
+
+#### `GetResultTool`
+
+New narrow interfaces:
+
+```typescript
+export interface GetResultToolManager {
+  getRecord(id: string): AgentRecord | undefined;
+}
+
+export interface GetResultToolNotifications {
+  cancelNudge(key: string): void;
+}
+```
+
+`getAgentConversation` is a pure function — imported directly by the class, not injected.
+
+#### `SteerTool`
+
+New narrow interfaces:
+
+```typescript
+export interface SteerToolManager {
+  getRecord(id: string): AgentRecord | undefined;
+  queueSteer(id: string, message: string): boolean;
+}
+
+export interface SteerToolEvents {
+  emit(name: string, data: unknown): void;
+}
+```
+
+`steerAgent` is a pure function — imported directly by the class, not injected.
+
+### Call site after conversion
+
+```typescript
+const agentTool = new AgentTool(manager, runtime, settings, registry, getAgentDir());
+const getResultTool = new GetResultTool(manager, notifications, registry);
+const steerTool = new SteerTool(manager, pi.events);
+pi.registerTool(agentTool.toToolDefinition());
+pi.registerTool(getResultTool.toToolDefinition());
+pi.registerTool(steerTool.toToolDefinition());
+```
+
+### Design decisions
+
+1. **`toToolDefinition()` on each class** — encapsulates the `defineTool()` call so `index.ts` doesn't import `defineTool` for each tool.
+2. **Pure functions imported directly** — `steerAgent` and `getAgentConversation` are pure utilities with no state; injecting them adds indirection without testability benefit.
+3. **`agentDir` stays a constructor param** — it's a static string computed once at startup; putting it on the registry would add scope responsibility the registry doesn't need.
+4. **Keep existing `AgentToolDeps` temporarily** — remove it in the same PR once the class replaces all usage.
+
+## Module-Level Changes
+
+### `src/tools/agent-tool.ts`
+
+- Add `AgentToolRuntime` interface (narrow runtime slice).
+- Add `AgentToolSettings` type alias (existing inline type, extracted for clarity).
+- Add `AgentTool` class with constructor storing `manager`, `runtime`, `settings`, `registry`, `agentDir`.
+- Move the existing factory body into class methods: `toToolDefinition()`, private `execute()`.
+- Remove `createAgentTool` function and `AgentToolDeps` interface.
+- Keep `AgentToolManager`, `AgentToolWidget`, `AgentActivityAccess` interfaces (still used by `background-spawner` and `foreground-runner` — though `AgentToolWidget` may be replaceable by `AgentToolRuntime`).
+
+### `src/tools/get-result-tool.ts`
+
+- Add `GetResultToolManager` and `GetResultToolNotifications` interfaces.
+- Add `GetResultTool` class with constructor.
+- Import `getAgentConversation` directly.
+- Move factory body into class method.
+- Remove `createGetResultTool` function.
+
+### `src/tools/steer-tool.ts`
+
+- Add `SteerToolManager` and `SteerToolEvents` interfaces.
+- Add `SteerTool` class with constructor.
+- Import `steerAgent` directly.
+- Move factory body into class method.
+- Remove `createSteerTool` function.
+
+### `src/tools/background-spawner.ts`
+
+- Update `BackgroundWidgetDeps` to reference `AgentToolRuntime` instead (or keep as-is since `AgentToolRuntime` is a superset).
+  Actually no change needed — `spawnBackground` already accepts narrow interfaces; the `AgentTool` class passes `this.runtime` which satisfies `BackgroundWidgetDeps` structurally.
+
+### `src/tools/foreground-runner.ts`
+
+- Same as above — no change needed.
+  The `AgentTool` class passes `this.runtime` which satisfies `ForegroundWidgetDeps` structurally.
+
+### `src/index.ts`
+
+- Remove adapter closures for all three tool registrations.
+- Replace with class construction + `toToolDefinition()` calls.
+- Remove `defineTool` import (moves into tool classes).
+- Remove unused imports that were only needed for adapter closures.
+
+### `test/tools/agent-tool.test.ts`
+
+- Replace `createToolDeps()` with class construction in test helpers.
+- Update `execute()` helper to instantiate `AgentTool` and call its execute.
+- Keep all existing test cases — behavior is unchanged.
+
+### `test/tools/get-result-tool.test.ts`
+
+- Replace positional args with class construction.
+- Update `makeDeps` and `execute` helpers.
+- Keep all existing test cases.
+
+### `test/tools/steer-tool.test.ts`
+
+- Replace positional args with class construction.
+- Update `makeDeps` and `execute` helpers.
+- Keep all existing test cases.
+
+### `test/helpers/make-deps.ts`
+
+- Update `createToolDeps` to construct `AgentTool`-compatible deps (or remove if no longer needed).
+  Likely transforms into a factory that builds mock `AgentToolRuntime`, `AgentToolManager`, etc.
+
+### `docs/architecture/architecture.md`
+
+- Update the Layer 3 table to mark #195 as done.
+- Update the file listing for `src/tools/` to reflect class names (if the listing is that detailed).
+
+## Test Impact Analysis
+
+1. **No new test surfaces** — this is a structural refactoring with identical behavior.
+   Existing tests already cover all tool paths.
+2. **Test helper changes** — `createToolDeps()` and per-tool `makeDeps()` functions need updating to use class construction instead of function calls, but the mock shapes remain the same.
+3. **All existing tests stay** — they exercise the tool execution logic which doesn't change.
+
+## TDD Order
+
+1. **Convert `SteerTool` to class** — smallest tool (fewest deps, no render methods).
+   - Update `steer-tool.ts`: add interfaces, add class, remove factory.
+   - Update `test/tools/steer-tool.test.ts`: use class construction.
+   - Verify: `pnpm vitest run test/tools/steer-tool.test.ts`
+   - Commit: `refactor: convert createSteerTool to SteerTool class (#195)`
+
+2. **Convert `GetResultTool` to class** — medium complexity (3 deps, no render methods).
+   - Update `get-result-tool.ts`: add interfaces, add class, import `getAgentConversation`, remove factory.
+   - Update `test/tools/get-result-tool.test.ts`: use class construction.
+   - Verify: `pnpm vitest run test/tools/get-result-tool.test.ts`
+   - Commit: `refactor: convert createGetResultTool to GetResultTool class (#195)`
+
+3. **Convert `AgentTool` to class** — largest (5 deps, render methods, delegates to spawner/runner).
+   - Add `AgentToolRuntime` and `AgentToolSettings` interfaces.
+   - Add `AgentTool` class.
+   - Remove `createAgentTool` and `AgentToolDeps`.
+   - Update `test/tools/agent-tool.test.ts` and `test/helpers/make-deps.ts`.
+   - Verify: `pnpm vitest run test/tools/agent-tool.test.ts`
+   - Commit: `refactor: convert createAgentTool to AgentTool class (#195)`
+
+4. **Update `index.ts`** — wire class constructors, remove adapter closures and `defineTool` import.
+   - Verify: `pnpm vitest run` (full suite) + `pnpm run check` (type-check).
+   - Commit: `refactor: wire tool classes in index.ts, remove adapter closures (#195)`
+
+5. **Update architecture doc** — mark Layer 3 (partial) as complete.
+   - Commit: `docs: mark #195 complete in architecture roadmap`
+
+## Risks and Mitigations
+
+| Risk                                                                                                      | Mitigation                                                                                    |
+| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `background-spawner` and `foreground-runner` accept narrow interfaces that differ from `AgentToolRuntime` | `AgentToolRuntime` is a superset — pass `this.runtime` and structural typing handles it.      |
+| Test factories import `AgentToolDeps` which will be removed                                               | Step 3 updates all test imports in the same commit.                                           |
+| `defineTool` import removed from `index.ts` — must live somewhere                                         | Each class's `toToolDefinition()` imports it internally.                                      |
+| Spreading class instances in tests breaks method access                                                   | Tests will construct the class, not spread it. Step 3 uses lift-and-shift for `make-deps.ts`. |
+
+## Open Questions
+
+- Should `AgentToolWidget` interface be removed entirely (replaced by `AgentToolRuntime`)?
+  Defer to implementation — if `background-spawner` and `foreground-runner` can accept `AgentToolRuntime` directly, remove it; otherwise keep the narrow subset interfaces.

package/docs/retro/0194-align-tool-interfaces-for-structural-typing.md

@@ -34,3 +34,29 @@ The `pnpm run check` type-gate caught a previously-unnoticed `test/helpers/make-
 - The `NotificationManager` constructor takes `updateWidget` as a positional callback parameter name — this does NOT need renaming (it's not a structural interface member).
 - The rename from `updateWidget` → `update` is safe because the `WidgetLike` interface in `runtime.ts` already uses `update()` — no naming conflict within the class.
 - All three changes are independent of each other and could be committed in any order, but the plan sequences them for clean `pnpm run check` passes at each step.
+
+## Stage: Final Retrospective (2026-05-24T21:15:00Z)
+
+### Session summary
+
+Planning, TDD implementation, and shipping completed in one continuous session.
+Released as `pi-subagents-v7.2.1` with zero rework or deviations from the plan.
+
+### Observations
+
+#### What went well
+
+- Clean execution end-to-end: 3 refactor commits + 1 docs commit, all planned in advance.
+- The `pnpm run check` gate after step 2 caught `test/helpers/make-deps.test.ts` — a file the plan didn't list — preventing a broken intermediate state.
+  This validates the "run type-check after each step" pattern for interface-alignment work.
+- Phased architecture approach paid off: Layers 0 and 1 being done made Layer 2 entirely mechanical.
+
+#### What caused friction (agent side)
+
+- None identified.
+  The issue scope was tight, the plan was unambiguous, and no rabbit-holes arose.
+
+#### What caused friction (user side)
+
+- None identified.
+  The issue body and architecture doc provided complete context with no ambiguity.

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.1",
+  "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 ----
@@ -185,45 +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),
-    },
-    widget: {
-      setUICtx: (ctx) => runtime.setUICtx(ctx as UICtx),
-      ensureTimer: () => runtime.ensureTimer(),
-      update: () => runtime.update(),
-      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 ----