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

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @dreki-gg/pi-plan-mode
 
+## 0.18.0
+
+### Minor Changes
+
+- Make `update_task` / `add_task` usable across sessions and resilient for autonomous agents.
+
+  The active plan was session-scoped: `update_task` / `add_task` only worked when a plan was submitted in the same session, restored from its entries, or handed off via the one-shot exec-pending marker. An agent executing an existing `.plans/<name>/` in a fresh session (the common plan-here / execute-there flow) hit a hard `No active plan` throw.
+
+  - **Disk-backed resolution** (`resolveActivePlan`): when nothing is attached in memory, the active plan is resolved from `.plans/plans.jsonl` — the sole in-progress plan auto-attaches (data only; does NOT enter execution mode / change tools / model). Wired into `session_start` and both tracking tools.
+  - **No hard throws on tracking calls**: `update_task` / `add_task` now return soft, non-terminating results (no active plan, unknown task id, already-resolved task) so a tracking miss never derails the real work. `update_task` is idempotent — re-marking the same status is a no-op success.
+  - **`plan` parameter**: both tools accept an optional `plan` (name or `.plans/<name>`) to disambiguate without the interactive `/plan resume` when multiple plans are in-progress.
+  - **`update_task` corrections**: a different status on an already-resolved task now applies as a correction (e.g. `done`→`skipped`, or `blocked`→`done` to unblock) and is reported as such, instead of being refused.
+  - **New `plan_status` tool**: read-only snapshot of the active plan — progress counts + every task id/status — so an agent can check what's active and which ids are valid (disk-backed; works in a fresh execution session) instead of probing with a failing `update_task`. Added to both tool sets.
+
 ## 0.17.1
 
 ### Patch Changes

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

@@ -7,8 +7,14 @@ const now = '2026-05-27T12:00:00.000Z';
 interface CapturedTool {
   execute: (
     id: string,
-    params: { description: string; reason: string; details?: string; depends_on?: string[] },
-  ) => Promise<{ details?: unknown }>;
+    params: {
+      description: string;
+      reason: string;
+      details?: string;
+      depends_on?: string[];
+      plan?: string;
+    },
+  ) => Promise<{ content?: Array<{ text: string }>; details?: unknown }>;
 }
 
 function setup(plan: PlanData | undefined) {
@@ -21,7 +27,8 @@ function setup(plan: PlanData | undefined) {
   } as unknown as Parameters<typeof registerAddTaskTool>[0];
 
   registerAddTaskTool(pi, {
-    getPlan: () => plan,
+    // Mirrors index.ts: in-memory plan wins; disk fallback returns candidates.
+    resolvePlan: async () => ({ plan, candidates: [] }),
     onTaskAdded: (task) => {
       added.push(task);
     },
@@ -66,10 +73,11 @@ describe('add_task tool', () => {
     expect(task.description).toBe('Extract shared helper');
   });
 
-  test('throws when there is no active plan', async () => {
-    const { tool } = setup(undefined);
-    await expect(tool.execute('call-1', { description: 'x', reason: 'y' })).rejects.toThrow(
-      /No active plan/,
-    );
+  test('soft-skips (does not throw) when there is no active plan', async () => {
+    const { tool, added } = setup(undefined);
+    const result = await tool.execute('call-1', { description: 'x', reason: 'y' });
+    expect((result.details as { skipped?: boolean }).skipped).toBe(true);
+    expect(result.content?.[0]?.text).toMatch(/no active plan/i);
+    expect(added).toHaveLength(0);
   });
 });

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

@@ -0,0 +1,68 @@
+import { describe, expect, test } from 'bun:test';
+import { registerPlanStatusTool } from '../tools/plan-status.js';
+import type { PlanData, TaskRecord, TaskStatus } from '../types.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(plan: PlanData | undefined, candidates: string[] = []) {
+  let tool: CapturedTool | undefined;
+  const pi = {
+    registerTool: (config: CapturedTool) => {
+      tool = config;
+    },
+  } as unknown as Parameters<typeof registerPlanStatusTool>[0];
+  registerPlanStatusTool(pi, { resolvePlan: async () => ({ plan, candidates }) });
+  return tool!;
+}
+
+const planTask = (id: string, status: TaskStatus): TaskRecord => ({
+  _type: 'task',
+  id,
+  description: `task ${id}`,
+  status,
+  origin: 'plan',
+  created_at: now,
+  updated_at: now,
+});
+
+describe('plan_status tool', () => {
+  test('summarizes progress + lists task ids and statuses', async () => {
+    const plan: PlanData = {
+      title: 'My Plan',
+      planName: 'my-plan',
+      handoff: '',
+      tasks: [
+        planTask('t-001', 'done'),
+        planTask('t-002', 'pending'),
+        planTask('t-003', 'blocked'),
+      ],
+    };
+    const tool = setup(plan);
+    const result = await tool.execute('c', {});
+
+    const text = result.content?.[0]?.text ?? '';
+    expect(text).toMatch(/My Plan \(my-plan\)/);
+    expect(text).toMatch(/1\/3 resolved/);
+    expect(text).toMatch(/blocked 1/);
+    expect(text).toMatch(/t-002 \[pending\]/);
+
+    const details = result.details as { active: boolean; task_ids: string[]; total: number };
+    expect(details.active).toBe(true);
+    expect(details.task_ids).toEqual(['t-001', 't-002', 't-003']);
+    expect(details.total).toBe(3);
+  });
+
+  test('reports no active plan (read-only, no throw) with candidates', async () => {
+    const tool = setup(undefined, ['alpha', 'beta']);
+    const result = await tool.execute('c', {});
+    expect((result.details as { active: boolean }).active).toBe(false);
+    expect(result.content?.[0]?.text).toMatch(/alpha, beta/);
+  });
+});

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

@@ -0,0 +1,129 @@
+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('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__/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,18 @@ export const PLAN_TOOLS = [
   'questionnaire',
   'search_skills',
   'subagent',
+  'plan_status',
 ];
 
-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',
+];
 
 // ── Model + thinking presets ─────────────────────────────────────────────────
 export const PLAN_MODEL = { provider: 'anthropic', id: 'claude-opus-4-6' } as const;

package/extensions/plan-mode/index.ts

@@ -38,10 +38,12 @@ import { filterExecutionMessages, filterStalePlanMessages } from './context-filt
 import { activeTasksResolved, deferredTasks } 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 { 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 { isSafeCommand, isPlanPath } from './utils.js';
 
 export default function planMode(pi: ExtensionAPI): void {
@@ -68,7 +70,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);
@@ -92,8 +94,12 @@ export default function planMode(pi: ExtensionAPI): void {
     },
   });
 
