@dreki-gg/pi-plan-mode 0.20.1 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @dreki-gg/pi-plan-mode
 
+## 0.21.0
+
+### Minor Changes
+
+- Add two plan-management tools:
+
+  - `revise_plan` — sister of `submit_plan` that rewrites an existing plan in place by name. All content fields (title, handoff, tasks) are optional, so you pass only what changes. When tasks are supplied they fully replace the set, but `status` and `notes` are preserved for any task whose id is unchanged; registry status is re-derived from task state. Use when a plan was submitted prematurely and follow-up changes arrive, instead of creating a new plan.
+  - `set_active_plan` — tool form of the `/plan focus` command. Pins a plan into session state so subsequent `plan_status` / `update_task` / `add_task` calls target it. Useful when `plan_status` reports multiple in-progress plans and the agent needs to select one programmatically. Available in both plan and execution phases.
+
 ## 0.20.1
 
 ### Patch Changes

package/README.md

@@ -26,10 +26,12 @@ pi install npm:@dreki-gg/pi-questionnaire
 | Command  | `/plan focus <name>` | Pin a plan so tracking calls default to it (multi-plan repos) |
 | Command  | `/todos`       | Show current plan progress                     |
 | Shortcut | `Ctrl+Alt+P`   | Toggle plan mode                               |
+| Tool     | `revise_plan`  | Rewrite an existing plan in place (title/handoff/tasks) |
 | Tool     | `update_task`  | Mark a task done / skipped / blocked           |
 | Tool     | `update_tasks` | Mark several tasks done / skipped in one call  |
 | Tool     | `add_task`     | Capture a discovered follow-up (deferred)      |
 | Tool     | `plan_status`  | Read-only snapshot; progress table when many plans are active |
+| Tool     | `set_active_plan` | Pin a plan as active (tool form of `/plan focus`) so tracking calls target it |
 | Tool     | `update_plan`  | Close/reopen a plan: done, superseded, abandoned, in-progress |
 | Tool     | `reconcile_plans` | Detect & repair drift between tasks.jsonl and the registry |
 

package/extensions/plan-mode/__tests__/revise-plan.test.ts

