@dreki-gg/pi-plan-mode 0.17.1 → 0.19.0

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

@@ -0,0 +1,114 @@
+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 { writeTasksJsonl } from '../storage/task-storage.js';
+import {
+  readPlansManifest,
+  upsertPlanEntry,
+  writePlansManifest,
+} from '../storage/plans-manifest.js';
+import { applyReconcile, collectPlanDrift } from '../reconcile.js';
+import type { TaskMeta, TaskRecord, TaskStatus } from '../types.js';
+
+const runPlanIO = makePlanRuntime();
+const now = '2026-05-27T12:00:00.000Z';
+
+const meta = (name: string): TaskMeta => ({
+  _type: 'meta',
+  title: `Title ${name}`,
+  plan_name: name,
+  created_at: now,
+});
+const task = (id: string, status: TaskStatus = 'pending'): TaskRecord => ({
+  _type: 'task',
+  id,
+  description: `task ${id}`,
+  status,
+  origin: 'plan',
+  created_at: now,
+  updated_at: now,
+});
+
+const originalCwd = process.cwd();
+let dir: string;
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'plan-mode-reconcile-'));
+  chdir(dir);
+});
+afterEach(async () => {
+  chdir(originalCwd);
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('collectPlanDrift', () => {
+  test('flags a fully-done plan still registered in-progress as status drift', async () => {
+    await runPlanIO(writeTasksJsonl('.plans/alpha', meta('alpha'), [task('t-001', 'done')]));
+    await runPlanIO(upsertPlanEntry('alpha', { status: 'in-progress', title: 'Title alpha' }));
+
+    const rows = await runPlanIO(collectPlanDrift());
+    const alpha = rows.find((r) => r.name === 'alpha')!;
+    expect(alpha.drift).toBe('status');
+    expect(alpha.derivedStatus).toBe('done');
+    expect(alpha.resolved).toBe(1);
+    expect(alpha.total).toBe(1);
+  });
+
+  test('reports an in-sync plan with no drift', async () => {
+    await runPlanIO(writeTasksJsonl('.plans/beta', meta('beta'), [task('t-001', 'pending')]));
+    await runPlanIO(upsertPlanEntry('beta', { status: 'in-progress', title: 'Title beta' }));
+
+    const rows = await runPlanIO(collectPlanDrift());
+    expect(rows.find((r) => r.name === 'beta')!.drift).toBeUndefined();
+  });
+
+  test('flags registry-only plans (no tasks.jsonl)', async () => {
+    await runPlanIO(upsertPlanEntry('ghost', { status: 'in-progress', title: 'Ghost' }));
+    const rows = await runPlanIO(collectPlanDrift());
+    const ghost = rows.find((r) => r.name === 'ghost')!;
+    expect(ghost.drift).toBe('registry-only');
+    expect(ghost.hasTasks).toBe(false);
+  });
+
+  test('flags orphan task dirs (tasks.jsonl, no registry entry)', async () => {
+    await runPlanIO(writeTasksJsonl('.plans/orphan', meta('orphan'), [task('t-001', 'done')]));
+    const rows = await runPlanIO(collectPlanDrift());
+    const orphan = rows.find((r) => r.name === 'orphan')!;
+    expect(orphan.drift).toBe('orphan');
+  });
+
+  test('never flags a manually-closed terminal status as drift', async () => {
+    await runPlanIO(writeTasksJsonl('.plans/sup', meta('sup'), [task('t-001', 'pending')]));
+    await runPlanIO(
+      writePlansManifest([
+        {
+          _type: 'plan',
+          name: 'sup',
+          status: 'superseded',
+          title: 'Title sup',
+          created_at: now,
+          completed_at: now,
+          reason: 'absorbed',
+        },
+      ]),
+    );
+    const rows = await runPlanIO(collectPlanDrift());
+    expect(rows.find((r) => r.name === 'sup')!.drift).toBeUndefined();
+  });
+});
+
+describe('applyReconcile', () => {
+  test('repairs only status drift and projects derived status into the registry', async () => {
+    await runPlanIO(writeTasksJsonl('.plans/alpha', meta('alpha'), [task('t-001', 'done')]));
+    await runPlanIO(upsertPlanEntry('alpha', { status: 'in-progress', title: 'Title alpha' }));
+
+    const rows = await runPlanIO(collectPlanDrift());
+    const repaired = await runPlanIO(applyReconcile(rows));
+    expect(repaired.map((r) => r.name)).toEqual(['alpha']);
+
+    const [entry] = await runPlanIO(readPlansManifest());
+    expect(entry.status).toBe('done');
+  });
+});

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

@@ -0,0 +1,154 @@
+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 { writeTasksJsonl } from '../storage/task-storage.js';
+import { upsertPlanEntry } from '../storage/plans-manifest.js';
+import { saveHandoff } from '../storage/plan-storage.js';
+import { PlanModeState } from '../state.js';
+import { resolveActivePlan } from '../resolve-plan.js';
+import type { TaskMeta, TaskRecord } from '../types.js';
+
+const runPlanIO = makePlanRuntime();
+const now = '2026-05-27T12:00:00.000Z';
+
+const meta = (name: string): TaskMeta => ({
+  _type: 'meta',
+  title: `Title ${name}`,
+  plan_name: name,
+  created_at: now,
+});
+const task = (id: string): TaskRecord => ({
+  _type: 'task',
+  id,
+  description: `task ${id}`,
+  status: 'pending',
+  origin: 'plan',
+  created_at: now,
+  updated_at: now,
+});
+
+/** Minimal pi stub — `state.persist` only needs `appendEntry`. */
+function fakePi() {
+  const entries: unknown[] = [];
+  return {
+    pi: { appendEntry: (_t: string, d: unknown) => entries.push(d) },
+    entries,
+  } as unknown as {
+    pi: Parameters<typeof resolveActivePlan>[1];
+    entries: unknown[];
+  };
+}
+
+async function seedPlan(name: string, status: 'in-progress' | 'done', ids: string[]) {
+  await runPlanIO(writeTasksJsonl(`.plans/${name}`, meta(name), ids.map(task)));
+  await runPlanIO(saveHandoff(`.plans/${name}`, `# Handoff ${name}`));
+  await runPlanIO(upsertPlanEntry(name, { status, title: `Title ${name}` }));
+}
+
+const originalCwd = process.cwd();
+let dir: string;
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'plan-mode-resolve-'));
+  chdir(dir);
+});
+afterEach(async () => {
+  chdir(originalCwd);
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('resolveActivePlan', () => {
+  test('returns the in-memory plan without touching disk', async () => {
+    const state = new PlanModeState();
+    state.plan = { title: 'mem', planName: 'mem', handoff: '', tasks: [task('t-001')] };
+    const { pi } = fakePi();
+    const result = await resolveActivePlan(state, pi, runPlanIO);
+    expect(result.plan?.planName).toBe('mem');
+  });
+
+  test('auto-attaches the single in-progress plan from disk', async () => {
+    await seedPlan('alpha', 'in-progress', ['t-001', 't-002']);
+    const state = new PlanModeState();
+    const { pi } = fakePi();
+
+    const result = await resolveActivePlan(state, pi, runPlanIO);
+
+    expect(result.plan?.planName).toBe('alpha');
+    expect(result.plan?.tasks).toHaveLength(2);
+    expect(result.plan?.handoff).toBe('# Handoff alpha');
+    // Attached into state (data only — execution mode untouched).
+    expect(state.planDir).toBe('.plans/alpha');
+    expect(state.executing).toBe(false);
+  });
+
+  test('is ambiguous (no attach) when multiple plans are in-progress', async () => {
+    await seedPlan('alpha', 'in-progress', ['t-001']);
+    await seedPlan('beta', 'in-progress', ['t-001']);
+    const state = new PlanModeState();
+    const { pi } = fakePi();
+
+    const result = await resolveActivePlan(state, pi, runPlanIO);
+
+    expect(result.plan).toBeUndefined();
+    expect(result.candidates.sort()).toEqual(['alpha', 'beta']);
+    expect(state.plan).toBeUndefined();
+  });
+
+  test('an explicit name hint wins over an attached in-memory plan (FEEDBACK #7)', async () => {
+    // Two plans on disk; a *different* plan is pinned in memory.
+    await seedPlan('alpha', 'in-progress', ['t-001']);
+    await seedPlan('beta', 'in-progress', ['t-001']);
+    const state = new PlanModeState();
+    state.plan = { title: 'alpha', planName: 'alpha', handoff: '', tasks: [task('t-001')] };
+    state.planDir = '.plans/alpha';
+    const { pi } = fakePi();
+
+    // The explicit hint must re-attach beta, not silently keep alpha.
+    const result = await resolveActivePlan(state, pi, runPlanIO, { name: 'beta' });
+
+    expect(result.plan?.planName).toBe('beta');
+    expect(state.plan?.planName).toBe('beta');
+    expect(state.planDir).toBe('.plans/beta');
+  });
+
+  test('a hint matching the in-memory plan returns it without touching disk', async () => {
+    const state = new PlanModeState();
+    state.plan = { title: 'mem', planName: 'mem', handoff: '', tasks: [task('t-001')] };
+    const { pi } = fakePi();
+    const result = await resolveActivePlan(state, pi, runPlanIO, { name: 'mem' });
+    expect(result.plan?.planName).toBe('mem');
+  });
+
+  test('a name hint disambiguates among multiple in-progress plans', async () => {
+    await seedPlan('alpha', 'in-progress', ['t-001']);
+    await seedPlan('beta', 'in-progress', ['t-001']);
+    const state = new PlanModeState();
+    const { pi } = fakePi();
+
+    const result = await resolveActivePlan(state, pi, runPlanIO, { name: '.plans/beta' });
+
+    expect(result.plan?.planName).toBe('beta');
+    expect(state.planDir).toBe('.plans/beta');
+  });
+
+  test('ignores a done plan when auto-attaching', async () => {
+    await seedPlan('alpha', 'done', ['t-001']);
+    const state = new PlanModeState();
+    const { pi } = fakePi();
+
+    const result = await resolveActivePlan(state, pi, runPlanIO);
+
+    expect(result.plan).toBeUndefined();
+    expect(result.candidates).toEqual([]);
+  });
+
+  test('returns no plan + no candidates when .plans is empty', async () => {
+    const state = new PlanModeState();
+    const { pi } = fakePi();
+    const result = await resolveActivePlan(state, pi, runPlanIO);
+    expect(result.plan).toBeUndefined();
+    expect(result.candidates).toEqual([]);
+  });
+});

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

@@ -177,6 +177,25 @@ describe('plan manifest entry schema', () => {
     ).toBe(true);
   });
 
+  test('accepts terminal statuses (superseded / abandoned) with a reason', () => {
+    for (const status of ['done', 'superseded', 'abandoned'] as const) {
+      expect(
+        isOk(
+          {
+            _type: 'plan',
+            name: 'plan',
+            status,
+            title: 'Plan',
+            created_at: now,
+            completed_at: now,
+            reason: 'another plan shipped it',
+          },
+          decodePlanManifestEntry,
+        ),
+      ).toBe(true);
+    }
+  });
+
   test('rejects an invalid status', () => {
     expect(
       isOk(

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

@@ -0,0 +1,69 @@
+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 { readPlansManifest, upsertPlanEntry } from '../storage/plans-manifest.js';
+import { registerUpdatePlanTool } from '../tools/update-plan.js';
+
+const runPlanIO = makePlanRuntime();
+
+interface CapturedTool {
+  execute: (
+    id: string,
+    params: { plan: string; status: string; reason?: string },
+  ) => Promise<{ content?: Array<{ text: string }>; details?: unknown }>;
+}
+
+function setup(): CapturedTool {
+  let tool: CapturedTool | undefined;
+  const pi = {
+    registerTool: (config: CapturedTool) => {
+      tool = config;
+    },
+  } as unknown as Parameters<typeof registerUpdatePlanTool>[0];
+  registerUpdatePlanTool(pi, runPlanIO);
+  return tool!;
+}
+
+const originalCwd = process.cwd();
+let dir: string;
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'plan-mode-update-plan-'));
+  chdir(dir);
+});
+afterEach(async () => {
+  chdir(originalCwd);
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('update_plan tool', () => {
+  test('closes a plan as superseded with a reason', async () => {
+    await runPlanIO(upsertPlanEntry('p', { status: 'in-progress', title: 'P' }));
+    const tool = setup();
+    const result = await tool.execute('c', {
+      plan: 'p',
+      status: 'superseded',
+      reason: 'absorbed by q',
+    });
+    expect(result.content?.[0]?.text).toMatch(/in-progress → superseded/);
+    const [entry] = await runPlanIO(readPlansManifest());
+    expect(entry.status).toBe('superseded');
+    expect(entry.reason).toBe('absorbed by q');
+  });
+
+  test('accepts a .plans/<name> hint', async () => {
+    await runPlanIO(upsertPlanEntry('p', { status: 'in-progress', title: 'P' }));
+    const tool = setup();
+    await tool.execute('c', { plan: '.plans/p', status: 'abandoned', reason: 'rejected' });
+    const [entry] = await runPlanIO(readPlansManifest());
+    expect(entry.status).toBe('abandoned');
+  });
+
+  test('reports not_found for an unknown plan (no throw)', async () => {
+    const tool = setup();
+    const result = await tool.execute('c', { plan: 'ghost', status: 'done' });
+    expect((result.details as { error?: string }).error).toBe('not_found');
+  });
+});

package/extensions/plan-mode/__tests__/update-task.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, test } from 'bun:test';
+import { registerUpdateTaskTool } from '../tools/update-task.js';
+import type { PlanData, TaskRecord, TaskStatus } from '../types.js';
+
+const now = '2026-05-27T12:00:00.000Z';
+
+interface CapturedTool {
+  execute: (
+    id: string,
+    params: {
+      task_id: string;
+      status: 'done' | 'skipped' | 'blocked';
+      notes?: string;
+      plan?: string;
+    },
+  ) => Promise<{ content?: Array<{ text: string }>; details?: unknown; terminate?: boolean }>;
+}
+
+function setup(plan: PlanData | undefined, candidates: string[] = []) {
+  let tool: CapturedTool | undefined;
+  const updates: Array<{ taskId: string; status: string; notes?: string }> = [];
+  const pi = {
+    registerTool: (config: CapturedTool) => {
+      tool = config;
+    },
+  } as unknown as Parameters<typeof registerUpdateTaskTool>[0];
+
+  registerUpdateTaskTool(pi, {
+    resolvePlan: async () => ({ plan, candidates }),
+    onTaskUpdated: (taskId, status, notes) => {
+      const target = plan?.tasks.find((candidate) => candidate.id === taskId);
+      if (target) target.status = status;
+      updates.push({ taskId, status, notes });
+    },
+  });
+
+  return { tool: tool!, updates };
+}
+
+const basePlan = (tasks: TaskRecord[]): PlanData => ({
+  title: 'Plan',
+  planName: 'plan',
+  handoff: '',
+  tasks,
+});
+const planTask = (id: string, status: TaskStatus = 'pending'): TaskRecord => ({
+  _type: 'task',
+  id,
+  description: `task ${id}`,
+  status,
+  origin: 'plan',
+  created_at: now,
+  updated_at: now,
+});
+
+describe('update_task tool', () => {
+  test('marks a pending task and reports progress', async () => {
+    const { tool, updates } = setup(basePlan([planTask('t-001'), planTask('t-002')]));
+    const result = await tool.execute('c', { task_id: 't-001', status: 'done', notes: 'did it' });
+    expect(updates).toEqual([{ taskId: 't-001', status: 'done', notes: 'did it' }]);
+    expect(result.content?.[0]?.text).toMatch(/Progress: 1\/2/);
+  });
+
+  test('blocked terminates the turn', async () => {
+    const { tool } = setup(basePlan([planTask('t-001')]));
+    const result = await tool.execute('c', { task_id: 't-001', status: 'blocked' });
+    expect(result.terminate).toBe(true);
+  });
+
+  test('soft-skips (no throw) when there is no active plan', async () => {
+    const { tool, updates } = setup(undefined, ['alpha', 'beta']);
+    const result = await tool.execute('c', { task_id: 't-001', status: 'done' });
+    expect((result.details as { skipped?: boolean }).skipped).toBe(true);
+    expect(result.content?.[0]?.text).toMatch(/alpha, beta/);
+    expect(updates).toHaveLength(0);
+  });
+
+  test('soft result (no throw) for an unknown task id', async () => {
+    const { tool, updates } = setup(basePlan([planTask('t-001')]));
+    const result = await tool.execute('c', { task_id: 't-999', status: 'done' });
+    expect((result.details as { error?: string }).error).toBe('not_found');
+    expect(result.content?.[0]?.text).toMatch(/t-001/);
+    expect(updates).toHaveLength(0);
+  });
+
+  test('idempotent: re-marking the same status is a no-op success', async () => {
+    const { tool, updates } = setup(basePlan([planTask('t-001', 'done')]));
+    const result = await tool.execute('c', { task_id: 't-001', status: 'done' });
+    expect(result.content?.[0]?.text).toMatch(/no-op/);
+    expect(updates).toHaveLength(0);
+  });
+
+  test('corrects an already-resolved task (done → skipped) and reports it', async () => {
+    const { tool, updates } = setup(basePlan([planTask('t-001', 'done')]));
+    const result = await tool.execute('c', { task_id: 't-001', status: 'skipped' });
+    expect(updates).toEqual([{ taskId: 't-001', status: 'skipped', notes: undefined }]);
+    expect(result.content?.[0]?.text).toMatch(/corrected \(done → skipped\)/);
+  });
+
+  test('unblocks a task (blocked → done) without terminating', async () => {
+    const { tool, updates } = setup(basePlan([planTask('t-001', 'blocked')]));
+    const result = await tool.execute('c', { task_id: 't-001', status: 'done' });
+    expect(updates).toEqual([{ taskId: 't-001', status: 'done', notes: undefined }]);
+    expect(result.terminate).toBeUndefined();
+  });
+});

package/extensions/plan-mode/constants.ts

@@ -15,9 +15,22 @@ export const PLAN_TOOLS = [
   'questionnaire',
   'search_skills',
   'subagent',
+  'plan_status',
+  'update_plan',
+  'reconcile_plans',
 ];
 
-export const EXEC_TOOLS = ['read', 'bash', 'edit', 'write', 'update_task', 'add_task'];
+export const EXEC_TOOLS = [
+  'read',
+  'bash',
+  'edit',
+  'write',
+  'update_task',
+  'add_task',
+  'plan_status',
+  'update_plan',
+  'reconcile_plans',
+];
 
 // ── Model + thinking presets ─────────────────────────────────────────────────
 export const PLAN_MODEL = { provider: 'anthropic', id: 'claude-opus-4-6' } as const;

package/extensions/plan-mode/index.ts

@@ -31,17 +31,22 @@ import { PlanModeState } from './state.js';
 import { makePlanRuntime } from './effects/runtime.js';
 import { loadHandoff, readAndClearExecPending } from './storage/plan-storage.js';
 import { readTasksJsonl, writeTasksJsonl } from './storage/task-storage.js';
-import { upsertPlanEntry } from './storage/plans-manifest.js';
+import { upsertPlanEntry, reconcilePlanStatus } from './storage/plans-manifest.js';
 import { updateUI } from './ui.js';
 import { buildPlanModePrompt, buildExecutionPrompt } from './prompts.js';
 import { filterExecutionMessages, filterStalePlanMessages } from './context-filter.js';
-import { activeTasksResolved, deferredTasks } from './task-status.js';
+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 { collectPlanDrift } from './reconcile.js';
 import { registerSubmitPlanTool } from './tools/submit-plan.js';
 import { registerPreviewPrototypeTool } from './tools/preview-prototype.js';
 import { registerUpdateTaskTool } from './tools/update-task.js';
 import { registerAddTaskTool } from './tools/add-task.js';
+import { registerPlanStatusTool } from './tools/plan-status.js';
+import { registerUpdatePlanTool } from './tools/update-plan.js';
+import { registerReconcilePlansTool } from './tools/reconcile-plans.js';
 import { isSafeCommand, isPlanPath } from './utils.js';
 
 export default function planMode(pi: ExtensionAPI): void {
@@ -68,7 +73,7 @@ export default function planMode(pi: ExtensionAPI): void {
   registerPreviewPrototypeTool(pi, runPlanIO);
 
   registerUpdateTaskTool(pi, {
-    getPlan: () => state.plan,
+    resolvePlan: (opts) => resolveActivePlan(state, pi, runPlanIO, opts),
     onTaskUpdated: async (taskId, status, notes) => {
       if (!state.plan || !state.planDir) return;
       const task = state.plan.tasks.find((candidate) => candidate.id === taskId);
@@ -88,12 +93,40 @@ export default function planMode(pi: ExtensionAPI): void {
           state.plan.tasks,
         ),
       );
+      // FEEDBACK #1: registry status is a projection of task state. Re-derive it
+      // on every task write so completion is decoupled from in-session execution
+      // — cross-session / disk-tracked `update_task` now closes the plan too.
+      await runPlanIO(
+        reconcilePlanStatus(
+          state.plan.planName,
+          isPlanFinalizable(state.plan.tasks),
+          state.plan.title,
+        ),
+      );
       state.persist(pi);
     },
   });
 
+  registerPlanStatusTool(pi, {
+    resolvePlan: (opts) => resolveActivePlan(state, pi, runPlanIO, opts),
+    listInProgress: async () => {
+      const rows = await runPlanIO(collectPlanDrift());
+      return rows
+        .filter((row) => row.registryStatus === 'in-progress')
+        .map((row) => ({
+          name: row.name,
+          title: row.title ?? row.name,
+          resolved: row.resolved ?? 0,
+          total: row.total ?? 0,
+        }));
+    },
+  });
+
+  registerUpdatePlanTool(pi, runPlanIO);
+  registerReconcilePlansTool(pi, runPlanIO);
+
   registerAddTaskTool(pi, {
-    getPlan: () => state.plan,
+    resolvePlan: (opts) => resolveActivePlan(state, pi, runPlanIO, opts),
     onTaskAdded: async (task) => {
       if (!state.plan || !state.planDir) return;
       state.plan.tasks.push(task);
@@ -109,6 +142,15 @@ export default function planMode(pi: ExtensionAPI): void {
           state.plan.tasks,
         ),
       );
+      // A new deferred follow-up means the plan is no longer finalizable: re-open
+      // it in the registry if it had been auto-marked done.
+      await runPlanIO(
+        reconcilePlanStatus(
+          state.plan.planName,
+          isPlanFinalizable(state.plan.tasks),
+          state.plan.title,
+        ),
+      );
       state.persist(pi);
     },
   });
@@ -116,13 +158,33 @@ export default function planMode(pi: ExtensionAPI): void {
   // ── Commands ──────────────────────────────────────────────────────────────
   pi.registerCommand('plan', {
     description:
-      'Enter plan mode, optionally with a starting prompt. Use "/plan resume" to pick up an existing plan.',
+      'Enter plan mode, optionally with a starting prompt. "/plan resume" picks up an existing plan; "/plan focus <name>" pins the active plan for tracking calls.',
     handler: async (args, ctx) => {
       const trimmed = args?.trim();
       if (trimmed === 'resume') {
         await resumePlan(state, pi, ctx, runPlanIO);
         return;
       }
+      // "/plan focus <name>" — pin a plan so update_task / add_task / plan_status
+      // default to it without repeating { plan: "<name>" } on every call (#5).
+      if (trimmed?.startsWith('focus')) {
+        const name = trimmed.slice('focus'.length).trim();
+        if (!name) {
+          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 });
+        if (plan) {
+          ctx.ui.notify(`Focused plan: ${plan.title} (${plan.planName})`, 'info');
+        } else {
+          const hint = candidates.length ? ` In-progress: ${candidates.join(', ')}.` : '';
+          ctx.ui.notify(`No plan named "${name}".${hint}`, 'error');
+        }
+        return;
+      }
       if (state.planEnabled || state.executing) {
         await exitPlanMode(state, pi, ctx);
         return;
@@ -477,6 +539,14 @@ export default function planMode(pi: ExtensionAPI): void {
       }
     }
 
+    // No plan attached from this session's entries or the exec handoff, but a
+    // plan may exist on disk (planning happened in another session). Attach the
+    // single in-progress plan so update_task / add_task work without an
+    // interactive /plan resume. Data only — does NOT enter execution mode.
+    if (!state.plan) {
+      await resolveActivePlan(state, pi, runPlanIO);
+    }
+
     // Apply tool restrictions, model, and thinking level
     if (state.planEnabled) {
       pi.setActiveTools(PLAN_TOOLS);