+  registerPlanStatusTool(pi, {
+    resolvePlan: (opts) => resolveActivePlan(state, pi, runPlanIO, opts),
+  });
+
   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);
@@ -477,6 +483,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);

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

@@ -0,0 +1,104 @@
+/**
+ * Disk-backed active-plan resolution.
+ *
+ * `state.plan` is session-scoped: it is only populated when a plan is submitted
+ * in *this* session, restored from this session's entries, or handed off via
+ * the one-shot exec-pending file. But `.plans/<name>/tasks.jsonl` is the real
+ * source of truth, and execution routinely happens in a different session than
+ * planning. This bridges that gap: when nothing is attached in memory, resolve
+ * the plan from disk so `update_task` / `add_task` work without an interactive
+ * `/plan resume`.
+ *
+ * Attaching only loads the plan DATA into `state` (so tracking writes land in
+ * `tasks.jsonl`); it intentionally does NOT flip `executing` / tools / model —
+ * that stays the user's explicit choice via `/plan-exec` or `/plan resume`.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { PlanModeState } from './state.js';
+import type { PlanData } from './types.js';
+import type { RunPlanIO } from './effects/runtime.js';
+import { readPlansManifest } from './storage/plans-manifest.js';
+import { readTasksJsonl } from './storage/task-storage.js';
+import { loadHandoff } from './storage/plan-storage.js';
+
+export interface ResolvedPlan {
+  /** The attached plan, when resolvable. Already written into `state`. */
+  plan?: PlanData;
+  /**
+   * In-progress plan names, surfaced when resolution was ambiguous (multiple
+   * in-progress and no usable `name` hint) or a hint missed. Lets a caller
+   * report actionable choices instead of dead-ending.
+   */
+  candidates: string[];
+}
+
+/** Normalize a plan hint (`my-plan` or `.plans/my-plan`) to a bare name. */
+function normalizeName(hint: string): string {
+  return hint
+    .replace(/^\.plans\//, '')
+    .replace(/\/+$/, '')
+    .trim();
+}
+
+/** Load `.plans/<name>` from disk into `state` (data only). Returns the plan,
+ *  or undefined when the tasks file is missing/empty. */
+async function attach(
+  state: PlanModeState,
+  pi: ExtensionAPI,
+  runPlanIO: RunPlanIO,
+  name: string,
+): Promise<PlanData | undefined> {
+  const dir = `.plans/${name}`;
+  const snapshot = await runPlanIO(readTasksJsonl(dir));
+  if (!snapshot) return undefined;
+  const plan: PlanData = {
+    title: snapshot.meta.title,
+    planName: snapshot.meta.plan_name,
+    handoff: (await runPlanIO(loadHandoff(dir))) ?? '',
+    tasks: snapshot.tasks,
+  };
+  state.plan = plan;
+  state.planDir = dir;
+  state.persist(pi);
+  return plan;
+}
+
+/**
+ * Resolve the active plan, attaching from disk when nothing is in memory.
+ *
+ * Order: in-memory `state.plan` → explicit `name` hint → the single
+ * in-progress plan in `.plans/plans.jsonl`. Ambiguous (multiple in-progress,
+ * no hint) returns `{ plan: undefined, candidates }` so the caller can prompt
+ * for a `name`.
+ */
+export async function resolveActivePlan(
+  state: PlanModeState,
+  pi: ExtensionAPI,
+  runPlanIO: RunPlanIO,
+  opts: { name?: string } = {},
+): Promise<ResolvedPlan> {
+  if (state.plan) return { plan: state.plan, candidates: [] };
+
+  const manifest = await runPlanIO(readPlansManifest());
+
+  if (opts.name) {
+    const hint = normalizeName(opts.name);
+    const match = manifest.find((entry) => entry.name === hint);
+    // A hint that names a real plan attaches regardless of status (the caller
+    // asked for it explicitly); a hint that names nothing falls through to the
+    // ambiguity report so the caller sees the valid choices.
+    if (match) {
+      const plan = await attach(state, pi, runPlanIO, match.name);
+      if (plan) return { plan, candidates: [] };
+    }
+  }
+
+  const inProgress = manifest.filter((entry) => entry.status === 'in-progress');
+  if (inProgress.length === 1) {
+    const plan = await attach(state, pi, runPlanIO, inProgress[0]!.name);
+    if (plan) return { plan, candidates: [] };
+  }
+
+  return { plan: undefined, candidates: inProgress.map((entry) => entry.name) };
+}

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

@@ -9,11 +9,13 @@
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { Text } from '@earendil-works/pi-tui';
 import { Type } from 'typebox';
-import type { PlanData, TaskRecord } from '../types.js';
+import type { TaskRecord } from '../types.js';
+import type { ResolvedPlan } from '../resolve-plan.js';
 import { nextTaskId } from '../utils.js';
 
 export interface AddTaskCallbacks {
-  getPlan: () => PlanData | undefined;
+  /** Resolve the active plan, attaching from disk when none is in memory. */
+  resolvePlan: (opts?: { name?: string }) => Promise<ResolvedPlan>;
   onTaskAdded: (task: TaskRecord) => void | Promise<void>;
 }
 
@@ -38,11 +40,31 @@ 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.',
+        }),
+      ),
     }),
 
     async execute(_toolCallId, params) {
-      const plan = callbacks.getPlan();
-      if (!plan) throw new Error('No active plan. Cannot add a follow-up task.');
+      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.
+      if (!plan) {
+        const hint =
+          candidates.length > 1
+            ? ` Multiple in-progress plans (${candidates.join(', ')}) — pass { plan: "<name>" } to choose.`
+            : ' No in-progress plan found in .plans/plans.jsonl.';
+        const details: Record<string, unknown> = { skipped: true, candidates };
+        return {
+          content: [
+            { type: 'text' as const, text: `Skipped follow-up capture — no active plan.${hint}` },
+          ],
+          details,
+        };
+      }
 
       const now = new Date().toISOString();
       const task: TaskRecord = {

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

@@ -0,0 +1,123 @@
+/**
+ * plan_status tool — read-only snapshot of the active plan.
+ *
+ * Lets an agent proactively learn whether a plan is active, its progress, and
+ * the valid task ids — instead of discovering that by a failed `update_task`.
+ * Resolves disk-backed (attaches the sole in-progress plan), so it works in a
+ * fresh execution session. Pure read: never mutates plan state.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Text } from '@earendil-works/pi-tui';
+import { Type } from 'typebox';
+import type { TaskStatus } from '../types.js';
+import type { ResolvedPlan } from '../resolve-plan.js';
+
+export interface PlanStatusCallbacks {
+  /** Resolve the active plan, attaching from disk when none is in memory. */
+  resolvePlan: (opts?: { name?: string }) => Promise<ResolvedPlan>;
+}
+
+const STATUS_GLYPH: Record<TaskStatus, string> = {
+  done: '✓',
+  skipped: '⊘',
+  blocked: '✗',
+  pending: '○',
+  deferred: '+',
+};
+
+export function registerPlanStatusTool(pi: ExtensionAPI, callbacks: PlanStatusCallbacks): void {
+  pi.registerTool({
+    name: 'plan_status',
+    label: 'Plan Status',
+    description:
+      'Read-only snapshot of the active plan: progress counts and every task id + status. Use to check whether a plan is active and what the valid task ids are before calling update_task.',
+    promptSnippet: 'Show the active plan: progress + task ids/statuses',
+    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.',
+    ],
+    parameters: Type.Object({
+      plan: Type.Optional(
+        Type.String({
+          description:
+            'Plan name (or .plans/<name>) to inspect. Only needed to disambiguate when multiple plans are in-progress.',
+        }),
+      ),
+    }),
+
+    async execute(_toolCallId, params) {
+      const { plan, candidates } = await callbacks.resolvePlan({ name: params.plan });
+      if (!plan) {
+        const hint =
+          candidates.length > 1
+            ? ` In-progress plans: ${candidates.join(', ')} — pass { plan: "<name>" }.`
+            : ' No in-progress plan found in .plans/plans.jsonl.';
+        const noPlanDetails: Record<string, unknown> = { active: false, candidates };
+        return {
+          content: [{ type: 'text' as const, text: `No active plan.${hint}` }],
+          details: noPlanDetails,
+        };
+      }
+
+      const counts: Record<TaskStatus, number> = {
+        done: 0,
+        skipped: 0,
+        blocked: 0,
+        pending: 0,
+        deferred: 0,
+      };
+      for (const task of plan.tasks) counts[task.status] += 1;
+      const resolved = counts.done + counts.skipped;
+
+      const parts = [
+        `done ${counts.done}`,
+        `skipped ${counts.skipped}`,
+        `pending ${counts.pending}`,
+      ];
+      if (counts.blocked) parts.push(`blocked ${counts.blocked}`);
+      if (counts.deferred) parts.push(`follow-up ${counts.deferred}`);
+
+      const lines = plan.tasks.map(
+        (task) => `  ${STATUS_GLYPH[task.status]} ${task.id} [${task.status}] ${task.description}`,
+      );
+      const text =
+        `Plan: ${plan.title} (${plan.planName})\n` +
+        `Progress: ${resolved}/${plan.tasks.length} resolved — ${parts.join(', ')}\n` +
+        `Tasks:\n${lines.join('\n')}`;
+
+      return {
+        content: [{ type: 'text' as const, text }],
+        details: {
+          active: true,
+          plan_name: plan.planName,
+          title: plan.title,
+          total: plan.tasks.length,
+          counts,
+          task_ids: plan.tasks.map((task) => task.id),
+        },
+      };
+    },
+
+    renderCall(args, theme) {
+      const name = (args as { plan?: string }).plan;
+      let content = theme.fg('toolTitle', theme.bold('plan_status'));
+      if (name) content += ' ' + theme.fg('muted', name);
+      return new Text(content, 0, 0);
+    },
+
+    renderResult(result, _options, theme) {
+      const details = result.details as
+        | { active?: boolean; plan_name?: string; total?: number; counts?: Record<string, number> }
+        | undefined;
+      if (!details?.active) return new Text(theme.fg('dim', 'No active plan'), 0, 0);
+      const resolved = (details.counts?.done ?? 0) + (details.counts?.skipped ?? 0);
+      return new Text(
+        theme.fg('toolTitle', `${details.plan_name ?? 'plan'} `) +
+          theme.fg('muted', `${resolved}/${details.total ?? 0} resolved`),
+        0,
+        0,
+      );
+    },
+  });
+}

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