@@ -0,0 +1,171 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { chdir } from 'node:process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { makePlanRuntime } from '../effects/runtime.js';
+import { registerRevisePlanTool } from '../tools/revise-plan.js';
+import { readTasksJsonl, writeTasksJsonl } from '../storage/task-storage.js';
+import { saveHandoff, loadHandoff } from '../storage/plan-storage.js';
+import { readPlansManifest, upsertPlanEntry } from '../storage/plans-manifest.js';
+import type { PlanData, TaskRecord } from '../types.js';
+
+const runPlanIO = makePlanRuntime();
+const now = '2026-05-27T12:00:00.000Z';
+
+interface CapturedTool {
+  execute: (
+    id: string,
+    params: {
+      plan: string;
+      title?: string;
+      handoff?: string;
+      tasks?: Array<{
+        id: string;
+        description: string;
+        details?: string;
+        depends_on?: string[];
+      }>;
+    },
+  ) => Promise<{ content?: Array<{ text: string }>; details?: unknown }>;
+}
+
+function setup(plan: PlanData | undefined): { tool: CapturedTool; revised: PlanData[] } {
+  let tool: CapturedTool | undefined;
+  const revised: PlanData[] = [];
+  const pi = {
+    registerTool: (config: CapturedTool) => {
+      tool = config;
+    },
+  } as unknown as Parameters<typeof registerRevisePlanTool>[0];
+
+  registerRevisePlanTool(pi, runPlanIO, {
+    resolvePlan: async () => ({ plan, candidates: plan ? [] : ['other'] }),
+    onPlanRevised: (_dir, p) => {
+      revised.push(p);
+    },
+  });
+
+  return { tool: tool!, revised };
+}
+
+const task = (id: string, over: Partial<TaskRecord> = {}): TaskRecord => ({
+  _type: 'task',
+  id,
+  description: `task ${id}`,
+  details: '',
+  status: 'pending',
+  origin: 'plan',
+  created_at: now,
+  updated_at: now,
+  ...over,
+});
+
+async function seed(plan: PlanData): Promise<void> {
+  const dir = `.plans/${plan.planName}`;
+  await runPlanIO(
+    writeTasksJsonl(
+      dir,
+      { _type: 'meta', title: plan.title, plan_name: plan.planName, created_at: now },
+      plan.tasks,
+    ),
+  );
+  await runPlanIO(saveHandoff(dir, plan.handoff));
+}
+
+const originalCwd = process.cwd();
+let dir: string;
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'plan-mode-revise-plan-'));
+  chdir(dir);
+});
+afterEach(async () => {
+  chdir(originalCwd);
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('revise_plan tool', () => {
+  test('rewrites handoff + title only, leaving tasks untouched', async () => {
+    const plan: PlanData = {
+      title: 'Old title',
+      planName: 'p',
+      handoff: 'old handoff',
+      tasks: [task('t-001'), task('t-002')],
+    };
+    await seed(plan);
+    await runPlanIO(upsertPlanEntry('p', { status: 'in-progress', title: 'Old title' }));
+
+    const { tool } = setup(plan);
+    await tool.execute('c', { plan: 'p', title: 'New title', handoff: 'new handoff' });
+
+    const snapshot = await runPlanIO(readTasksJsonl('.plans/p'));
+    expect(snapshot?.meta.title).toBe('New title');
+    expect(snapshot?.tasks.map((t) => t.id)).toEqual(['t-001', 't-002']);
+    expect(await runPlanIO(loadHandoff('.plans/p'))).toBe('new handoff');
+    const [entry] = await runPlanIO(readPlansManifest());
+    expect(entry.title).toBe('New title');
+    expect(entry.status).toBe('in-progress');
+  });
+
+  test('replaces task set but preserves status/notes for matching ids', async () => {
+    const plan: PlanData = {
+      title: 'P',
+      planName: 'p',
+      handoff: 'h',
+      tasks: [
+        task('t-001', { status: 'done', notes: 'shipped' }),
+        task('t-002', { status: 'pending' }),
+      ],
+    };
+    await seed(plan);
+    await runPlanIO(upsertPlanEntry('p', { status: 'in-progress', title: 'P' }));
+
+    const { tool } = setup(plan);
+    await tool.execute('c', {
+      plan: 'p',
+      tasks: [
+        { id: 't-001', description: 'reworded but same id' },
+        { id: 't-003', description: 'brand new task' },
+      ],
+    });
+
+    const snapshot = await runPlanIO(readTasksJsonl('.plans/p'));
+    const tasks = snapshot!.tasks;
+    expect(tasks.map((t) => t.id)).toEqual(['t-001', 't-003']);
+    const t1 = tasks.find((t) => t.id === 't-001')!;
+    expect(t1.status).toBe('done');
+    expect(t1.notes).toBe('shipped');
+    expect(t1.description).toBe('reworded but same id');
+    const t3 = tasks.find((t) => t.id === 't-003')!;
+    expect(t3.status).toBe('pending');
+  });
+
+  test('reopens an all-done plan when a pending task is added', async () => {
+    const plan: PlanData = {
+      title: 'P',
+      planName: 'p',
+      handoff: 'h',
+      tasks: [task('t-001', { status: 'done' })],
+    };
+    await seed(plan);
+    await runPlanIO(upsertPlanEntry('p', { status: 'done', title: 'P' }));
+
+    const { tool } = setup(plan);
+    await tool.execute('c', {
+      plan: 'p',
+      tasks: [
+        { id: 't-001', description: 'done one' },
+        { id: 't-002', description: 'new pending work' },
+      ],
+    });
+
+    const [entry] = await runPlanIO(readPlansManifest());
+    expect(entry.status).toBe('in-progress');
+  });
+
+  test('reports not_found for an unknown plan (no throw)', async () => {
+    const { tool } = setup(undefined);
+    const result = await tool.execute('c', { plan: 'ghost', title: 'x' });
+    expect((result.details as { error?: string }).error).toBe('not_found');
+  });
+});

package/extensions/plan-mode/__tests__/set-active-plan.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from 'bun:test';
+import { registerSetActivePlanTool } from '../tools/set-active-plan.js';
+import type { PlanData } from '../types.js';
+import type { ResolvedPlan } from '../resolve-plan.js';
+
+const now = '2026-05-27T12:00:00.000Z';
+
+interface CapturedTool {
+  execute: (
+    id: string,
+    params: { plan: string },
+  ) => Promise<{ content?: Array<{ text: string }>; details?: unknown }>;
+}
+
+function setup(resolved: ResolvedPlan): { tool: CapturedTool; requested: string[] } {
+  let tool: CapturedTool | undefined;
+  const requested: string[] = [];
+  const pi = {
+    registerTool: (config: CapturedTool) => {
+      tool = config;
+    },
+  } as unknown as Parameters<typeof registerSetActivePlanTool>[0];
+
+  registerSetActivePlanTool(pi, {
+    setActivePlan: async (name) => {
+      requested.push(name);
+      return resolved;
+    },
+  });
+
+  return { tool: tool!, requested };
+}
+
+const plan: PlanData = {
+  title: 'My Plan',
+  planName: 'my-plan',
+  handoff: '',
+  tasks: [
+    {
+      _type: 'task',
+      id: 't-001',
+      description: 'do',
+      status: 'pending',
+      created_at: now,
+      updated_at: now,
+    },
+  ],
+};
+
+describe('set_active_plan tool', () => {
+  test('pins the plan and confirms when resolution succeeds', async () => {
+    const { tool, requested } = setup({ plan, candidates: [] });
+    const result = await tool.execute('c', { plan: '.plans/my-plan' });
+
+    expect(requested).toEqual(['.plans/my-plan']);
+    const details = result.details as { active?: boolean; plan_name?: string; title?: string };
+    expect(details.active).toBe(true);
+    expect(details.plan_name).toBe('my-plan');
+    expect(details.title).toBe('My Plan');
+    expect(result.content?.[0]?.text).toMatch(/my-plan/);
+  });
+
+  test('reports not_found with candidates (no throw) when unresolved', async () => {
+    const { tool } = setup({ plan: undefined, candidates: ['alpha', 'beta'] });
+    const result = await tool.execute('c', { plan: 'ghost' });
+
+    const details = result.details as { error?: string; candidates?: string[] };
+    expect(details.error).toBe('not_found');
+    expect(details.candidates).toEqual(['alpha', 'beta']);
+    expect(result.content?.[0]?.text).toMatch(/alpha, beta/);
+  });
+});

package/extensions/plan-mode/constants.ts

@@ -10,12 +10,14 @@ export const PLAN_TOOLS = [
   'find',
   'ls',
   'submit_plan',
+  'revise_plan',
   'preview_prototype',
   'write',
   'questionnaire',
   'search_skills',
   'subagent',
   'plan_status',
+  'set_active_plan',
   'update_plan',
   'reconcile_plans',
 ];
@@ -29,6 +31,7 @@ export const EXEC_TOOLS = [
   'update_tasks',
   'add_task',
   'plan_status',
+  'set_active_plan',
   'update_plan',
   'reconcile_plans',
 ];

package/extensions/plan-mode/index.ts

@@ -38,14 +38,16 @@ import { filterExecutionMessages, filterStalePlanMessages } from './context-filt
 import { activeTasksResolved, deferredTasks, isPlanFinalizable } from './task-status.js';
 import { enterPlanMode, exitPlanMode, switchModel } from './phase-transitions.js';
 import { resumePlan, executeInNewSession } from './resume.js';
-import { resolveActivePlan } from './resolve-plan.js';
+import { resolveActivePlan, focusActivePlan } from './resolve-plan.js';
 import { collectPlanDrift } from './reconcile.js';
 import { registerSubmitPlanTool } from './tools/submit-plan.js';
+import { registerRevisePlanTool } from './tools/revise-plan.js';
 import { registerPreviewPrototypeTool } from './tools/preview-prototype.js';
 import { registerUpdateTaskTool } from './tools/update-task.js';
 import { registerUpdateTasksTool } from './tools/update-tasks.js';
 import { registerAddTaskTool } from './tools/add-task.js';
 import { registerPlanStatusTool } from './tools/plan-status.js';
+import { registerSetActivePlanTool } from './tools/set-active-plan.js';
 import { registerUpdatePlanTool } from './tools/update-plan.js';
 import { registerReconcilePlansTool } from './tools/reconcile-plans.js';
 import { isSafeCommand, isPlanPath } from './utils.js';
@@ -71,6 +73,15 @@ export default function planMode(pi: ExtensionAPI): void {
     },
   });
 
