@dreki-gg/pi-plan-mode 0.26.2 → 0.27.3

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @dreki-gg/pi-plan-mode
 
+## 0.27.3
+
+### Patch Changes
+
+- Require an explicit plan id on plan mutations so writes always target the intended plan.
+
+## 0.27.2
+
+### Patch Changes
+
+- `add_task` now rejects an empty or whitespace `plan` argument instead of
+  silently filing the follow-up onto whatever plan happens to be in-progress.
+  This prevents discovered tasks from being misfiled onto an unrelated plan
+  after a context switch — the agent is told to re-issue with an explicit plan.
+
+## 0.27.1
+
+### Patch Changes
+
+- Require an explicit `plan` argument on `add_task`, `update_task`, and `update_tasks` so writes are always scoped to the intended plan and can never be misfiled into whatever plan happened to be the active pin. Previously these tools would trust a stale in-memory active-plan pin (or silently fall back to some other in-progress plan) after the pinned plan finished, causing follow-ups to be filed against the wrong plan.
+
+  In addition, `resolveActivePlan` now drops a stale pin and reports the in-progress candidates instead of guessing when a pinned plan has completed while other plans are still in-progress. The pin is still honored when no other plan is in-progress.
+
+## 0.27.0
+
+### Minor Changes
+
+- Plan mode no longer overrides the model or thinking level. Entering plan mode,
+  starting execution, and session restore all keep whatever model and thinking
+  level the user had active. The forced executor model picker is also removed.
+  Additionally, plan mode now auto-exits after the agent submits a plan or
+  initiative, returning the user to normal mode immediately.
+
 ## 0.26.2
 
 ### Patch Changes

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

