@emiliosp/pi-maestro 0.17.0 → 0.18.0

package/TECH_STACK.md

@@ -7,8 +7,7 @@
 | ------------------------------ | ------------------------------------------------------------------------------------------------- |
 | TypeScript                     | Application code and static type checks with `tsc --noEmit`.                                      |
 | Node.js                        | Runtime.                                                                                          |
-| Pi                             | Extension host, agent APIs, and terminal interface.                                               |
-| `pi-subagents`                 | `Builder`, `verifier`, and `simplifier` execution and activity tracking.                          |
+| Pi                             | Extension host, SDK child sessions, native session persistence, and terminal interface.           |
 | TypeBox                        | Schemas and runtime validation for configuration, workflow state, tool inputs, and agent reports. |
 | Vitest with coverage           | Unit tests, integration tests, and code coverage.                                                 |
 | Oxfmt                          | Formatting                                                                                        |

package/agents/builder.md

@@ -1,14 +1,3 @@
----
-name: builder
-package: maestro
-description: Implements an owner-approved Maestro specification.
-systemPromptMode: replace
-inheritProjectContext: true
-inheritGlobalContext: true
-inheritSkills: true
-subagentOnlyExtensions: ../extensions/maestro-subagent.ts
----
-
 # Builder
 
 Implement the approved spec and produce one saved result for this pass. Work in the project directory supplied by Maestro. The owner decides requirements, scope, spec

package/agents/simplifier.md

@@ -1,14 +1,3 @@
----
-name: simplifier
-package: maestro
-description: Refactors accepted Maestro code for clarity without changing behavior.
-systemPromptMode: replace
-inheritProjectContext: true
-inheritGlobalContext: true
-inheritSkills: true
-subagentOnlyExtensions: ../extensions/maestro-subagent.ts
----
-
 # Simplifier
 
 Refactor accepted code for clarity. Work only in the canonical project directory supplied by Maestro. Communicate with Maestro, never directly with the owner. Do not

package/agents/verifier.md

@@ -1,14 +1,3 @@
----
-name: verifier
-package: maestro
-description: Independently verifies a Maestro candidate against its specification.
-systemPromptMode: replace
-inheritProjectContext: true
-inheritGlobalContext: true
-inheritSkills: true
-subagentOnlyExtensions: ../extensions/maestro-subagent.ts
----
-
 # Verifier
 
 Independently verify the supplied candidate against the approved spec and record evidence and findings. Work in the project directory supplied by Maestro. Check its live

package/docs/configuration.md

@@ -52,7 +52,7 @@ For example, if Pi starts in `/work/app/src`, `Maestro` reads `/work/app/src/.pi
 | `simplifier.thinking` |                        No | `high`                      | One supported thinking level.                            |
 
 Model values use the full `provider/model` identifier supplied by Pi's model registry, such as `openrouter/~openai/gpt-mini-latest`. Model IDs may contain additional
-slashes. `Maestro` does not apply a separate format rule; it matches the complete identifier against Pi's available models and passes it unchanged through `pi-subagents`.
+slashes. `Maestro` does not apply a separate format rule; it matches the complete identifier against Pi's available models and uses it unchanged for SDK execution.
 
 `Maestro` accepts these thinking levels:
 
@@ -97,8 +97,8 @@ used for implementation in another workflow. With `builder` enabled, `verifier`
 | `true`             | `false`             | `true`                | `Builder`, then `simplifier`   |
 | `true`             | `true`              | `true`                | All three, in order            |
 
-Disabled phases do not require agent or model availability and produce no `handoff`. The final summary identifies skipped work rather than claiming it was performed.
-Enabled simplification can still be skipped if Git is unavailable.
+Disabled phases do not require model availability and produce no `handoff`. The final summary identifies skipped work rather than claiming it was performed. Enabled
+simplification can still be skipped if Git is unavailable.
 
 ## Schema version
 
@@ -117,12 +117,11 @@ For example, `specDirectory: "planning/specs"` places `specs` in `<project-root>
 
 ## Model access
 