+  registerRevisePlanTool(pi, runPlanIO, {
+    resolvePlan: (opts) => resolveActivePlan(state, pi, runPlanIO, opts),
+    onPlanRevised: (dir, revisedPlan) => {
+      state.planDir = dir;
+      state.plan = revisedPlan;
+      state.persist(pi);
+    },
+  });
+
   registerPreviewPrototypeTool(pi, runPlanIO);
 
   // Shared task-write closure: mutate the in-memory task, persist tasks.jsonl,
@@ -169,6 +180,10 @@ export default function planMode(pi: ExtensionAPI): void {
     },
   });
 
+  registerSetActivePlanTool(pi, {
+    setActivePlan: (name) => focusActivePlan(state, pi, runPlanIO, name),
+  });
+
   registerUpdatePlanTool(pi, runPlanIO);
   registerReconcilePlansTool(pi, runPlanIO);
 
@@ -220,10 +235,7 @@ export default function planMode(pi: ExtensionAPI): void {
           ctx.ui.notify('Usage: /plan focus <name>', 'info');
           return;
         }
-        // Clear any stale in-memory plan so the hint re-attaches from disk.
-        state.plan = undefined;
-        state.planDir = undefined;
-        const { plan, candidates } = await resolveActivePlan(state, pi, runPlanIO, { name });
+        const { plan, candidates } = await focusActivePlan(state, pi, runPlanIO, name);
         if (plan) {
           ctx.ui.notify(`Focused plan: ${plan.title} (${plan.planName})`, 'info');
         } else {

package/extensions/plan-mode/prompts.ts

@@ -33,6 +33,8 @@ Plan weight:
 
 submit_plan is finalization, not the starting point. It records tasks and the handoff — it does not generate HTML.
 
+If a plan with the same name already exists and the user asks for follow-up changes (e.g. you submitted prematurely), call revise_plan instead of submit_plan. It rewrites the existing plan in place — pass only the fields that change (title, handoff, and/or tasks); status and notes are preserved for tasks whose id is unchanged.
+
 For visual/UI/layout/style work, build a prototype with preview_prototype DURING planning, before submit_plan, so the user can react to the visual before the plan hardens. The visual-prototype skill covers when and how.
 
 When facing a significant technical decision with multiple viable approaches (architecture, API design, implementation strategy), use the technical-options skill: you generate the competing proposals yourself, then use the subagent tool to fan out voting agents for evaluation. Do not delegate the entire workflow to a subagent — you are the planner, you drive the process.`;

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

@@ -116,3 +116,21 @@ export async function resolveActivePlan(
 
   return { plan: undefined, candidates: inProgress.map((entry) => entry.name) };
 }
+
+/**
+ * Pin a plan as the active one (the tool/command form of `/plan focus`).
+ *
+ * Clears any stale in-memory plan first so the hint always re-attaches from
+ * disk, then resolves by name. Returns the same `ResolvedPlan` shape so callers
+ * can report success or surface in-progress candidates on a miss.
+ */
+export async function focusActivePlan(
+  state: PlanModeState,
+  pi: ExtensionAPI,
+  runPlanIO: RunPlanIO,
+  name: string,
+): Promise<ResolvedPlan> {
+  state.plan = undefined;
+  state.planDir = undefined;
+  return resolveActivePlan(state, pi, runPlanIO, { name });
+}

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

@@ -49,6 +49,7 @@ export function registerPlanStatusTool(pi: ExtensionAPI, callbacks: PlanStatusCa
     promptGuidelines: [
       'Call plan_status when unsure whether a plan is active or which task ids exist — it is read-only and never mutates state.',
       'Prefer it over guessing task ids; the returned ids are what update_task expects.',
+      'When it reports multiple in-progress plans, call set_active_plan to pin one before update_task / add_task.',
     ],
     parameters: Type.Object({
       plan: Type.Optional(
@@ -74,7 +75,7 @@ export function registerPlanStatusTool(pi: ExtensionAPI, callbacks: PlanStatusCa
             })
             .join('\n');
           const text =
-            `No single active plan — ${summaries.length} in-progress. Pass { plan: "<name>" } to target one.\n` +
+            `No single active plan — ${summaries.length} in-progress. Pass { plan: "<name>" } or call set_active_plan to target one.\n` +
             `Progress:\n${rows}`;
           return {
             content: [{ type: 'text' as const, text }],

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

@@ -0,0 +1,189 @@
+/**
+ * revise_plan tool — sister of submit_plan, available during the plan phase.
+ *
+ * Re-opens an EXISTING plan by name and rewrites its contents in place. Use
+ * when a plan was submitted (often prematurely) and follow-up changes arrive:
+ * instead of creating a new plan, revise the existing one.
+ *
+ * All content fields are optional — only what you pass is overwritten. When
+ * `tasks` is supplied it fully defines the new task set (tasks not listed are
+ * dropped); for any task whose `id` matches an existing one, its `status`,
+ * `notes`, `origin`, and `created_at` are preserved so progress survives a
+ * re-plan. Registry status is then re-derived from task state.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Text } from '@earendil-works/pi-tui';
+import { Type } from 'typebox';
+import { Effect } from 'effect';
+import { saveHandoff } from '../storage/plan-storage.js';
+import { writeTasksJsonl } from '../storage/task-storage.js';
+import {
+  readPlansManifest,
+  reconcilePlanStatus,
+  upsertPlanEntry,
+} from '../storage/plans-manifest.js';
+import { isPlanFinalizable } from '../task-status.js';
+import type { RunPlanIO } from '../effects/runtime.js';
+import type { PlanData, TaskMeta, TaskRecord } from '../types.js';
+
+export interface RevisePlanCallbacks {
+  resolvePlan: (opts: { name?: string }) => Promise<{ plan?: PlanData; candidates: string[] }>;
+  onPlanRevised: (planDir: string, plan: PlanData) => void;
+}
+
+export function registerRevisePlanTool(
+  pi: ExtensionAPI,
+  runPlanIO: RunPlanIO,
+  callbacks: RevisePlanCallbacks,
+): void {
+  pi.registerTool({
+    name: 'revise_plan',
+    label: 'Revise Plan',
+    description:
+      'Rewrite an existing plan in place by name — change its title, handoff, and/or tasks. Use after submit_plan when follow-up changes arrive, instead of creating a new plan.',
+    promptSnippet: 'Rewrite an existing plan in place (title/handoff/tasks) by name',
+    promptGuidelines: [
+      'Use revise_plan instead of submit_plan when a plan with the same name already exists and the user asks for follow-up changes.',
+      'All content fields are optional — pass only what changes; omitted title/handoff/tasks are left as-is.',
+      'When you pass tasks, it fully replaces the task set (tasks you omit are dropped). Status and notes are preserved for any task whose id is unchanged.',
+    ],
+    parameters: Type.Object({
+      plan: Type.String({ description: 'Plan name (or .plans/<name>) to revise' }),
+      title: Type.Optional(Type.String({ description: 'New human-readable plan title' })),
+      handoff: Type.Optional(Type.String({ description: 'New markdown content for HANDOFF.md' })),
+      tasks: Type.Optional(
+        Type.Array(
+          Type.Object({
+            id: Type.String({ description: 'Stable task ID, e.g. t-001' }),
+            description: Type.String({
+              description: 'Short task label for progress display (≤60 chars)',
+            }),
+            details: Type.Optional(
+              Type.String({ description: 'Full implementation instructions for this task.' }),
+            ),
+            depends_on: Type.Optional(
+              Type.Array(Type.String({ description: 'Dependency task ID' })),
+            ),
+          }),
+          { minItems: 1 },
+        ),
+      ),
+    }),
+
+    async execute(_toolCallId, params) {
+      const { plan, candidates } = await callbacks.resolvePlan({ name: params.plan });
+      if (!plan) {
+        const notFound: Record<string, unknown> = {
+          error: 'not_found',
+          plan: params.plan,
+          candidates,
+        };
+        const hint = candidates.length ? ` In-progress: ${candidates.join(', ')}.` : '';
+        return {
+          content: [
+            { type: 'text' as const, text: `Plan not found: ${params.plan}.${hint}` },
+          ],
+          details: notFound,
+        };
+      }
+
+      const now = new Date().toISOString();
+      const newTitle = params.title ?? plan.title;
+      const newHandoff = params.handoff ?? plan.handoff;
+
+      let tasks = plan.tasks;
+      if (params.tasks) {
+        const previous = new Map(plan.tasks.map((task) => [task.id, task]));
+        tasks = params.tasks.map((task): TaskRecord => {
+          const existing = previous.get(task.id);
+          return {
+            _type: 'task',
+            id: task.id,
+            description: task.description.slice(0, 60),
+            details: task.details ?? '',
+            // Preserve progress for tasks whose id is unchanged.
+            status: existing?.status ?? 'pending',
+            origin: existing?.origin ?? 'plan',
+            depends_on: task.depends_on,
+            notes: existing?.notes,
+            created_at: existing?.created_at ?? now,
+            updated_at: now,
+          };
+        });
+      }
+
+      const meta: TaskMeta = {
+        _type: 'meta',
+        title: newTitle,
+        plan_name: plan.planName,
+        created_at: plan.tasks[0]?.created_at ?? now,
+      };
+      const revised: PlanData = {
+        title: newTitle,
+        planName: plan.planName,
+        handoff: newHandoff,
+        tasks,
+      };
+      const planDir = `.plans/${plan.planName}`;
+
+      await runPlanIO(
+        Effect.gen(function* () {
+          yield* writeTasksJsonl(planDir, meta, tasks);
+          yield* saveHandoff(planDir, newHandoff);
+          // Persist a title change without flipping status, then let task state
+          // re-derive in-progress ⇄ done (never clobbers superseded/abandoned).
+          const manifest = yield* readPlansManifest();
+          const current = manifest.find((entry) => entry.name === plan.planName);
+          yield* upsertPlanEntry(plan.planName, {
+            status: current?.status ?? 'in-progress',
+            title: newTitle,
+          });
+          yield* reconcilePlanStatus(plan.planName, isPlanFinalizable(tasks), newTitle);
+        }),
+      );
+
+      callbacks.onPlanRevised(planDir, revised);
+
+      const changed = [
+        params.title ? 'title' : undefined,
+        params.handoff ? 'handoff' : undefined,
+        params.tasks ? 'tasks' : undefined,
+      ].filter(Boolean);
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Plan "${newTitle}" revised (${changed.join(', ') || 'no changes'}) in ${planDir}.`,
+          },
+        ],
+        details: { planDir, plan: revised, changed },
+      };
+    },
+
+    renderCall(args, theme) {
+      const name = (args as { plan?: string }).plan ?? 'plan';
+      let content = theme.fg('toolTitle', theme.bold('revise_plan '));
+      content += theme.fg('accent', name);
+      return new Text(content, 0, 0);
+    },
+
+    renderResult(result, _options, theme) {
+      const details = result.details as
+        | { plan?: PlanData; changed?: string[] }
+        | undefined;
+      const plan = details?.plan;
+      if (!plan) return new Text(theme.fg('success', '✓ Plan revised'), 0, 0);
+      const changed = details?.changed?.length ? ` (${details.changed.join(', ')})` : '';
+      const lines = [
+        theme.fg('success', '✓ ') +
+          theme.fg('accent', theme.bold(plan.title)) +
+          theme.fg('dim', changed),
+        '',
+      ];
+      for (const task of plan.tasks)
+        lines.push(`  ${theme.fg('muted', task.id)} ${task.description}`);
+      return new Text(lines.join('\n'), 0, 0);
+    },
+  });
+}