@@ -62,6 +62,7 @@ describe('add_task tool', () => {
     await tool.execute('call-1', {
       description: 'Extract shared helper',
       reason: 'noticed duplication while editing',
+      plan: 'plan',
     });
 
     expect(added).toHaveLength(1);
@@ -73,11 +74,23 @@ describe('add_task tool', () => {
     expect(task.description).toBe('Extract shared helper');
   });
 
-  test('soft-skips (does not throw) when there is no active plan', async () => {
+  test('soft-skips (does not throw) when the named plan cannot be resolved', async () => {
     const { tool, added } = setup(undefined);
-    const result = await tool.execute('call-1', { description: 'x', reason: 'y' });
+    const result = await tool.execute('call-1', { description: 'x', reason: 'y', plan: 'plan' });
     expect((result.details as { skipped?: boolean }).skipped).toBe(true);
     expect(result.content?.[0]?.text).toMatch(/no active plan/i);
     expect(added).toHaveLength(0);
   });
+
+  test('throws when { plan } is missing or whitespace', async () => {
+    const plan = basePlan([planTask('t-001')]);
+    const { tool, added } = setup(plan);
+    await expect(tool.execute('call-1', { description: 'x', reason: 'y' })).rejects.toThrow(
+      /requires an explicit \{ plan \}/,
+    );
+    await expect(
+      tool.execute('call-2', { description: 'x', reason: 'y', plan: '   ' }),
+    ).rejects.toThrow(/requires an explicit \{ plan \}/);
+    expect(added).toHaveLength(0);
+  });
 });

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

@@ -133,6 +133,36 @@ describe('resolveActivePlan', () => {
     expect(state.planDir).toBe('.plans/beta');
   });
 
+  test('refuses a stale in-memory pin when other plans are in-progress (misfile guard)', async () => {
+    // The pinned plan has completed; two unrelated plans are still in-progress.
+    await seedPlan('alpha', 'done', ['t-001']);
+    await seedPlan('beta', 'in-progress', ['t-001']);
+    await seedPlan('gamma', '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();
+
+    const result = await resolveActivePlan(state, pi, runPlanIO);
+
+    // Must NOT silently file into the stale pin or guess one of the others.
+    expect(result.plan).toBeUndefined();
+    expect(result.candidates.sort()).toEqual(['beta', 'gamma']);
+  });
+
+  test('keeps a stale in-memory pin when no other plan is in-progress', async () => {
+    // Pin completed, nothing else live → safe to keep using it (no ambiguity).
+    await seedPlan('alpha', 'done', ['t-001']);
+    const state = new PlanModeState();
+    state.plan = { title: 'alpha', planName: 'alpha', handoff: '', tasks: [task('t-001')] };
+    state.planDir = '.plans/alpha';
+    const { pi } = fakePi();
+
+    const result = await resolveActivePlan(state, pi, runPlanIO);
+
+    expect(result.plan?.planName).toBe('alpha');
+  });
+
   test('ignores a done plan when auto-attaching', async () => {
     await seedPlan('alpha', 'done', ['t-001']);
     const state = new PlanModeState();

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

@@ -206,4 +206,16 @@ describe('revise_plan tool', () => {
     const [entry] = await runPlanIO(readPlansManifest());
     expect(entry.initiative).toBe('big');
   });
+
+  test('throws when { plan } is empty or whitespace', async () => {
+    const plan: PlanData = { title: 'P', planName: 'p', handoff: 'h', tasks: [task('t-001')] };
+    const { tool, revised } = setup(plan);
+    await expect(tool.execute('c', { plan: '', title: 'x' })).rejects.toThrow(
+      /requires an explicit \{ plan \}/,
+    );
+    await expect(tool.execute('c', { plan: '   ', title: 'x' })).rejects.toThrow(
+      /requires an explicit \{ plan \}/,
+    );
+    expect(revised).toHaveLength(0);
+  });
 });

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

@@ -56,20 +56,25 @@ const planTask = (id: string, status: TaskStatus = 'pending'): TaskRecord => ({
 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' });
+    const result = await tool.execute('c', {
+      task_id: 't-001',
+      status: 'done',
+      notes: 'did it',
+      plan: 'plan',
+    });
     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' });
+    const result = await tool.execute('c', { task_id: 't-001', status: 'blocked', plan: 'plan' });
     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' });
+    const result = await tool.execute('c', { task_id: 't-001', status: 'done', plan: 'plan' });
     expect((result.details as { skipped?: boolean }).skipped).toBe(true);
     expect(result.content?.[0]?.text).toMatch(/alpha, beta/);
     expect(updates).toHaveLength(0);
@@ -77,7 +82,7 @@ describe('update_task tool', () => {
 
   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' });
+    const result = await tool.execute('c', { task_id: 't-999', status: 'done', plan: 'plan' });
     expect((result.details as { error?: string }).error).toBe('not_found');
     expect(result.content?.[0]?.text).toMatch(/t-001/);
     expect(updates).toHaveLength(0);
@@ -85,22 +90,33 @@ describe('update_task tool', () => {
 
   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' });
+    const result = await tool.execute('c', { task_id: 't-001', status: 'done', plan: 'plan' });
     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' });
+    const result = await tool.execute('c', { task_id: 't-001', status: 'skipped', plan: 'plan' });
     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' });
+    const result = await tool.execute('c', { task_id: 't-001', status: 'done', plan: 'plan' });
     expect(updates).toEqual([{ taskId: 't-001', status: 'done', notes: undefined }]);
     expect(result.terminate).toBeUndefined();
   });
+
+  test('throws when { plan } is missing or whitespace', async () => {
+    const { tool, updates } = setup(basePlan([planTask('t-001')]));
+    await expect(tool.execute('c', { task_id: 't-001', status: 'done' })).rejects.toThrow(
+      /requires an explicit \{ plan \}/,
+    );
+    await expect(
+      tool.execute('c', { task_id: 't-001', status: 'done', plan: '   ' }),
+    ).rejects.toThrow(/requires an explicit \{ plan \}/);
+    expect(updates).toHaveLength(0);
+  });
 });

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

@@ -66,6 +66,7 @@ describe('update_tasks tool', () => {
         { task_id: 't-001', status: 'done', notes: 'a' },
         { task_id: 't-002', status: 'skipped', notes: 'b' },
       ],
+      plan: 'plan',
     });
     expect(updates).toEqual([
       { taskId: 't-001', status: 'done', notes: 'a' },
@@ -79,7 +80,10 @@ describe('update_tasks tool', () => {
 
   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', { updates: [{ task_id: 't-001', status: 'done' }] });
+    const result = await tool.execute('c', {
+      updates: [{ task_id: 't-001', status: 'done' }],
+      plan: 'plan',
+    });
     expect((result.details as { skipped?: boolean }).skipped).toBe(true);
     expect(result.content?.[0]?.text).toMatch(/alpha, beta/);
     expect(updates).toHaveLength(0);
@@ -92,6 +96,7 @@ describe('update_tasks tool', () => {
         { task_id: 't-001', status: 'done' },
         { task_id: 't-999', status: 'done' },
       ],
+      plan: 'plan',
     });
     expect(getWriteCount()).toBe(0);
   });
@@ -103,6 +108,7 @@ describe('update_tasks tool', () => {
         { task_id: 't-001', status: 'done' },
         { task_id: 't-999', status: 'done' },
       ],
+      plan: 'plan',
     });
     expect(updates).toEqual([{ taskId: 't-001', status: 'done', notes: undefined }]);
     const details = result.details as { results?: Array<{ task_id: string; outcome: string }> };
@@ -116,6 +122,7 @@ describe('update_tasks tool', () => {
         { task_id: 't-001', status: 'done' },
         { task_id: 't-002', status: 'done' },
       ],
+      plan: 'plan',
     });
     expect(updates).toEqual([{ taskId: 't-002', status: 'done', notes: undefined }]);
     const details = result.details as { results?: Array<{ task_id: string; outcome: string }> };
@@ -124,7 +131,21 @@ describe('update_tasks tool', () => {
 
   test('corrects an already-resolved task (done → skipped)', async () => {
     const { tool, updates } = setup(basePlan([planTask('t-001', 'done')]));
-    await tool.execute('c', { updates: [{ task_id: 't-001', status: 'skipped' }] });
+    await tool.execute('c', {
+      updates: [{ task_id: 't-001', status: 'skipped' }],
+      plan: 'plan',
+    });
     expect(updates).toEqual([{ taskId: 't-001', status: 'skipped', notes: undefined }]);
   });
+
+  test('throws when { plan } is missing or whitespace', async () => {
+    const { tool, updates } = setup(basePlan([planTask('t-001')]));
+    await expect(
+      tool.execute('c', { updates: [{ task_id: 't-001', status: 'done' }] }),
+    ).rejects.toThrow(/requires an explicit \{ plan \}/);
+    await expect(
+      tool.execute('c', { updates: [{ task_id: 't-001', status: 'done' }], plan: '   ' }),
+    ).rejects.toThrow(/requires an explicit \{ plan \}/);
+    expect(updates).toHaveLength(0);
+  });
 });

package/extensions/plan-mode/constants.ts

@@ -41,18 +41,5 @@ export const EXEC_TOOLS = [
   'reconcile_plans',
 ];
 
-// ── Model + thinking presets ─────────────────────────────────────────────────
-export const PLAN_MODEL = { provider: 'anthropic', id: 'claude-opus-4-6' } as const;
-export const PLAN_THINKING = 'medium' as const;
-
-export const EXEC_MODEL = { provider: 'openai', id: 'gpt-5.5' } as const;
-export const EXEC_THINKING = 'low' as const;
-
 // ── Exec-pending marker file name ────────────────────────────────────────────
 export const EXEC_PENDING_FILE = '.exec-pending.json';
-
-// ── Execution model picker options ───────────────────────────────────────────
-export const EXEC_MODEL_OPTIONS: { label: string; model: { provider: string; id: string } }[] = [
-  { label: 'gpt-5.5', model: { provider: 'openai', id: 'gpt-5.5' } },
-  { label: 'claude-opus-4-6', model: { provider: 'anthropic', id: 'claude-opus-4-6' } },
-];

package/extensions/plan-mode/index.ts

@@ -21,12 +21,8 @@ import { Key } from '@earendil-works/pi-tui';
 import {
   PLAN_TOOLS,
   EXEC_TOOLS,
-  PLAN_MODEL,
-  PLAN_THINKING,
-  EXEC_MODEL,
-  EXEC_THINKING,
 } from './constants.js';
-import type { ThinkingLevel, TaskStatus } from './types.js';
+import type { TaskStatus } from './types.js';
 import { PlanModeState } from './state.js';
 import { makePlanRuntime } from '@dreki-gg/taskman';
 import { loadHandoff } from '@dreki-gg/taskman';
@@ -524,11 +520,10 @@ export default function planMode(pi: ExtensionAPI): void {
           { triggerTurn: false },
         );
 
-        const { previousModel: dpm, previousThinking: dpt } = state;
+        const { previousModel: dpm } = state;
         state.exitPreservingPlan();
         pi.setActiveTools(EXEC_TOOLS);
         if (dpm) await switchModel(pi, ctx, dpm);
-        if (dpt) pi.setThinkingLevel(dpt);
         updateUI(state, ctx);
         state.persist(pi);
         return;
@@ -587,11 +582,10 @@ export default function planMode(pi: ExtensionAPI): void {
           { triggerTurn: false },
         );
 
-        const { previousModel: pm, previousThinking: pt } = state;
+        const { previousModel: pm } = state;
         state.reset();
         pi.setActiveTools(EXEC_TOOLS);
         if (pm) await switchModel(pi, ctx, pm);
-        if (pt) pi.setThinkingLevel(pt);
         updateUI(state, ctx);
         state.persist(pi);
         return;
@@ -599,8 +593,11 @@ export default function planMode(pi: ExtensionAPI): void {
       return;
     }
 
-    // Plan submitted — user can /plan-exec or type naturally.
-    // No menu needed: plan.jsonl + HANDOFF.md are the source of truth.
+    // Auto-exit plan mode after plan/initiative submission so the user
+    // returns to normal mode with their original model.
+    if (state.planEnabled) {
+      await exitPlanMode(state, pi, ctx);
+    }
   });
 
   // ── Event: session restore ────────────────────────────────────────────────
@@ -636,7 +633,7 @@ export default function planMode(pi: ExtensionAPI): void {
         state.planEnabled = false;
         pi.setActiveTools(EXEC_TOOLS);
         await switchModel(pi, ctx, pending.config.model);
-        pi.setThinkingLevel(pending.config.thinking as ThinkingLevel);
+
         updateUI(state, ctx);
         state.persist(pi);
         return;
@@ -651,15 +648,11 @@ export default function planMode(pi: ExtensionAPI): void {
       await resolveActivePlan(state, pi, runPlanIO);
     }
 
-    // Apply tool restrictions, model, and thinking level
+    // Apply tool restrictions (no model/thinking override — keep user's settings)
     if (state.planEnabled) {
       pi.setActiveTools(PLAN_TOOLS);
-      await switchModel(pi, ctx, PLAN_MODEL);
-      pi.setThinkingLevel(PLAN_THINKING);
     } else if (state.executing) {
       pi.setActiveTools(EXEC_TOOLS);
-      await switchModel(pi, ctx, EXEC_MODEL);
-      pi.setThinkingLevel(EXEC_THINKING);
     }
 
     updateUI(state, ctx);

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

@@ -4,14 +4,9 @@
 
 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';
 
@@ -42,12 +37,9 @@ export async function enterPlanMode(
   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');
+  ctx.ui.notify('Plan mode ON', 'info');
   updateUI(state, ctx);
   state.persist(pi);
 }
@@ -57,16 +49,13 @@ export async function exitPlanMode(
   pi: ExtensionAPI,
   ctx: ExtensionContext,
 ): Promise<void> {
-  const { previousModel, previousThinking } = state;
+  const { previousModel } = state;
   state.exitPreservingPlan();
   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');
+  ctx.ui.notify('Plan mode OFF', 'info');
   updateUI(state, ctx);
   state.persist(pi);
 }
@@ -80,12 +69,7 @@ export async function startExecution(
   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',
-  );
+  ctx.ui.notify('Executing plan', 'info');
   updateUI(state, ctx);
   state.persist(pi);
 }

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

@@ -106,10 +106,27 @@ export async function resolveActivePlan(
   }
 
   // ── No hint: in-memory plan, else the single in-progress plan on disk ─────
-  if (state.plan) return { plan: state.plan, candidates: [] };
-
+  //
+  // IMPORTANT (misfile guard): a pinned `state.plan` must NOT be trusted blindly
+  // when it no longer corresponds to an in-progress plan. After a plan completes
+  // (e.g. `set_active_plan` then 6/6 done), a stale pin would silently capture
+  // writes — or the fallback would guess a different in-progress plan. Mirror
+  // `update_task`'s strictness: when the pin is stale AND other plans are still
+  // in-progress, REFUSE and force an explicit `{ plan }` rather than guess.
   const manifest = await runPlanIO(readPlansManifest());
   const inProgress = manifest.filter((entry) => entry.status === 'in-progress');
+
+  if (state.plan) {
+    const pinName = state.plan.planName;
+    const pinInProgress = inProgress.some((entry) => entry.name === pinName);
+    const competing = inProgress.filter((entry) => entry.name !== pinName);
+    // Trust the pin only when it is still in-progress, or when there is no other
+    // in-progress plan to confuse it with (e.g. an in-memory-only plan).
+    if (pinInProgress || competing.length === 0) return { plan: state.plan, candidates: [] };
+    // Stale pin with live competitors → ambiguous: require an explicit choice.
+    return { plan: undefined, candidates: inProgress.map((entry) => entry.name) };
+  }
+
   if (inProgress.length === 1) {
     const plan = await attach(state, pi, runPlanIO, inProgress[0]!.name);
     if (plan) return { plan, candidates: [] };

package/extensions/plan-mode/resume.ts

@@ -4,13 +4,12 @@
 
 import type {
   ExtensionAPI,
-  ExtensionContext,
   ExtensionCommandContext,
 } from '@earendil-works/pi-coding-agent';
 import type { PlanModeState } from './state.js';
 import type { PlanData } from './types.js';
 import type { RunPlanIO } from '@dreki-gg/taskman';
-import { EXEC_THINKING, EXEC_MODEL_OPTIONS } from './constants.js';
+
 import { readPlansManifest } from '@dreki-gg/taskman';
 import { loadHandoff } from '@dreki-gg/taskman';
 import { writeExecPending } from './exec-pending.js';
@@ -18,15 +17,6 @@ import { readTasksJsonl, writeTasksJsonl } from '@dreki-gg/taskman';
 import { enterPlanMode } from './phase-transitions.js';
 import { reactivateForExecution } from '@dreki-gg/taskman';
 
-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,
   runPlanIO: RunPlanIO,
@@ -34,10 +24,12 @@ export async function executeInNewSession(
   _planData: PlanData,
   kickoff: string,
 ): Promise<void> {
-  const selectedModel = await pickExecutionModel(ctx);
-  if (!selectedModel) return;
+  // Use the current model for execution — no forced model override.
+  const currentModel = ctx.model
+    ? { provider: ctx.model.provider, id: ctx.model.id }
+    : { provider: 'anthropic', id: 'claude-sonnet-4-20250514' };
 
-  await runPlanIO(writeExecPending(dir, { model: selectedModel, thinking: EXEC_THINKING }));
+  await runPlanIO(writeExecPending(dir, { model: currentModel, thinking: 'low' }));
   const parentSession = ctx.sessionManager.getSessionFile();
 
   await ctx.newSession({

package/extensions/plan-mode/state.ts

@@ -3,7 +3,7 @@
  */
 
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-import type { PlanData, PersistedState, ThinkingLevel } from './types.js';
+import type { PlanData, PersistedState } from './types.js';
 
 export class PlanModeState {
   planEnabled = false;
@@ -11,7 +11,6 @@ export class PlanModeState {
   planDir: string | undefined;
   plan: PlanData | undefined;
   executionStartIdx: number | undefined;
-  previousThinking: ThinkingLevel | undefined;
   previousModel: { provider: string; id: string } | undefined;
 
   persist(pi: ExtensionAPI): void {

package/extensions/plan-mode/tools/add-task.ts

@@ -30,6 +30,7 @@ export function registerAddTaskTool(pi: ExtensionAPI, callbacks: AddTaskCallback
       'Use add_task when you notice worthwhile work outside the current plan while implementing.',
       'Discovered tasks are deferred for the user to review — do NOT implement them now; continue with the planned tasks.',
       'Give a clear reason so the user can decide whether the follow-up is worth doing.',
+      'Always pass an explicit { plan } (it is required) so the write is scoped to the intended plan — never rely on an implicit active-plan pin, which may have completed after a context switch.',
     ],
     parameters: Type.Object({
       description: Type.String({ description: 'Short task label (≤60 chars)' }),
@@ -40,15 +41,23 @@ export function registerAddTaskTool(pi: ExtensionAPI, callbacks: AddTaskCallback
         Type.String({ description: 'Optional fuller implementation notes for the follow-up' }),
       ),
       depends_on: Type.Optional(Type.Array(Type.String({ description: 'Dependency task ID' }))),
-      plan: Type.Optional(
-        Type.String({
-          description:
-            'Plan name (or .plans/<name>) to target. Only needed to disambiguate when multiple plans are in-progress.',
-        }),
-      ),
+      plan: Type.String({
+        description:
+          'Plan name (or .plans/<name>) to target. Required — always scope the capture explicitly so it never lands in the wrong plan.',
+      }),
     }),
 
     async execute(_toolCallId, params) {
+      // Hard-require an explicit plan: the schema marks it required, but an
+      // empty/whitespace value must never fall through to candidate resolution
+      // (that silently files the follow-up onto whatever plan happens to be
+      // in-progress — e.g. after the intended plan completed on a context
+      // switch). Throw so the agent re-issues with an explicit { plan }.
+      if (!params.plan || !params.plan.trim()) {
+        throw new Error(
+          'add_task requires an explicit { plan } — pass the plan name so the follow-up is never misfiled onto an unrelated in-progress plan.',
+        );
+      }
       const { plan, candidates } = await callbacks.resolvePlan({ name: params.plan });
       // No active plan is a tracking miss, not an error — return a soft,
       // non-terminating result so real work continues.

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

@@ -83,6 +83,15 @@ export function registerRevisePlanTool(
     }),
 
     async execute(_toolCallId, params) {
+      // Hard-require an explicit plan: an empty/whitespace value must never fall
+      // through to candidate resolution (that silently rewrites whatever plan
+      // happens to be in-progress — e.g. after the intended plan completed on a
+      // context switch). Throw so the agent re-issues with an explicit { plan }.
+      if (!params.plan || !params.plan.trim()) {
+        throw new Error(
+          'revise_plan requires an explicit { plan } — pass the plan name so the rewrite is never applied to an unrelated in-progress plan.',
+        );
+      }
       const { plan, candidates } = await callbacks.resolvePlan({ name: params.plan });
       if (!plan) {
         const notFound: Record<string, unknown> = {

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

@@ -35,6 +35,7 @@ export function registerUpdateTaskTool(pi: ExtensionAPI, callbacks: UpdateTaskCa
       'Call update_task after completing each plan task before moving to the next.',
       'Always include notes summarizing what was done, why skipped, or why blocked.',
       'Use update_task with status "blocked" and explain the reason in notes if a task cannot be completed.',
+      'Always pass an explicit { plan } (it is required) so the write is scoped to the intended plan — never rely on an implicit active-plan pin, which may have completed after a context switch.',
     ],
     parameters: Type.Object({
       task_id: Type.String({ description: 'Task ID (for example, t-001)' }),
@@ -42,15 +43,22 @@ export function registerUpdateTaskTool(pi: ExtensionAPI, callbacks: UpdateTaskCa
       notes: Type.Optional(
         Type.String({ description: 'What was done, why skipped, or why blocked' }),
       ),
-      plan: Type.Optional(
-        Type.String({
-          description:
-            'Plan name (or .plans/<name>) to target. Only needed to disambiguate when multiple plans are in-progress; otherwise the active / sole in-progress plan is used.',
-        }),
-      ),
+      plan: Type.String({
+        description:
+          'Plan name (or .plans/<name>) to target. Required — always scope the write explicitly so it never lands in the wrong plan.',
+      }),
     }),
 
     async execute(_toolCallId, params) {
+      // Hard-require an explicit plan: an empty/whitespace value must never fall
+      // through to candidate resolution (that silently writes to whatever plan
+      // happens to be in-progress — e.g. after the intended plan completed on a
+      // context switch). Throw so the agent re-issues with an explicit { plan }.
+      if (!params.plan || !params.plan.trim()) {
+        throw new Error(
+          'update_task requires an explicit { plan } — pass the plan name so the write is never applied to an unrelated in-progress plan.',
+        );
+      }
       const { plan, candidates } = await callbacks.resolvePlan({ name: params.plan });
       // No active plan is a tracking miss, not an error: return a soft result
       // (non-terminating) so the agent keeps doing the real work.

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

@@ -69,15 +69,22 @@ export function registerUpdateTasksTool(pi: ExtensionAPI, callbacks: UpdateTasks
         }),
         { description: 'Tasks to mark, each with its own status and notes', minItems: 1 },
       ),
-      plan: Type.Optional(
-        Type.String({
-          description:
-            'Plan name (or .plans/<name>) to target. Only needed to disambiguate when multiple plans are in-progress; otherwise the active / sole in-progress plan is used.',
-        }),
-      ),
+      plan: Type.String({
+        description:
+          'Plan name (or .plans/<name>) to target. Required — always scope the write explicitly so it never lands in the wrong plan.',
+      }),
     }),
 
     async execute(_toolCallId, params) {
+      // Hard-require an explicit plan: an empty/whitespace value must never fall
+      // through to candidate resolution (that silently writes to whatever plan
+      // happens to be in-progress — e.g. after the intended plan completed on a
+      // context switch). Throw so the agent re-issues with an explicit { plan }.
+      if (!params.plan || !params.plan.trim()) {
+        throw new Error(
+          'update_tasks requires an explicit { plan } — pass the plan name so the writes are never applied to an unrelated in-progress plan.',
+        );
+      }
       const { plan, candidates } = await callbacks.resolvePlan({ name: params.plan });
       // No active plan is a tracking miss, not an error: return a soft result
       // (non-terminating) so the agent keeps doing the real work.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-plan-mode",
-  "version": "0.26.2",
+  "version": "0.27.3",
   "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"
@@ -9,12 +9,12 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/dreki-gg/pi-extensions",
+    "url": "git+https://github.com/dreki-gg/pi-extensions.git",
     "directory": "packages/plan-mode"
   },
   "type": "module",
   "bin": {
-    "pi-plan-mode": "./bin/clean-plans.js"
+    "pi-plan-mode": "bin/clean-plans.js"
   },
   "files": [
     "extensions",