@@ -6,10 +6,12 @@ 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, TaskStatus } from '../types.js';
+import type { TaskStatus } from '../types.js';
+import type { ResolvedPlan } from '../resolve-plan.js';
 
 export interface UpdateTaskCallbacks {
-  getPlan: () => PlanData | undefined;
+  /** Resolve the active plan, attaching from disk when none is in memory. */
+  resolvePlan: (opts?: { name?: string }) => Promise<ResolvedPlan>;
   onTaskUpdated: (
     taskId: string,
     status: Exclude<TaskStatus, 'pending'>,
@@ -17,6 +19,11 @@ export interface UpdateTaskCallbacks {
   ) => void | Promise<void>;
 }
 
+/** A non-terminating tool result — task tracking must never derail real work. */
+function soft(text: string, details: Record<string, unknown>) {
+  return { content: [{ type: 'text' as const, text }], details };
+}
+
 export function registerUpdateTaskTool(pi: ExtensionAPI, callbacks: UpdateTaskCallbacks): void {
   pi.registerTool({
     name: 'update_task',
@@ -35,19 +42,51 @@ 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.',
+        }),
+      ),
     }),
 
     async execute(_toolCallId, params) {
-      const plan = callbacks.getPlan();
-      if (!plan) throw new Error('No active plan. Cannot update task.');
+      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.
+      if (!plan) {
+        const hint =
+          candidates.length > 1
+            ? ` Multiple in-progress plans (${candidates.join(', ')}) — pass { plan: "<name>" } to choose.`
+            : ' No in-progress plan found in .plans/plans.jsonl.';
+        return soft(`Skipped task tracking — no active plan.${hint}`, {
+          skipped: true,
+          candidates,
+        });
+      }
 
       const task = plan.tasks.find((candidate) => candidate.id === params.task_id);
-      if (!task) throw new Error(`Task not found: ${params.task_id}`);
-      if (task.status !== 'pending') {
-        throw new Error(
-          `Task ${params.task_id} is already "${task.status}". Only pending tasks can be updated.`,
-        );
+      if (!task) {
+        const ids = plan.tasks.map((candidate) => candidate.id).join(', ');
+        return soft(`Task not found: ${params.task_id}. Valid ids: ${ids || '(none)'}`, {
+          error: 'not_found',
+          task_id: params.task_id,
+        });
+      }
+      // Idempotent: re-marking the same status is a no-op success (safe to
+      // retry).
+      if (task.status === params.status) {
+        return soft(`Task ${params.task_id} already ${params.status} (no-op).`, {
+          task_id: params.task_id,
+          status: params.status,
+          description: task.description,
+        });
       }
+      // A different status on an already-resolved task is a CORRECTION — apply
+      // it (e.g. done→skipped, or blocked→done to unblock). The status is the
+      // edit; the plan queue recomputes from it.
+      const wasCorrection = task.status !== 'pending';
+      const priorStatus = task.status;
 
       await callbacks.onTaskUpdated(params.task_id, params.status, params.notes);
 
@@ -75,7 +114,8 @@ export function registerUpdateTaskTool(pi: ExtensionAPI, callbacks: UpdateTaskCa
       const resolved = done + skipped;
       const next = plan.tasks.find((candidate) => candidate.status === 'pending');
       const statusEmoji = params.status === 'done' ? '✓' : '⊘';
-      let text = `${statusEmoji} Task ${params.task_id} ${params.status}. Progress: ${resolved}/${plan.tasks.length}`;
+      const verb = wasCorrection ? `corrected (${priorStatus} → ${params.status})` : params.status;
+      let text = `${statusEmoji} Task ${params.task_id} ${verb}. Progress: ${resolved}/${plan.tasks.length}`;
       if (params.notes) text += ` — ${params.notes}`;
       text += next ? `\n\nNext task ${next.id}: ${next.description}` : '\n\nAll tasks resolved!';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-plan-mode",
-  "version": "0.17.1",
+  "version": "0.18.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"