@dreki-gg/pi-plan-mode 0.6.4 → 0.10.1

package/extensions/plan-mode/phase-transitions.ts

@@ -0,0 +1,87 @@
+/**
+ * Phase transitions — enter/exit plan mode, start execution, switch models.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { PlanModeState } from './state.js';
+import type { ThinkingLevel } from './types.js';
+import { PLAN_TOOLS, EXEC_TOOLS, PLAN_MODEL, PLAN_THINKING, EXEC_MODEL, EXEC_THINKING } from './constants.js';
+import { updateUI } from './ui.js';
+
+export async function switchModel(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  preset: { provider: string; id: string },
+): Promise<boolean> {
+  const model = ctx.modelRegistry.find(preset.provider, preset.id);
+  if (!model) {
+    ctx.ui.notify(`Model ${preset.provider}/${preset.id} not found`, 'error');
+    return false;
+  }
+  const ok = await pi.setModel(model);
+  if (!ok) {
+    ctx.ui.notify(`No API key for ${preset.provider}/${preset.id}`, 'error');
+    return false;
+  }
+  return true;
+}
+
+export async function enterPlanMode(
+  state: PlanModeState,
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+): Promise<void> {
+  state.planEnabled = true;
+  state.executing = false;
+  state.planDir = undefined;
+  state.plan = undefined;
+  state.previousThinking = pi.getThinkingLevel() as ThinkingLevel;
+  state.previousModel = ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : undefined;
+  pi.setActiveTools(PLAN_TOOLS);
+  await switchModel(pi, ctx, PLAN_MODEL);
+  pi.setThinkingLevel(PLAN_THINKING);
+  ctx.ui.notify(
+    `Plan mode ON — ${PLAN_MODEL.provider}/${PLAN_MODEL.id}:${PLAN_THINKING}`,
+    'info',
+  );
+  updateUI(state, ctx);
+  state.persist(pi);
+}
+
+export async function exitPlanMode(
+  state: PlanModeState,
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+): Promise<void> {
+  const { previousModel, previousThinking } = state;
+  state.reset();
+  pi.setActiveTools(EXEC_TOOLS);
+  if (previousModel) {
+    await switchModel(pi, ctx, previousModel);
+  }
+  if (previousThinking) {
+    pi.setThinkingLevel(previousThinking);
+  }
+  ctx.ui.notify('Plan mode OFF — original model restored', 'info');
+  updateUI(state, ctx);
+  state.persist(pi);
+}
+
+export async function startExecution(
+  state: PlanModeState,
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+): Promise<void> {
+  state.planEnabled = false;
+  state.executing = true;
+  state.executionStartIdx = ctx.sessionManager.getEntries().length;
+  pi.setActiveTools(EXEC_TOOLS);
+  await switchModel(pi, ctx, EXEC_MODEL);
+  pi.setThinkingLevel(EXEC_THINKING);
+  ctx.ui.notify(
+    `Executing plan — ${EXEC_MODEL.provider}/${EXEC_MODEL.id}:${EXEC_THINKING}`,
+    'info',
+  );
+  updateUI(state, ctx);
+  state.persist(pi);
+}

package/extensions/plan-mode/plan-storage.ts

@@ -0,0 +1,67 @@
+/**
+ * Plan disk I/O — save/load plans, exec-pending markers, and manifest updates.
+ */
+
+import { mkdir, readFile, readdir, unlink, writeFile } from 'node:fs/promises';
+import { readPlansJson, serializePlansJson } from './plans-json.js';
+import type { PlanData, ExecPendingConfig } from './types.js';
+import { EXEC_PENDING_FILE } from './constants.js';
+
+export async function savePlanToDisk(planDir: string, plan: PlanData): Promise<void> {
+  await mkdir(planDir, { recursive: true });
+  await writeFile(`${planDir}/plan.json`, JSON.stringify(plan, null, 2) + '\n', 'utf-8');
+}
+
+export async function loadPlanFromDisk(dir: string): Promise<PlanData | undefined> {
+  try {
+    const text = await readFile(`${dir}/plan.json`, 'utf-8');
+    return JSON.parse(text) as PlanData;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function writeExecPending(dir: string, config: ExecPendingConfig): Promise<void> {
+  await mkdir(dir, { recursive: true });
+  await writeFile(`${dir}/${EXEC_PENDING_FILE}`, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}
+
+export async function readAndClearExecPending(): Promise<{ planDir: string; config: ExecPendingConfig } | undefined> {
+  try {
+    const entries = await readdir('.plans', { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const dir = `.plans/${entry.name}`;
+      const markerPath = `${dir}/${EXEC_PENDING_FILE}`;
+      try {
+        const text = await readFile(markerPath, 'utf-8');
+        const config = JSON.parse(text) as ExecPendingConfig;
+        await unlink(markerPath);
+        return { planDir: dir, config };
+      } catch {
+        // No marker in this directory
+      }
+    }
+  } catch {
+    // .plans/ doesn't exist
+  }
+  return undefined;
+}
+
+export async function updatePlansManifest(
+  planName: string,
+  status: 'in-progress' | 'done',
+  title?: string,
+): Promise<void> {
+  const manifest = await readPlansJson();
+  const existing = manifest[planName];
+  const now = new Date().toISOString();
+  manifest[planName] = {
+    status,
+    title: title ?? existing?.title ?? 'Untitled plan',
+    created: existing?.created ?? now,
+    completed: status === 'done' ? now : null,
+  };
+  await mkdir('.plans', { recursive: true });
+  await writeFile('.plans/plans.json', serializePlansJson(manifest), 'utf-8');
+}

package/extensions/plan-mode/plans-json.ts

@@ -45,8 +45,4 @@ export function serializePlansJson(manifest: PlansManifest): string {
   return `${JSON.stringify(manifest, null, 2)}\n`;
 }
 
-/** Extract the plan title from the first `# ...` heading in PLAN.md content. */
-export function extractPlanTitle(planContent: string): string {
-  const match = planContent.match(/^#\s+(.+)$/m);
-  return match ? match[1].trim() : 'Untitled plan';
-}
+

package/extensions/plan-mode/prompts.ts

@@ -0,0 +1,67 @@
+/**
+ * Prompt builders for plan and execution phases.
+ */
+
+import type { PlanData } from './types.js';
+import { PLAN_TOOLS } from './constants.js';
+
+export function buildPlanModePrompt(): string {
+  return `[PLAN MODE ACTIVE]
+You are in plan mode — a planning phase with strict bash restrictions.
+
+Restrictions:
+- Available tools: ${PLAN_TOOLS.join(', ')}
+- Bash is restricted to read-only commands (ls, grep, git status, etc.)
+
+Your task:
+1. Analyze the codebase thoroughly using the available read-only tools
+2. Ask clarifying questions if needed (use the questionnaire tool)
+3. Produce a detailed, concrete plan
+
+When you are ready to finalize the plan, call the submit_plan tool with:
+- name: a short kebab-case name (e.g. "add-auth-middleware")
+- title: a human-readable plan title
+- context: complete codebase context including relevant file paths, APIs, patterns, constraints, and gotchas — this must be thorough enough that an implementor with zero prior context can execute the plan
+- steps: an array of steps, each with a short description (≤60 chars for display) and detailed implementation instructions
+- risks: any open questions, assumptions, or concerns
+
+Do NOT attempt to make product code changes — only analyze and plan.
+Do NOT write files manually — use submit_plan to finalize the plan.`;
+}
+
+export function buildExecutionPrompt(plan: PlanData): string | undefined {
+  const remaining = plan.steps
+    .map((s, i) => ({ ...s, num: i + 1 }))
+    .filter((s) => s.status === 'pending');
+
+  if (remaining.length === 0) return undefined;
+
+  const stepList = remaining
+    .map((s) => `${s.num}. ${s.description}\n   Details: ${s.details}`)
+    .join('\n\n');
+
+  const currentStep = remaining[0];
+
+  return `[EXECUTING PLAN — FOLLOW THE PLAN EXACTLY]
+
+You are executing a structured plan. Your ONLY job is to implement the plan steps below, one at a time.
+
+Rules:
+- Work on ONE step at a time, starting with step ${currentStep.num}
+- After completing each step, IMMEDIATELY call update_step to mark it done
+- Do NOT run diagnostics, linters, test suites, or skills unless a step explicitly asks for it
+- Do NOT explore the codebase beyond what the current step requires
+- Do NOT deviate from the plan — if something seems wrong, call update_step with status "blocked"
+
+## Current step
+Step ${currentStep.num}: ${currentStep.description}
+Details: ${currentStep.details}
+
+## Codebase context
+${plan.context}
+
+## All remaining steps
+${stepList}
+
+Start with step ${currentStep.num} NOW. When done, call update_step(step=${currentStep.num}, status="done").`;
+}

package/extensions/plan-mode/resume.ts

@@ -0,0 +1,121 @@
+/**
+ * Resume and execution handoff — pick up in-progress plans, model picker, new session handoff.
+ */
+
+import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+import type { PlanModeState } from './state.js';
+import type { PlanData } from './types.js';
+import { EXEC_THINKING, EXEC_MODEL_OPTIONS } from './constants.js';
+import { readPlansJson } from './plans-json.js';
+import { loadPlanFromDisk, writeExecPending, savePlanToDisk } from './plan-storage.js';
+import { enterPlanMode } from './phase-transitions.js';
+
+export async function pickExecutionModel(
+  ctx: ExtensionContext,
+): Promise<{ provider: string; id: string } | undefined> {
+  const labels = EXEC_MODEL_OPTIONS.map((o) => o.label);
+  const choice = await ctx.ui.select('Execute with:', labels);
+  if (!choice) return undefined;
+  return EXEC_MODEL_OPTIONS.find((o) => o.label === choice)?.model;
+}
+
+export async function executeInNewSession(
+  ctx: ExtensionCommandContext,
+  dir: string,
+  _planData: PlanData,
+  kickoff: string,
+): Promise<void> {
+  const selectedModel = await pickExecutionModel(ctx);
+  if (!selectedModel) return;
+
+  await writeExecPending(dir, { model: selectedModel, thinking: EXEC_THINKING });
+  const parentSession = ctx.sessionManager.getSessionFile();
+
+  await ctx.newSession({
+    parentSession,
+    withSession: async (newCtx) => {
+      await newCtx.sendUserMessage(kickoff);
+    },
+  });
+}
+
+export async function resumePlan(
+  state: PlanModeState,
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  const manifest = await readPlansJson();
+  const inProgress = Object.entries(manifest).filter(([, e]) => e.status === 'in-progress');
+
+  if (inProgress.length === 0) {
+    ctx.ui.notify('No in-progress plans found in .plans/plans.json', 'info');
+    return;
+  }
+
+  const options = inProgress.map(([name, entry]) => `${name} — ${entry.title}`);
+  options.push('Cancel');
+
+  const choice = await ctx.ui.select('Resume which plan?', options);
+  if (!choice || choice === 'Cancel') return;
+
+  const planName = choice.split(' — ')[0];
+  const dir = `.plans/${planName}`;
+  const loaded = await loadPlanFromDisk(dir);
+
+  if (!loaded) {
+    ctx.ui.notify(`Could not load ${dir}/plan.json`, 'error');
+    return;
+  }
+
+  state.planDir = dir;
+  state.plan = loaded;
+
+  const doneCount = state.plan.steps.filter((s) => s.status === 'done' || s.status === 'skipped').length;
+  const pendingCount = state.plan.steps.filter((s) => s.status === 'pending').length;
+  const blockedCount = state.plan.steps.filter((s) => s.status === 'blocked').length;
+
+  if (pendingCount === 0 && blockedCount === 0) {
+    ctx.ui.notify(`Plan "${state.plan.title}" is already complete (${doneCount}/${state.plan.steps.length} done).`, 'info');
+    state.plan = undefined;
+    state.planDir = undefined;
+    return;
+  }
+
+  const summary = `${doneCount}/${state.plan.steps.length} done, ${pendingCount} pending${blockedCount ? `, ${blockedCount} blocked` : ''}`;
+  const action = await ctx.ui.select(
+    `Resume "${state.plan.title}" (${summary}) — what next?`,
+    ['Continue execution', 'Re-plan from scratch', 'Cancel'],
+  );
+
+  if (!action || action === 'Cancel') {
+    state.plan = undefined;
+    state.planDir = undefined;
+    return;
+  }
+
+  if (action === 'Re-plan from scratch') {
+    const planTitle = state.plan.title;
+    const planDirPath = state.planDir;
+    await enterPlanMode(state, pi, ctx);
+    pi.sendUserMessage(
+      `There is an existing plan "${planTitle}" at ${planDirPath}/plan.json. Review it and create a revised plan using submit_plan. Keep the same plan name ("${planName}").`,
+    );
+    return;
+  }
+
+  // Unblock any blocked steps
+  if (blockedCount > 0) {
+    for (const step of state.plan.steps) {
+      if (step.status === 'blocked') step.status = 'pending';
+    }
+    await savePlanToDisk(dir, state.plan);
+  }
+
+  const remaining = state.plan.steps
+    .map((s, i) => ({ ...s, num: i + 1 }))
+    .filter((s) => s.status === 'pending');
+  const stepList = remaining.map((s) => `${s.num}. ${s.description}`).join('\n');
+  const kickoff = `Resuming plan: "${state.plan.title}"\n\nCompleted: ${doneCount}/${state.plan.steps.length} steps\n\nRemaining steps:\n${stepList}\n\nContinue from step ${remaining[0].num}. Call update_step after completing each step.`;
+
+  await executeInNewSession(ctx, dir, state.plan, kickoff);
+}

package/extensions/plan-mode/state.ts

@@ -0,0 +1,47 @@
+/**
+ * Encapsulates all mutable plan-mode state with persistence helpers.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { PlanData, PersistedState, ThinkingLevel } from './types.js';
+
+export class PlanModeState {
+  planEnabled = false;
+  executing = false;
+  planDir: string | undefined;
+  plan: PlanData | undefined;
+  executionStartIdx: number | undefined;
+  previousThinking: ThinkingLevel | undefined;
+  previousModel: { provider: string; id: string } | undefined;
+
+  persist(pi: ExtensionAPI): void {
+    pi.appendEntry<PersistedState>('plan-mode', {
+      planEnabled: this.planEnabled,
+      executing: this.executing,
+      planDir: this.planDir,
+      plan: this.plan,
+      executionStartIdx: this.executionStartIdx,
+    });
+  }
+
+  restore(entries: Array<{ type: string; customType?: string; data?: PersistedState }>): void {
+    const saved = entries
+      .filter((e) => e.type === 'custom' && e.customType === 'plan-mode')
+      .pop();
+    if (saved?.data) {
+      this.planEnabled = saved.data.planEnabled ?? this.planEnabled;
+      this.executing = saved.data.executing ?? this.executing;
+      this.planDir = saved.data.planDir ?? this.planDir;
+      this.plan = saved.data.plan ?? this.plan;
+      this.executionStartIdx = saved.data.executionStartIdx ?? this.executionStartIdx;
+    }
+  }
+
+  reset(): void {
+    this.planEnabled = false;
+    this.executing = false;
+    this.planDir = undefined;
+    this.plan = undefined;
+    this.executionStartIdx = undefined;
+  }
+}

package/extensions/plan-mode/tools/submit-plan.ts

@@ -0,0 +1,144 @@
+/**
+ * submit_plan tool — available during the plan phase.
+ *
+ * The planner calls this to submit a structured plan with typed steps.
+ * Writes `.plans/<name>/plan.json` and updates the plans.json manifest.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Text } from '@earendil-works/pi-tui';
+import { Type } from 'typebox';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { readPlansJson, serializePlansJson } from '../plans-json.js';
+import { toKebabCase } from '../utils.js';
+import type { PlanData, PlanStep } from '../types.js';
+
+export interface SubmitPlanCallbacks {
+  onPlanSubmitted: (planDir: string, plan: PlanData) => void;
+}
+
+export function registerSubmitPlanTool(pi: ExtensionAPI, callbacks: SubmitPlanCallbacks): void {
+  pi.registerTool({
+    name: 'submit_plan',
+    label: 'Submit Plan',
+    description:
+      'Submit a structured plan with a title, context, numbered steps, and risks. ' +
+      'Each step has a short description (for progress display) and detailed implementation instructions. ' +
+      'This finalizes the plan and writes it to .plans/<name>/plan.json.',
+    promptSnippet:
+      'Submit a structured plan with title, context, steps (description + details), and risks',
+    promptGuidelines: [
+      'Call submit_plan once when you have finished analyzing the codebase and are ready to finalize your plan.',
+      'Each submit_plan step description should be a short label (≤60 chars). Put full implementation instructions in the details field.',
+      'The submit_plan context field must include all codebase findings, relevant file paths, APIs, patterns, and constraints so an executor with zero prior context can implement the plan.',
+    ],
+    parameters: Type.Object({
+      name: Type.String({
+        description: 'Short kebab-case name for the plan (e.g. "add-auth-middleware")',
+      }),
+      title: Type.String({ description: 'Human-readable plan title' }),
+      context: Type.String({
+        description:
+          'Complete codebase context: relevant file paths, APIs, patterns, constraints, and gotchas',
+      }),
+      steps: Type.Array(
+        Type.Object({
+          description: Type.String({
+            description: 'Short step label for progress display (≤60 chars)',
+          }),
+          details: Type.String({
+            description: 'Full implementation instructions for this step',
+          }),
+        }),
+        { minItems: 1 },
+      ),
+      risks: Type.String({ description: 'Open questions, assumptions, and risks' }),
+    }),
+
+    async execute(_toolCallId, params) {
+      const planName = toKebabCase(params.name);
+      const planDir = `.plans/${planName}`;
+
+      const steps: PlanStep[] = params.steps.map((s) => ({
+        description: s.description.slice(0, 60),
+        details: s.details,
+        status: 'pending' as const,
+      }));
+
+      const plan: PlanData = {
+        title: params.title,
+        context: params.context,
+        steps,
+        risks: params.risks,
+      };
+
+      // Write plan.json
+      await mkdir(planDir, { recursive: true });
+      await writeFile(`${planDir}/plan.json`, JSON.stringify(plan, null, 2) + '\n', 'utf-8');
+
+      // Update plans.json manifest
+      const manifest = await readPlansJson();
+      const now = new Date().toISOString();
+      manifest[planName] = {
+        status: 'in-progress',
+        title: params.title,
+        created: manifest[planName]?.created ?? now,
+        completed: null,
+      };
+      await writeFile('.plans/plans.json', serializePlansJson(manifest), 'utf-8');
+
+      callbacks.onPlanSubmitted(planDir, plan);
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Plan "${params.title}" saved with ${steps.length} steps. Waiting for user to review and execute.`,
+          },
+        ],
+        details: { planDir, plan },
+        terminate: true,
+      };
+    },
+
+    renderCall(args, theme) {
+      const name = (args as { name?: string }).name ?? 'plan';
+      const title = (args as { title?: string }).title ?? '';
+      let content = theme.fg('toolTitle', theme.bold('submit_plan '));
+      content += theme.fg('accent', name);
+      if (title) {
+        content += ' ' + theme.fg('dim', `"${title}"`);
+      }
+      return new Text(content, 0, 0);
+    },
+
+    renderResult(result, _options, theme) {
+      const details = result.details as { plan?: PlanData } | undefined;
+      const plan = details?.plan;
+      if (!plan) {
+        return new Text(theme.fg('success', '✓ Plan saved'), 0, 0);
+      }
+
+      const lines: string[] = [];
+
+      // Title
+      lines.push(theme.fg('success', '✓ ') + theme.fg('accent', theme.bold(plan.title)));
+      lines.push('');
+
+      // Steps
+      for (let i = 0; i < plan.steps.length; i++) {
+        const step = plan.steps[i];
+        const num = theme.fg('muted', `${i + 1}.`);
+        lines.push(`  ${num} ${step.description}`);
+      }
+
+      // Risks
+      if (plan.risks) {
+        lines.push('');
+        lines.push(theme.fg('warning', '⚠ Risks: ') + theme.fg('dim', plan.risks));
+      }
+
+      return new Text(lines.join('\n'), 0, 0);
+    },
+  });
+}

package/extensions/plan-mode/tools/update-step.ts

@@ -0,0 +1,145 @@
+/**
+ * update_step tool — available during the execution phase.
+ *
+ * The executor calls this to mark a plan step as done, skipped, or blocked.
+ * On "blocked", returns a stop signal so the executor pauses for user intervention.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { StringEnum } from '@earendil-works/pi-ai';
+import { Text } from '@earendil-works/pi-tui';
+import { Type } from 'typebox';
+import type { PlanData } from '../types.js';
+
+export interface UpdateStepCallbacks {
+  getPlan: () => PlanData | undefined;
+  onStepUpdated: (step: number, status: 'done' | 'skipped' | 'blocked', notes?: string) => void;
+}
+
+export function registerUpdateStepTool(pi: ExtensionAPI, callbacks: UpdateStepCallbacks): void {
+  pi.registerTool({
+    name: 'update_step',
+    label: 'Update Step',
+    description:
+      'Mark a plan step as done, skipped, or blocked. ' +
+      'Call this after completing each step. ' +
+      'If a step is blocked, execution will pause for user intervention.',
+    promptSnippet: 'Mark a plan step as done, skipped, or blocked',
+    promptGuidelines: [
+      'Call update_step after completing each plan step to mark it done before moving to the next.',
+      'Use update_step with status "skipped" if a step is unnecessary after inspecting the code.',
+      'Use update_step with status "blocked" and explain the reason in notes if a step cannot be completed — execution will pause for user input.',
+    ],
+    parameters: Type.Object({
+      step: Type.Number({ description: 'Step number (1-indexed)' }),
+      status: StringEnum(['done', 'skipped', 'blocked'] as const),
+      notes: Type.Optional(
+        Type.String({ description: 'What was done, why skipped, or why blocked' }),
+      ),
+    }),
+
+    async execute(_toolCallId, params) {
+      const plan = callbacks.getPlan();
+      if (!plan) {
+        throw new Error('No active plan. Cannot update step.');
+      }
+
+      const stepIdx = params.step - 1;
+      if (stepIdx < 0 || stepIdx >= plan.steps.length) {
+        throw new Error(
+          `Invalid step number ${params.step}. Plan has ${plan.steps.length} steps.`,
+        );
+      }
+
+      const step = plan.steps[stepIdx];
+      if (step.status !== 'pending') {
+        throw new Error(
+          `Step ${params.step} is already "${step.status}". Only pending steps can be updated.`,
+        );
+      }
+
+      callbacks.onStepUpdated(params.step, params.status, params.notes);
+
+      const details = {
+        step: params.step,
+        status: params.status,
+        notes: params.notes,
+        description: step.description,
+      };
+
+      if (params.status === 'blocked') {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Step ${params.step} blocked. Execution paused — waiting for user input.`,
+            },
+          ],
+          details,
+          terminate: true,
+        };
+      }
+
+      // Build progress info
+      const done = plan.steps.filter((s) => s.status === 'done').length;
+      const skipped = plan.steps.filter((s) => s.status === 'skipped').length;
+      const resolved = done + skipped;
+
+      const statusEmoji = params.status === 'done' ? '✓' : '⊘';
+      let text = `${statusEmoji} Step ${params.step} ${params.status}. Progress: ${resolved}/${plan.steps.length}`;
+      if (params.notes) {
+        text += ` — ${params.notes}`;
+      }
+
+      // Find next pending step
+      const next = plan.steps.find((s) => s.status === 'pending');
+      if (next) {
+        const nextIdx = plan.steps.indexOf(next) + 1;
+        text += `\n\nNext step ${nextIdx}: ${next.description}`;
+      } else {
+        text += '\n\nAll steps resolved!';
+      }
+
+      return {
+        content: [{ type: 'text' as const, text }],
+        details,
+        // Stop the agent when all steps are done so agent_end fires immediately
+        terminate: !next,
+      };
+    },
+
+    renderCall(args, theme) {
+      const step = (args as { step?: number }).step ?? '?';
+      const status = (args as { status?: string }).status ?? '';
+      let content = theme.fg('toolTitle', theme.bold('update_step '));
+      content += theme.fg('muted', `#${step}`);
+      if (status) {
+        const color = status === 'done' ? 'success' : status === 'skipped' ? 'warning' : 'error';
+        content += ' ' + theme.fg(color, status);
+      }
+      return new Text(content, 0, 0);
+    },
+
+    renderResult(result, _options, theme) {
+      const details = result.details as {
+        step?: number;
+        status?: string;
+        description?: string;
+      } | undefined;
+
+      if (!details) {
+        return new Text(theme.fg('dim', 'Updated'), 0, 0);
+      }
+
+      const statusMap: Record<string, string> = {
+        done: theme.fg('success', '✓'),
+        skipped: theme.fg('warning', '⊘'),
+        blocked: theme.fg('error', '✗'),
+      };
+
+      const icon = statusMap[details.status ?? ''] ?? '';
+      const desc = details.description ?? '';
+      return new Text(`${icon} Step ${details.step}: ${desc}`, 0, 0);
+    },
+  });
+}