@emiliosp/pi-maestro 0.10.1 → 0.11.0

package/extensions/maestro-subagent.ts

@@ -1,13 +1,15 @@
 /**
- * Objective: Compose the Maestro extension for builder and verifier subagent sessions.
+ * Objective: Compose the Maestro extension for builder, verifier, and simplifier subagent sessions.
  * Used: When Pi starts a Maestro subagent session.
  */
 
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { registerRecordBuilderHandoffTool } from '#tools/child/record-builder-handoff.ts';
+import { registerRecordSimplifierHandoffTool } from '#tools/child/record-simplifier-handoff.ts';
 import { registerRecordVerifierHandoffTool } from '#tools/child/record-verifier-handoff.ts';
 
 export default (pi: ExtensionAPI): void => {
   registerRecordBuilderHandoffTool(pi);
   registerRecordVerifierHandoffTool(pi);
+  registerRecordSimplifierHandoffTool(pi);
 };

package/extensions/maestro.ts

@@ -29,6 +29,10 @@ import {
   RUN_BUILDER_TOOL,
   registerRunBuilderTool,
 } from '#tools/main/run-builder.ts';
+import {
+  RUN_SIMPLIFIER_TOOL,
+  registerRunSimplifierTool,
+} from '#tools/main/run-simplifier.ts';
 import {
   RUN_VERIFIER_TOOL,
   registerRunVerifierTool,
@@ -41,6 +45,7 @@ const MAIN_TOOL_NAMES: readonly string[] = [
   RESOLVE_ESCALATIONS_TOOL.NAME,
   RUN_VERIFIER_TOOL.NAME,
   RESOLVE_FINDINGS_TOOL.NAME,
+  RUN_SIMPLIFIER_TOOL.NAME,
 ];
 
 export default (pi: ExtensionAPI): void => {
@@ -50,6 +55,7 @@ export default (pi: ExtensionAPI): void => {
   registerResolveEscalationsTool(pi);
   registerRunVerifierTool(pi);
   registerResolveFindingsTool(pi);
+  registerRunSimplifierTool(pi);
 
   const syncMainTools = (): void => {
     const foreignTools = pi
@@ -104,6 +110,10 @@ export default (pi: ExtensionAPI): void => {
               'accent',
               `Verifier (${config.verifier.model} ${config.verifier.thinking})`,
             ),
+            context.ui.theme.fg(
+              'accent',
+              `Simplifier (${config.simplifier.model} ${config.simplifier.thinking})`,
+            ),
           ].join('\n'),
           'info',
         );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emiliosp/pi-maestro",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "A spec-driven multiagent development workflow for Pi.",
   "license": "MIT",
   "type": "module",

package/src/MaestroPaths.ts

@@ -186,6 +186,10 @@ export class MaestroPaths {
     });
   }
 
+  public getSimplifierHandoffPath(specId: string): string {
+    return resolve(this.getSpecPath(specId), 'handoffs/simplifier/S.json');
+  }
+
   public getPrototypesPath(specId: string): string {
     return resolve(this.getSpecPath(specId), PATHS.PROTOTYPES_PATH);
   }

package/src/artifacts/simplifier-handoff/assertSimplifierHandoff.ts