package/extensions/plan-mode/tools/set-active-plan.ts

@@ -0,0 +1,86 @@
+/**
+ * set_active_plan tool — pin a plan as the active one.
+ *
+ * The tool-callable form of `/plan focus <name>`. Attaches the named plan into
+ * session state so subsequent plan_status / update_task / add_task calls target
+ * it. Use when plan_status reports multiple in-progress plans and the agent
+ * needs to select one programmatically instead of waiting for `/plan focus`.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Text } from '@earendil-works/pi-tui';
+import { Type } from 'typebox';
+import type { ResolvedPlan } from '../resolve-plan.js';
+
+export interface SetActivePlanCallbacks {
+  /** Pin the named plan into state (clears stale plan, re-attaches from disk). */
+  setActivePlan: (name: string) => Promise<ResolvedPlan>;
+}
+
+export function registerSetActivePlanTool(
+  pi: ExtensionAPI,
+  callbacks: SetActivePlanCallbacks,
+): void {
+  pi.registerTool({
+    name: 'set_active_plan',
+    label: 'Set Active Plan',
+    description:
+      'Pin a plan as the active one so plan_status / update_task / add_task target it. Use when multiple plans are in-progress and you need to select one.',
+    promptSnippet: 'Pin a plan as active so tracking calls target it',
+    promptGuidelines: [
+      'Call set_active_plan when plan_status reports multiple in-progress plans and you need to select one before update_task / add_task.',
+      'It is the tool form of the /plan focus command — it attaches the named plan into session state.',
+    ],
+    parameters: Type.Object({
+      plan: Type.String({ description: 'Plan name (or .plans/<name>) to pin as active' }),
+    }),
+
+    async execute(_toolCallId, params) {
+      const { plan, candidates } = await callbacks.setActivePlan(params.plan);
+      if (!plan) {
+        const hint = candidates.length ? ` In-progress: ${candidates.join(', ')}.` : '';
+        const notFound: Record<string, unknown> = {
+          error: 'not_found',
+          plan: params.plan,
+          candidates,
+        };
+        return {
+          content: [{ type: 'text' as const, text: `Plan not found: ${params.plan}.${hint}` }],
+          details: notFound,
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Active plan set to ${plan.title} (${plan.planName}).`,
+          },
+        ],
+        details: { active: true, plan_name: plan.planName, title: plan.title },
+      };
+    },
+
+    renderCall(args, theme) {
+      const name = (args as { plan?: string }).plan ?? 'plan';
+      return new Text(
+        theme.fg('toolTitle', theme.bold('set_active_plan ')) + theme.fg('accent', name),
+        0,
+        0,
+      );
+    },
+
+    renderResult(result, _options, theme) {
+      const details = result.details as
+        | { active?: boolean; plan_name?: string; title?: string }
+        | undefined;
+      if (!details?.active) return new Text(theme.fg('dim', 'No plan set'), 0, 0);
+      return new Text(
+        theme.fg('success', '✓ ') +
+          theme.fg('accent', theme.bold(details.title ?? details.plan_name ?? 'plan')),
+        0,
+        0,
+      );
+    },
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-plan-mode",
-  "version": "0.20.1",
+  "version": "0.21.0",
   "description": "Two-phase planning workflow for pi — plan with claude-opus-4-6:medium, execute with gpt-5.5:low, with .plans/ file-based handoff",
   "keywords": [
     "pi-package"