-During activation, `Maestro` checks only enabled agents and their configured models against `context.modelRegistry.getAvailable()`. Pi's registry is the source of truth
-for model availability; `Maestro` does not maintain a separate model list or authentication check. A missing enabled model stops activation and identifies the full
-configured identifier.
+During activation, `Maestro` checks the configured models for enabled agents against Pi's available model registry. Pi's registry is the source of truth for model
+availability; `Maestro` does not maintain a separate model list or authentication check. A missing enabled model stops activation and identifies the full configured
+identifier.
 
-With `builder` disabled, activation checks only project trust and configuration, with no agent checks, model lookup, or `pi-subagents` ping. With `builder` enabled, the
-availability ping remains required.
+With `builder` disabled, activation checks only project trust and configuration, without a model lookup.
 
-The `owner` can correct the identifier or authenticate the provider in Pi, then retry `/maestro`. Authentication or provider errors during delegation still appear as
-`run` failures. Agent names and context are described in [Subagent integration](subagent-integration.md#roles-and-context).
+The `owner` can correct the identifier or authenticate the provider in Pi, then retry `/maestro`. Authentication or provider errors during execution still appear as `run`
+failures. Agent context are described in [Subagent integration](subagent-integration.md#roles-and-context).

package/docs/subagent-integration.md

@@ -1,45 +1,46 @@
 # Subagent integration
 
-`Maestro` uses `pi-subagents` to run the `builder`, `verifier`, and `simplifier` as child sessions. A child session is a separate Pi session for one role. The `owner`
-stays in the main `Maestro` conversation.
+`Maestro` runs the `builder`, `verifier`, and `simplifier` through Pi's SDK. Each child session handles one role while the `owner` stays in the main `Maestro`
+conversation.
 
 ## Roles and context
 
-The package supplies all three roles and the tools that save their results:
+The package supplies the three roles:
 
-| Role         | Agent name           | Definition                                        |
-| ------------ | -------------------- | ------------------------------------------------- |
-| `Builder`    | `maestro.builder`    | [`agents/builder.md`](../agents/builder.md)       |
-| `Verifier`   | `maestro.verifier`   | [`agents/verifier.md`](../agents/verifier.md)     |
-| `Simplifier` | `maestro.simplifier` | [`agents/simplifier.md`](../agents/simplifier.md) |
+| Role         | Instructions                                      |
+| ------------ | ------------------------------------------------- |
+| `Builder`    | [`agents/builder.md`](../agents/builder.md)       |
+| `Verifier`   | [`agents/verifier.md`](../agents/verifier.md)     |
+| `Simplifier` | [`agents/simplifier.md`](../agents/simplifier.md) |
 
-Each `run` starts with a fresh conversation, not the main session's conversation history. All three agents inherit project instructions, the owner's global `AGENTS.md`,
-and available skills. The global file normally lives at `~/.pi/agent/AGENTS.md`.
+Each `run` starts a fresh conversation, without the main session's history or automatic resumption of earlier child sessions. The bundled role instructions supplement
+Pi's normal instructions. Global and project instructions, including `AGENTS.md`, and available skills are discovered through Pi. Models and thinking levels come from
+[Maestro configuration](configuration.md).
 
-`Maestro` supplies the `spec` ID, project directory, model, and thinking level. The agents read all approved documents (`proposal.md`, `spec.md`, and `design.md` when
-present) and saved `artifacts` to understand the work. Earlier `artifacts` provide context, not proof.
+Enabled global and project extensions load in child sessions. Native Pi tools and configured MCP, codemode, and tool search support are available.
 
-The `owner` does not call agent tools directly. `Maestro` starts the enabled `builder` after `GREEN FLAG` approval. The enabled `verifier` starts after successful
-`builder` completion. The enabled `simplifier` follows the selected preceding phases. Disabled agents are not delegated. See
-[Phase selection](configuration.md#phase-selection).
+The `owner` approves the `spec` and selected phases through the main conversation. See [Phase selection](configuration.md#phase-selection).
 
 ## Following a run
 
-`Runs` stay in the foreground and occur one at a time. Pi waits for each `run` to finish before `Maestro` continues. `Maestro` does not run agents in parallel or in the
-background.
+`Runs` stay in the foreground and occur one at a time. Pi waits for each `run` to finish before `Maestro` continues. Maestro's Pi status shows the workflow phase.
 
-Maestro's Pi status shows the workflow phase. `pi-subagents` FleetView shows agent activity, and `/subagents-fleet` opens its inspector for details and transcripts.
+Saved `handoffs` contain the structured results. See [Stored artifacts](workflow.md#stored-artifacts) for further details.
 
-Each child saves its result through `Maestro` tools before returning. `Builder` results produce `B1.json`, `B2.json`, and so on. `Verifier` results produce `V1.json`,
-`V2.json`, and so on. The `simplifier` saves the unnumbered `handoffs/simplifier/S.json`. See [Stored artifacts](workflow.md#stored-artifacts) for the creation sequence.
+## Cancellation and errors
 
-If a `run` fails or returns without a valid saved result, `Maestro` reports the error and stops. Manual follow-up is described in [Limitations](workflow.md#limitations).
+The `owner` can interrupt a running agent with Pi's cancel action (`Escape` by default). `Maestro` forwards cancellation to the child and waits for cleanup.
 
-## External configuration
+Execution errors, interruptions, and missing or invalid `handoffs` stop the workflow. Completed file changes remain.
 
-The `pi-subagents` extension must be installed and enabled in Pi when `builder` is enabled. Workflows with only an approved `spec` need no agent availability or ping.
-`Builder`, `verifier`, and `simplifier` model choices and thinking levels come from [Maestro configuration](configuration.md). `Maestro` does not supply a per-agent
-deadline. Other `pi-subagents` configuration remains the owner's responsibility.
+## Inspecting saved sessions
 
-Only `maestro_run_simplifier` checks Git readiness, with `git rev-parse --is-inside-work-tree`. If readiness cannot be confirmed, it warns and completes without
-delegation. The `simplifier` uses Git to select all uncommitted code changes. `Maestro` does not change the Git index or create commits or checkpoints.
+When a native child session file exists, `Maestro` displays its exact path on completion or failure, including interruptions and invalid `handoffs`. No path is displayed
+when execution fails before a session file is saved.
+
+Child session files live under `subagents/` in Pi's project session directory, outside the project repository. The `owner` can read the displayed JSONL file directly or
+export it with Pi:
+
+```bash
+pi --export /sessions/weather/subagents/child.jsonl conversation.html
+```

package/docs/workflow.md

@@ -31,7 +31,8 @@ issues.
 
 Maestro's Pi status shows the current phase.
 
-`pi-subagents` FleetView and `/subagents-fleet` show live agent activity and transcripts.
+`Maestro` displays the saved native child session path when one exists, including after a failed or interrupted `run`. The `owner` can inspect the file or export it with
+Pi. See [Inspecting saved sessions](subagent-integration.md#inspecting-saved-sessions).
 
 Saved `handoffs` provide a structured account of each reported `run`. The `builder` reports its outcome, `probe` results, notes, and any `escalation` questions. The
 `verifier` reports its independent checks, results, and `findings`. The `simplifier` reports its refactoring separately. Recorded `owner` decisions explain how questions
@@ -359,9 +360,12 @@ these project-specific checks.
 
 ### No automatic rollback
 
-Launch errors, delegation failures, timeouts, interruptions, cancellations, and missing or invalid `handoffs` stop the workflow without a recovery transition. If a `run`
-saves no completed transition, its saved running phase remains unchanged. Partial protocol writes require manual `owner` follow-up. `Maestro` provides no automatic
-rollback, repair, or recovery for these errors. The files that remain are available for `owner` inspection.
+The `owner` can stop a running agent through Pi's cancel action (`Escape` by default). There is no automatic `Maestro` execution deadline. Cancellation does not request a
+final agent turn or create a synthetic `handoff`.
+
+Launch errors, execution failures, interruptions, cancellations, and missing or invalid `handoffs` stop the workflow without a recovery transition. If a `run` saves no
+completed transition, its saved running phase remains unchanged. Partial protocol writes require manual `owner` follow-up. `Maestro` provides no automatic rollback,
+repair, or recovery for these errors. The files that remain are available for `owner` inspection.
 
 ### No reconciliation
 

package/extensions/maestro.ts

@@ -85,7 +85,7 @@ export default (pi: ExtensionAPI): void => {
       }
 
       try {
-        await assertEnvironment({ context, piEventsBus: pi.events });
+        await assertEnvironment({ context });
         const config = await loadConfiguration(context.cwd);
         const isImplementationEnabled = config.builder.required;
 

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@emiliosp/pi-maestro",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "A spec-driven multiagent development workflow for Pi.",
   "keywords": [
     "orchestration",
     "pi",
     "pi-coding-agent",
     "pi-package",
+    "sdd",
     "subagents",
     "workflow"
   ],
@@ -62,43 +63,34 @@
     "fmt": "oxfmt",
     "lint": "oxlint --fix"
   },
-  "dependencies": {
-    "pi-subagents": "0.78.0"
-  },
   "devDependencies": {
     "@earendil-works/pi-ai": "1.5.0",
     "@earendil-works/pi-tui": "1.5.0",
     "@types/node": "26.6.4",
-    "@vitest/coverage-v8": "5.0.3",
+    "@vitest/coverage-v8": "5.0.5",
     "oxfmt": "0.73.0",
     "oxlint": "1.87.0",
     "oxlint-anti-slop": "0.3.8",
     "typebox": "1.3.35",
     "typescript": "7.0.2",
-    "vitest": "5.0.3"
+    "vitest": "5.0.5"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "typebox": "*"
   },
-  "bundleDependencies": [
-    "pi-subagents"
-  ],
   "engines": {
     "node": ">=26.0.0"
   },
   "allowScripts": {
-    "fsevents@2.3.3": true
+    "fsevents@2.3.3": true,
+    "@google/genai": false,
+    "protobufjs": false
   },
   "pi": {
     "extensions": [
       "./extensions/maestro.ts"
-    ],
-    "subagents": {
-      "agents": [
-        "./agents"
-      ]
-    }
+    ]
   }
 }

package/src/config/schema.ts

@@ -5,12 +5,6 @@
 
 import { type Static, Type } from 'typebox';
 
-export const AGENTS = {
-  BUILDER: 'maestro.builder',
-  VERIFIER: 'maestro.verifier',
-  SIMPLIFIER: 'maestro.simplifier',
-} as const;
-
 export const THINKING_LEVELS = {
   OFF: 'off',
   MINIMAL: 'minimal',

package/src/delegation/{SubSession.ts → SubSessionManager.ts}

@@ -17,7 +17,7 @@ import {
 
 import { createChildServices } from '#src/delegation/createChildServices.ts';
 
-export type SubSessionInput = {
+export type SubSessionManagerInput = {
   roleGuidance: string;
   cwd: string;
   model: string;
@@ -26,14 +26,14 @@ export type SubSessionInput = {
   signal?: AbortSignal;
 };
 
-export class SubSession {
+export class SubSessionManager {
   private session?: AgentSession;
   private sessionManager?: SessionManager;
   private abortPromise?: Promise<void>;
 
-  private readonly input: SubSessionInput;
+  private readonly input: SubSessionManagerInput;
 
-  constructor(input: SubSessionInput) {
+  constructor(input: SubSessionManagerInput) {
     this.input = input;
   }
 
@@ -69,7 +69,7 @@ export class SubSession {
       sessionManager: this.sessionManager,
       model,
       thinkingLevel: this.input.thinkingLevel,
-      customTools: this.input.additionalTools,
+      customTools: this.input.additionalTools, // here child tool registration happens through SDK
     });
 
     this.session = session;

package/src/delegation/executeTask.ts

@@ -4,10 +4,13 @@
  */
 
 import { readTaskResult } from '#src/delegation/readTaskResult.ts';
-import { SubSession, type SubSessionInput } from '#src/delegation/SubSession.ts';
+import {
+  SubSessionManager,
+  type SubSessionManagerInput,
+} from '#src/delegation/SubSessionManager.ts';
 import { TaskExecutionError } from '#src/delegation/TaskExecutionError.ts';
 
-export type ExecuteTaskInput = SubSessionInput & {
+export type ExecuteTaskInput = SubSessionManagerInput & {
   prompt: string;
 };
 
@@ -16,23 +19,38 @@ export type TaskExecutionResult = {
   sessionFile?: string;
 };
 
-export const executeTask = async (input: ExecuteTaskInput): Promise<TaskExecutionResult> => {
-  const subSession = new SubSession(input);
+export const executeTask = async ({
+  prompt,
+  roleGuidance,
+  cwd,
+  model,
+  thinkingLevel,
+  additionalTools,
+  signal,
+}: ExecuteTaskInput): Promise<TaskExecutionResult> => {
+  const subSessionManager = new SubSessionManager({
+    roleGuidance,
+    cwd,
+    model,
+    thinkingLevel,
+    additionalTools,
+    signal,
+  });
 
   try {
     try {
-      const session = await subSession.open();
-      await session.prompt(input.prompt, { expandPromptTemplates: false });
+      const session = await subSessionManager.open();
+      await session.prompt(prompt, { expandPromptTemplates: false });
 
       const text = readTaskResult(
         session.messages.findLast((message) => message.role === 'assistant'),
       );
 
-      return { text, sessionFile: subSession.getSavedFile() };
+      return { text, sessionFile: subSessionManager.getSavedFile() };
     } finally {
-      await subSession.close();
+      await subSessionManager.close();
     }
   } catch (cause) {
-    throw new TaskExecutionError({ cause, sessionFile: subSession.getSavedFile() });
+    throw new TaskExecutionError({ cause, sessionFile: subSessionManager.getSavedFile() });
   }
 };

package/src/maestro/checks/assertEnvironment.ts

@@ -3,23 +3,11 @@
  * Used: When the owner activates Maestro mode.
  */
 
-import { randomUUID } from 'node:crypto';
 import { realpath } from 'node:fs/promises';
 
-import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
-import { resolveSubagentLaunchContract } from 'pi-subagents/preflight';
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
 
 import { loadConfiguration } from '#config/loadConfiguration.ts';
-import { AGENTS } from '#config/schema.ts';
-
-export const SUBAGENT_PING = {
-  REQUEST_EVENT: 'subagents:rpc:v1:request',
-  REPLY_EVENT_PREFIX: 'subagents:rpc:v1:reply:',
-  VERSION: 1,
-  METHOD: 'ping',
-  TIMEOUT_MS: 2000,
-  INSTALLATION_ERROR: 'Maestro flow requires pi-subagents installed in the Pi environment.',
-} as const;
 
 const getErrorMessage = (error: unknown): string =>
   error instanceof Error ? error.message : String(error);
@@ -63,114 +51,19 @@ function assertModelsAvailable({ context, models }: AssertModelsAvailableInput):
   }
 }
 
-type AssertAgentsAvailableInput = {
-  projectRoot: string;
-  agents: string[];
-};
-
-async function assertAgentsAvailable({
-  projectRoot,
-  agents,
-}: AssertAgentsAvailableInput): Promise<void> {
-  for (const agent of agents) {
-    const result = await resolveSubagentLaunchContract({
-      agent,
-      cwd: projectRoot,
-      context: 'fresh',
-    });
-
-    if (!result.ok) {
-      throw new Error(result.message);
-    }
-  }
-}
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null && !Array.isArray(value);
-
-const isReplyWithRequestId = (
-  reply: unknown,
-): reply is Record<string, unknown> & { requestId: string } =>
-  isRecord(reply) && typeof reply.requestId === 'string';
-
-function assertSuccessfulPingReply(reply: unknown): void {
-  if (
-    !isReplyWithRequestId(reply) ||
-    reply.version !== SUBAGENT_PING.VERSION ||
-    reply.method !== SUBAGENT_PING.METHOD ||
-    reply.success !== true ||
-    !isRecord(reply.data) ||
-    reply.data.version !== SUBAGENT_PING.VERSION
-  ) {
-    throw new Error('Unsuccessful or invalid pi-subagents ping reply.');
-  }
-}
-
-async function assertSubagentsRespond(piEventsBus: ExtensionAPI['events']): Promise<void> {
-  const requestId = randomUUID();
-  const { promise, resolve, reject } = Promise.withResolvers<unknown>();
-
-  const unsubscribe = piEventsBus.on(`${SUBAGENT_PING.REPLY_EVENT_PREFIX}${requestId}`, (reply) => {
-    if (isReplyWithRequestId(reply) && reply.requestId !== requestId) {
-      return;
-    }
-
-    resolve(reply);
-  });
-
-  const timeout = setTimeout(
-    () => reject(new Error('Pi-subagents ping timed out after 2000 ms.')),
-    SUBAGENT_PING.TIMEOUT_MS,
-  );
-
-  try {
-    piEventsBus.emit(SUBAGENT_PING.REQUEST_EVENT, {
-      version: SUBAGENT_PING.VERSION,
-      requestId,
-      method: SUBAGENT_PING.METHOD,
-    });
-    assertSuccessfulPingReply(await promise);
-  } finally {
-    clearTimeout(timeout);
-    unsubscribe();
-  }
-}
-
 type AssertEnvironmentInput = {
   context: ExtensionContext;
-  piEventsBus: ExtensionAPI['events'];
 };
 
-export async function assertEnvironment({
-  context,
-  piEventsBus,
-}: AssertEnvironmentInput): Promise<void> {
+export async function assertEnvironment({ context }: AssertEnvironmentInput): Promise<void> {
   const projectRoot = await getProjectRoot(context);
   const config = await getActivationConfiguration(projectRoot);
 
   if (!config.builder.required) return;
 
-  const enabledAgents = [
-    { agent: AGENTS.BUILDER, settings: config.builder },
-    { agent: AGENTS.VERIFIER, settings: config.verifier },
-    { agent: AGENTS.SIMPLIFIER, settings: config.simplifier },
-  ].filter(({ settings }) => settings.required);
-
-  try {
-    await assertAgentsAvailable({ projectRoot, agents: enabledAgents.map(({ agent }) => agent) });
-  } catch (error) {
-    throw new Error(
-      `Builder, verifier, or simplifier agent check failed: ${getErrorMessage(error)}`,
-    );
-  }
-
-  assertModelsAvailable({ context, models: enabledAgents.map(({ settings }) => settings.model) });
+  const enabledAgents = [config.builder, config.verifier, config.simplifier].filter(
+    ({ required }) => required,
+  );
 
-  try {
-    await assertSubagentsRespond(piEventsBus);
-  } catch (error) {
-    throw new Error(`${SUBAGENT_PING.INSTALLATION_ERROR} ${getErrorMessage(error)}`, {
-      cause: error,
-    });
-  }
+  assertModelsAvailable({ context, models: enabledAgents.map(({ model }) => model) });
 }

package/src/maestro/instructions/getMaestroInstructions.ts

@@ -33,7 +33,8 @@ The project root is the canonical Pi working directory, resolved with realpath.
 Load .pi/maestro.json only from this root. Each agent's required boolean defaults to true. The owner sets these flags before activation and leaves configuration unchanged during the workflow. Do not add caching or runtime flag controls.
 If builder.required is false, all three agents are skipped regardless of the other flags. Otherwise verifier and simplifier can be disabled independently. Never run a disabled phase.
 Resolve spec and product paths against this root. Children run in this directory.
-Do not add worktree checks, activation gates, warnings, or configuration changes: compatible pi-subagents configuration is the owner's responsibility.
+All three roles use the internal Pi SDK executor with bundled role guidance and handoff tools. Do not add another execution engine or a delegation preflight.
+Run tools forward manual cancellation and display the saved native child session path when one exists. Errors stop the workflow; do not retry, repair, resume, or roll back automatically.
 Use generic tools for project inspection. Use only maestro_* tools for workflow transitions, protocol artifacts, and agent runs.
 Do not edit workflow.json or handoffs directly, including through shell commands.
 The spec, prototype, and experiment permissions below are the only exceptions for file changes.

package/src/tools/child/record-builder-handoff.ts

@@ -1,9 +1,9 @@
 /**
- * Objective: Register the builder handoff tool for the current project.
+ * Objective: Define the builder handoff tool for the current project.
  * Used: When the builder reports a done or escalation result.
  */
 
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { ToolDefinition } from '@earendil-works/pi-coding-agent';
 import { Type } from 'typebox';
 
 import {
@@ -38,35 +38,33 @@ const BuilderHandoffToolParameters = Type.Union([
   ),
 ]);
 
-export const registerRecordBuilderHandoffTool = (pi: ExtensionAPI): void => {
-  pi.registerTool({
-    name: BUILDER_HANDOFF_TOOL.NAME,
-    label: BUILDER_HANDOFF_TOOL.LABEL,
-    description: BUILDER_HANDOFF_TOOL.DESCRIPTION,
-    parameters: BuilderHandoffToolParameters,
-    async execute(_toolCallId, params, _signal, _onUpdate, context) {
-      const { specId, ...handoff } = params;
+export const recordBuilderHandoffTool = {
+  name: BUILDER_HANDOFF_TOOL.NAME,
+  label: BUILDER_HANDOFF_TOOL.LABEL,
+  description: BUILDER_HANDOFF_TOOL.DESCRIPTION,
+  parameters: BuilderHandoffToolParameters,
+  async execute(_toolCallId, params, _signal, _onUpdate, context) {
+    const { specId, ...handoff } = params;
 
-      const { paths, config } = await resolveWorkflowContext({
-        cwd: context.cwd,
-        specId,
-      });
+    const { paths, config } = await resolveWorkflowContext({
+      cwd: context.cwd,
+      specId,
+    });
 
-      const completed = await completeBuilderPass({ config, paths, specId, handoff });
+    const completed = await completeBuilderPass({ config, paths, specId, handoff });
 
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Builder handoff recorded as ${completed.handoff.status}. The handoff and workflow phase are saved. Stop now.`,
-          },
-        ],
-        details: {
-          specId: completed.handoff.specId,
-          handoffPath: completed.handoffPath,
-          phase: completed.state.phase,
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Builder handoff recorded as ${completed.handoff.status}. The handoff and workflow phase are saved. Stop now.`,
         },
-      };
-    },
-  });
-};
+      ],
+      details: {
+        specId: completed.handoff.specId,
+        handoffPath: completed.handoffPath,
+        phase: completed.state.phase,
+      },
+    };
+  },
+} satisfies ToolDefinition<typeof BuilderHandoffToolParameters>;