@@ -0,0 +1,56 @@
+/**
+ * Objective: Validate the simplifier result and its project-relative file paths.
+ * Used: Before reading or saving a simplifier handoff.
+ */
+
+import { isAbsolute, resolve } from 'node:path';
+import { Value } from 'typebox/value';
+import {
+  type SimplifierHandoff,
+  SimplifierHandoffSchema,
+} from '#artifacts/simplifier-handoff/schema.ts';
+import { isPathStrictlyWithin } from '#utils/path-strictly-within.ts';
+
+type AssertSimplifierHandoffInput<Handoff = unknown> = {
+  handoff: Handoff;
+  specId: string;
+  projectRoot: string;
+};
+
+function assertSimplifierHandoffSchema(
+  input: unknown,
+): asserts input is SimplifierHandoff {
+  const [error] = Value.Errors(SimplifierHandoffSchema, input);
+
+  if (error !== undefined) {
+    throw new Error(`Invalid simplifier handoff: ${error.message}.`);
+  }
+}
+
+export function assertSimplifierHandoff(
+  input: AssertSimplifierHandoffInput,
+): asserts input is AssertSimplifierHandoffInput<SimplifierHandoff> {
+  assertSimplifierHandoffSchema(input.handoff);
+  const { handoff } = input;
+
+  if (handoff.specId !== input.specId) {
+    throw new Error(
+      `Simplifier handoff spec ID mismatch: expected "${input.specId}", found "${handoff.specId}".`,
+    );
+  }
+
+  for (const file of handoff.refactoredFiles) {
+    if (
+      file.includes('\0') ||
+      isAbsolute(file) ||
+      !isPathStrictlyWithin({
+        parent: input.projectRoot,
+        path: resolve(input.projectRoot, file),
+      })
+    ) {
+      throw new Error(
+        `Refactored file path must be relative and stay inside the project root: "${file}".`,
+      );
+    }
+  }
+}

package/src/artifacts/simplifier-handoff/readSimplifierHandoff.ts

@@ -0,0 +1,29 @@
+/**
+ * Objective: Read the fixed simplifier handoff and validate its identity.
+ * Used: After foreground simplifier execution completes.
+ */
+
+import { assertSimplifierHandoff } from '#artifacts/simplifier-handoff/assertSimplifierHandoff.ts';
+import { readJsonFile } from '#utils/read-json.ts';
+
+type ReadSimplifierHandoffInput = {
+  path: string;
+  specId: string;
+  projectRoot: string;
+};
+
+export const readSimplifierHandoff = async ({
+  path,
+  specId,
+  projectRoot,
+}: ReadSimplifierHandoffInput) => {
+  const input = {
+    handoff: await readJsonFile({ path, description: 'Simplifier handoff' }),
+    specId,
+    projectRoot,
+  };
+
+  assertSimplifierHandoff(input);
+
+  return input.handoff;
+};

package/src/artifacts/simplifier-handoff/schema.ts

@@ -0,0 +1,26 @@
+/**
+ * Objective: Define the fixed simplifier result contract.
+ * Used: When a simplifier submits or Maestro reads its handoff.
+ */
+
+import { type Static, Type } from 'typebox';
+import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
+
+export const SIMPLIFIER_HANDOFF_VERSION = '1.0.0';
+
+export const SimplifierSubmissionFields = {
+  specId: Type.String({ pattern: SPEC_ID_PATTERN.source }),
+  refactoredFiles: Type.Array(Type.String({ minLength: 1 })),
+  summary: Type.String({ minLength: 1 }),
+  notes: Type.Array(Type.String()),
+};
+
+export const SimplifierHandoffSchema = Type.Object(
+  {
+    version: Type.Literal(SIMPLIFIER_HANDOFF_VERSION),
+    ...SimplifierSubmissionFields,
+  },
+  { additionalProperties: false },
+);
+
+export type SimplifierHandoff = Static<typeof SimplifierHandoffSchema>;

package/src/config/assertConfiguration.ts

@@ -41,7 +41,7 @@ const formatError = (error: SchemaValidationError): string => {
     return `Invalid model identifier at "${path}". Must use "provider/model" format.`;
   }
 
-  if (path === 'builder' || path === 'verifier') {
+  if (path === 'builder' || path === 'verifier' || path === 'simplifier') {
     return `Invalid ${path} configuration: expected an object.`;
   }
 

package/src/config/defaults.ts

@@ -21,6 +21,8 @@ export const DEFAULT_VERIFIER_MODEL = 'openai-codex/gpt-6.1-sol';
 
 export const DEFAULT_VERIFIER_THINKING = THINKING_LEVELS.HIGH;
 
+export const DEFAULT_SIMPLIFIER_MODEL = 'openai-codex/gpt-6.1-sol';
+
 export const DEFAULT_TIMEOUT_MINUTES = 60;
 
 export const CONFIG_DIRECTORY_NAME = '.pi';
@@ -37,6 +39,11 @@ export const DEFAULT_CONFIG: MaestroConfig = {
     thinking: DEFAULT_BUILDER_THINKING,
     timeoutMinutes: DEFAULT_TIMEOUT_MINUTES,
   },
+  simplifier: {
+    model: DEFAULT_SIMPLIFIER_MODEL,
+    thinking: THINKING_LEVELS.HIGH,
+    timeoutMinutes: DEFAULT_TIMEOUT_MINUTES,
+  },
   verifier: {
     model: DEFAULT_VERIFIER_MODEL,
     thinking: DEFAULT_VERIFIER_THINKING,

package/src/config/loadConfiguration.ts

@@ -16,6 +16,7 @@ const resolveConfiguration = (input: PartialMaestroConfig): MaestroConfig => ({
   specDirectory: input.specDirectory ?? DEFAULT_CONFIG.specDirectory,
   builder: { ...DEFAULT_CONFIG.builder, ...input.builder },
   verifier: { ...DEFAULT_CONFIG.verifier, ...input.verifier },
+  simplifier: { ...DEFAULT_CONFIG.simplifier, ...input.simplifier },
 });
 
 type ResolveSpecDirectoryInput = {

package/src/config/schema.ts

@@ -8,6 +8,7 @@ import { type Static, Type } from 'typebox';
 export const AGENTS = {
   BUILDER: 'maestro.builder',
   VERIFIER: 'maestro.verifier',
+  SIMPLIFIER: 'maestro.simplifier',
 } as const;
 
 export const THINKING_LEVELS = {
@@ -61,6 +62,7 @@ export const MaestroConfigInputSchema = Type.Object(
     specDirectory: Type.Optional(Type.String({ minLength: 1 })),
     builder: Type.Optional(PartialAgentConfigSchema),
     verifier: Type.Optional(PartialAgentConfigSchema),
+    simplifier: Type.Optional(PartialAgentConfigSchema),
   },
   { additionalProperties: false },
 );
@@ -83,6 +85,7 @@ export const ResolvedMaestroConfigSchema = Type.Object(
     specDirectory: Type.String({ minLength: 1 }),
     builder: ResolvedAgentConfigSchema,
     verifier: ResolvedAgentConfigSchema,
+    simplifier: ResolvedAgentConfigSchema,
   },
   { additionalProperties: false },
 );

package/src/maestro/checks/assertEnvironment.ts

@@ -63,7 +63,11 @@ function assertModelsAvailable({
 }: AssertModelsAvailableInput): void {
   const availableModels = context.modelRegistry.getAvailable();
 
-  for (const model of [config.builder.model, config.verifier.model]) {
+  for (const model of [
+    config.builder.model,
+    config.verifier.model,
+    config.simplifier.model,
+  ]) {
     const [provider, id] = model.split('/');
 
     if (
@@ -77,7 +81,7 @@ function assertModelsAvailable({
 }
 
 async function assertAgentsAvailable(projectRoot: string): Promise<void> {
-  for (const agent of [AGENTS.BUILDER, AGENTS.VERIFIER]) {
+  for (const agent of [AGENTS.BUILDER, AGENTS.VERIFIER, AGENTS.SIMPLIFIER]) {
     const result = await resolveSubagentLaunchContract({
       agent,
       cwd: projectRoot,
@@ -171,7 +175,7 @@ export async function assertEnvironment({
     await assertAgentsAvailable(projectRoot);
   } catch (error) {
     throw new Error(
-      `Builder or verifier agent check failed: ${getErrorMessage(error)}`,
+      `Builder, verifier, or simplifier agent check failed: ${getErrorMessage(error)}`,
     );
   }
 

package/src/maestro/instructions/getMaestroInstructions.ts

@@ -15,8 +15,8 @@ const MAESTRO_INSTRUCTIONS = `## Maestro mode
 
 You are Maestro. Coordinate one sequential spec-driven workflow in the current session.
 The owner decides requirements, scope, technical decisions in the spec, spec approval, escalation answers, and finding decisions.
-The builder implements the approved spec. The verifier independently checks the candidate. Do not perform their work yourself.
-The approved spec.md is the contract for all three roles. Do not infer owner approval from an agent's recommendation.
+The builder implements the approved spec. The verifier independently checks the candidate. The simplifier refactors accepted code. Do not perform their work yourself.
+The approved spec.md is the contract for all roles. Do not infer owner approval from an agent's recommendation.
 
 ### Maestro documentation
 
@@ -37,7 +37,7 @@ The spec, prototype, and experiment permissions below are the only exceptions fo
 
 Use the specId and paths returned by maestro_create_spec. Read workflow.json before selecting the next action. Its validated phase is the source of truth.
 Use tool schemas for arguments and tool results for outcomes. Do not infer a completed transition from an agent's final message.
-Builder and verifier runs are foreground operations with fresh contexts. Start them only through maestro_run_builder and maestro_run_verifier.
+Builder, verifier, and simplifier runs are foreground operations with fresh contexts. Start them only through maestro_run_builder, maestro_run_verifier, and maestro_run_simplifier.
 Wait for each tool result before taking the next workflow action. Do not launch parallel or background runs.
 
 ### Prepare and approve the spec
@@ -93,7 +93,7 @@ Edit the active spec.md and its prototypes/ directory only in drafting-spec.
 For either revision origin, record the complete owner decision batch through the corresponding resolution tool before editing in drafting-spec.
 The numbering-only recovery procedure above also permits spec.md corrections after failed numbering validation in drafting-spec.
 Do not edit the spec or prototypes in other phases.
-The approved spec is frozen. Never change it during builder or verifier execution.
+The approved spec is frozen. Never change it during builder, verifier, or simplifier execution.
 Use any available tool for these permitted edits. Do not change other workflow artifacts.
 
 Only in those same circumstances, run tests and checks to answer specification questions.
@@ -128,7 +128,14 @@ The verifier restores only its temporary changes and removes only its own tempor
 Each completed pass creates the next numbered file: handoffs/builder/B1.json, B2.json or handoffs/verifier/V1.json, V2.json.
 Earlier handoffs remain on the file system. The highest numeric sequence identifies the active handoff for each role.
 Use earlier handoffs only as references. Validate the active artifact's spec identity, schema, and outcome against the phase.
-Read the returned verifier handoff. If there are findings, follow finding-decisions. If there are none, follow candidate-ready.
+Read the returned verifier handoff. If there are findings, follow finding-decisions. If there are none, follow simplifier-running.
+
+In simplifier-running, call maestro_run_simplifier next with the active specId, after either successful verification or rejection of all findings.
+Do not ask for another approval or run the verifier again. Both routes enter this phase regardless of Git availability.
+Only maestro_run_simplifier checks Git readiness immediately before delegation. Do not check Git in activation or either entry route.
+If Git is unavailable, the tool warns and skips simplification, saves candidate-ready, and creates no simplifier handoff. Report simplification as skipped.
+Otherwise the simplifier records handoffs/simplifier/S.json before candidate-ready. This fixed result is unnumbered.
+Simplifier execution or protocol errors stop the workflow under the same error policy as other runs.
 
 ### Explain findings and escalations
 
@@ -168,7 +175,7 @@ Submit the complete batch through maestro_resolve_findings before editing the sp
 The tool saves every decision in the active verifier handoff before saving the next phase. Earlier numbered handoffs remain unchanged.
 If any decision is revise-spec, the tool returns drafting-spec without approving the spec or running an agent.
 Revision takes priority over fix-code and reject in mixed batches, while all decisions are saved.
-Without revision, all rejections return candidate-ready and any fix-code returns ready-for-builder.
+Without revision, all rejections return simplifier-running and any fix-code returns ready-for-builder.
 For ready-for-builder, call maestro_run_builder separately. Do not fix the code yourself.
 
 For either an escalation revision or a finding revision, first record the complete batch and enter drafting-spec as described above.
@@ -193,6 +200,9 @@ The owner handles execution errors, protocol errors, and interrupted workflows m
 
 At candidate-ready, the workflow is complete. No final tool call is required.
 You own the final summary. Read the artifacts to summarize changes, verification results, rejected findings with reasons, and applicable builder notes.
+For completed simplification, read handoffs/simplifier/S.json and report its saved summary and notes as the simplifier's report.
+For example, summary "Simplified counting" and note "Updated the caller to read the Map." belong to the simplifier, not verifier evidence.
+Do not claim the verifier independently checked later refactoring. Keep verification evidence and the simplifier report separate.
 Do not describe rejected findings as passed verification.
 Do not change files, run verification again, or modify the concluded workflow to prepare this summary.
 The owner controls later review and changes. Later changes are outside this verification.`;

package/src/maestro/status/formatMaestroStatus.ts

@@ -18,6 +18,7 @@ export const WORKFLOW_PHASE_LABELS = {
   [WORKFLOW_PHASES.READY_FOR_VERIFIER]: 'Ready for verifier',
   [WORKFLOW_PHASES.VERIFIER_RUNNING]: 'Verifier running',
   [WORKFLOW_PHASES.FINDING_DECISIONS]: 'Owner decision needed: findings',
+  [WORKFLOW_PHASES.SIMPLIFIER_RUNNING]: 'Simplifier running',
   [WORKFLOW_PHASES.CANDIDATE_READY]: 'Completed',
 } as const;
 
@@ -29,6 +30,7 @@ export const WORKFLOW_PHASE_ICONS = {
   [WORKFLOW_PHASES.READY_FOR_VERIFIER]: '📋',
   [WORKFLOW_PHASES.VERIFIER_RUNNING]: '🔍',
   [WORKFLOW_PHASES.FINDING_DECISIONS]: '💬',
+  [WORKFLOW_PHASES.SIMPLIFIER_RUNNING]: '🧹',
   [WORKFLOW_PHASES.CANDIDATE_READY]: '✅',
 } as const;
 
@@ -40,6 +42,7 @@ export const WORKFLOW_PHASE_COLORS = {
   [WORKFLOW_PHASES.READY_FOR_VERIFIER]: 'accent',
   [WORKFLOW_PHASES.VERIFIER_RUNNING]: 'accent',
   [WORKFLOW_PHASES.FINDING_DECISIONS]: 'warning',
+  [WORKFLOW_PHASES.SIMPLIFIER_RUNNING]: 'accent',
   [WORKFLOW_PHASES.CANDIDATE_READY]: 'success',
 } as const satisfies Record<WorkflowPhase, ThemeColor>;
 

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

@@ -0,0 +1,73 @@
+/**
+ * Objective: Register the simplifier's fixed result recording tool.
+ * Used: When a child simplifier completes its refactoring pass.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { type Static, Type } from 'typebox';
+import { Value } from 'typebox/value';
+import {
+  SIMPLIFIER_HANDOFF_VERSION,
+  SimplifierSubmissionFields,
+} from '#artifacts/simplifier-handoff/schema.ts';
+import { resolveWorkflowContext } from '#tools/child/utils/resolveWorkflowContext.ts';
+import { completeSimplifierPass } from '#workflow/simplifier/completeSimplifierPass.ts';
+
+export const SIMPLIFIER_HANDOFF_TOOL = {
+  NAME: 'maestro_record_simplifier_handoff',
+  LABEL: 'Record Simplifier Handoff',
+  DESCRIPTION:
+    'Save the simplifier result at handoffs/simplifier/S.json and complete the workflow. Stop after success.',
+} as const;
+
+const SimplifierHandoffToolParameters = Type.Object(
+  SimplifierSubmissionFields,
+  { additionalProperties: false },
+);
+
+function assertSimplifierSubmission(
+  input: unknown,
+): asserts input is Static<typeof SimplifierHandoffToolParameters> {
+  const [error] = Value.Errors(SimplifierHandoffToolParameters, input);
+
+  if (error !== undefined) {
+    throw new Error(`Invalid simplifier submission: ${error.message}.`);
+  }
+}
+
+export const registerRecordSimplifierHandoffTool = (pi: ExtensionAPI): void => {
+  pi.registerTool({
+    name: SIMPLIFIER_HANDOFF_TOOL.NAME,
+    label: SIMPLIFIER_HANDOFF_TOOL.LABEL,
+    description: SIMPLIFIER_HANDOFF_TOOL.DESCRIPTION,
+    parameters: SimplifierHandoffToolParameters,
+    async execute(_toolCallId, params, _signal, _onUpdate, context) {
+      assertSimplifierSubmission(params);
+
+      const { paths } = await resolveWorkflowContext({
+        cwd: context.cwd,
+        specId: params.specId,
+      });
+
+      const completed = await completeSimplifierPass({
+        paths,
+        specId: params.specId,
+        handoff: { ...params, version: SIMPLIFIER_HANDOFF_VERSION },
+      });
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: 'Simplifier handoff and candidate-ready phase saved. Stop now.',
+          },
+        ],
+        details: {
+          specId: params.specId,
+          handoffPath: completed.handoffPath,
+          phase: completed.state.phase,
+        },
+      };
+    },
+  });
+};

package/src/tools/main/resolve-findings.ts

@@ -97,7 +97,7 @@ const formatResolution = (details: FindingResolutionDetails): string => {
     return `${summary} The workflow is ready-for-builder. Run the builder separately.`;
   }
 
-  return `${summary} The workflow is candidate-ready.`;
+  return `${summary} The workflow is simplifier-running. Call maestro_run_simplifier next with this specId, without another approval or verifier pass.`;
 };
 
 export const registerResolveFindingsTool = (pi: ExtensionAPI): void => {

package/src/tools/main/run-simplifier.ts

@@ -0,0 +1,182 @@
+/**
+ * Objective: Run the simplifier in Git projects or explicitly skip unavailable Git.
+ * Used: After verification succeeds or the owner rejects all findings.
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { SubagentDelegationRequest } from 'pi-subagents/delegation';
+import { Type } from 'typebox';
+import { readSimplifierHandoff } from '#artifacts/simplifier-handoff/readSimplifierHandoff.ts';
+import { AGENTS } from '#config/schema.ts';
+import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
+import type { MaestroPaths } from '#MaestroPaths.ts';
+import { refreshMaestroStatus } from '#maestro/status/refreshMaestroStatus.ts';
+import {
+  assertDelegationResponse,
+  waitForDelegationResponse,
+} from '#tools/utils/pi-subagent-delegation.ts';
+import { resolveToolRunContext } from '#tools/utils/resolveToolRunContext.ts';
+import { WORKFLOW_ROLES } from '#workflow/roles.ts';
+import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
+import { WORKFLOW_EVENTS, WORKFLOW_PHASES } from '#workflow/state/schema.ts';
+import { writeWorkflowState } from '#workflow/state/writeWorkflowState.ts';
+import { transitionWorkflow } from '#workflow/transitions.ts';
+
+export const RUN_SIMPLIFIER_TOOL = {
+  NAME: 'maestro_run_simplifier',
+  LABEL: 'Run Simplifier',
+  DESCRIPTION:
+    'Run the simplifier in the foreground from simplifier-running. If Git readiness cannot be confirmed, warn and complete without delegation.',
+} as const;
+
+const RunSimplifierToolParameters = Type.Object(
+  { specId: Type.String({ pattern: SPEC_ID_PATTERN.source }) },
+  { additionalProperties: false },
+);
+
+const MILLISECONDS_PER_MINUTE = 60_000;
+
+const GIT_SKIP_WARNING = 'Simplifier skipped: Git repository unavailable.';
+
+type GitReadinessInput = {
+  pi: ExtensionAPI;
+  projectRoot: string;
+};
+
+const isGitReady = async ({
+  pi,
+  projectRoot,
+}: GitReadinessInput): Promise<boolean> => {
+  try {
+    const result = await pi.exec(
+      'git',
+      ['rev-parse', '--is-inside-work-tree'],
+      { cwd: projectRoot },
+    );
+
+    return result.code === 0 && result.stdout.trim() === 'true';
+  } catch {
+    return false;
+  }
+};
+
+type ReadSimplifierResultInput = {
+  paths: MaestroPaths;
+  specId: string;
+};
+
+const readSimplifierResult = async ({
+  paths,
+  specId,
+}: ReadSimplifierResultInput) => {
+  try {
+    const state = await readWorkflowState(paths.getWorkflowPath(specId));
+
+    if (state.specId !== specId) {
+      throw new Error(
+        `Workflow spec ID mismatch: expected "${specId}", found "${state.specId}".`,
+      );
+    }
+
+    if (state.phase !== WORKFLOW_PHASES.CANDIDATE_READY) {
+      throw new Error(
+        `The simplifier returned without recording a valid terminal handoff. Workflow phase is "${state.phase}".`,
+      );
+    }
+
+    const handoff = await readSimplifierHandoff({
+      path: paths.getSimplifierHandoffPath(specId),
+      specId,
+      projectRoot: paths.getProjectRoot(),
+    });
+
+    return { specId, phase: state.phase, outcome: state.phase, handoff };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Simplifier protocol error: ${message}`, { cause: error });
+  }
+};
+
+export const registerRunSimplifierTool = (pi: ExtensionAPI): void => {
+  pi.registerTool({
+    name: RUN_SIMPLIFIER_TOOL.NAME,
+    label: RUN_SIMPLIFIER_TOOL.LABEL,
+    description: RUN_SIMPLIFIER_TOOL.DESCRIPTION,
+    parameters: RunSimplifierToolParameters,
+    async execute(toolCallId, { specId }, _signal, _onUpdate, context) {
+      const { paths, config, projectRoot } = await resolveToolRunContext(
+        context.cwd,
+      );
+
+      const workflowPath = paths.getWorkflowPath(specId);
+      const state = await readWorkflowState(workflowPath);
+
+      if (state.specId !== specId) {
+        throw new Error(
+          `Workflow spec ID mismatch: expected "${specId}", found "${state.specId}".`,
+        );
+      }
+
+      if (state.phase !== WORKFLOW_PHASES.SIMPLIFIER_RUNNING) {
+        throw new Error(
+          `Simplifier run requires simplifier-running state, found "${state.phase}".`,
+        );
+      }
+
+      await refreshMaestroStatus(context);
+
+      if (!(await isGitReady({ pi, projectRoot }))) {
+        const nextState = transitionWorkflow({
+          state,
+          event: WORKFLOW_EVENTS.SIMPLIFIER_SKIPPED,
+        });
+
+        await writeWorkflowState({ path: workflowPath, state: nextState });
+        context.ui.notify(GIT_SKIP_WARNING, 'warning');
+
+        return {
+          content: [{ type: 'text', text: GIT_SKIP_WARNING }],
+          details: {
+            specId,
+            phase: nextState.phase,
+            skipped: true,
+            warning: GIT_SKIP_WARNING,
+          },
+        };
+      }
+
+      const request: SubagentDelegationRequest = {
+        requestId: randomUUID(),
+        ownerRunId: toolCallId,
+        nodeId: WORKFLOW_ROLES.SIMPLIFIER,
+        agent: AGENTS.SIMPLIFIER,
+        task: `Simplify accepted code for specId "${specId}" in the project directory "${projectRoot}". Discover all current staged, unstaged, and untracked code changes with Git, including pre-existing changes.`,
+        context: 'fresh',
+        cwd: projectRoot,
+        model: config.simplifier.model,
+        thinking: config.simplifier.thinking,
+        timeoutMs: config.simplifier.timeoutMinutes * MILLISECONDS_PER_MINUTE,
+        result: { kind: 'text' },
+      };
+
+      const response = await waitForDelegationResponse({
+        piEventsBus: pi.events,
+        request,
+      });
+
+      assertDelegationResponse(response);
+      const result = await readSimplifierResult({ paths, specId });
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Simplifier completed spec ${specId}. The workflow is candidate-ready. Report the saved simplifier summary and notes as its report, not verifier evidence.`,
+          },
+        ],
+        details: result,
+      };
+    },
+  });
+};