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

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @dreki-gg/pi-plan-mode
 
+## 0.20.1
+
+### Patch Changes
+
+- Hide the `technical-options` skill from model auto-invocation (`disable-model-invocation: true`). It carried always-on system-prompt token cost but never auto-triggered in practice. It remains available on demand via `/skill:technical-options`. `planning-context` and `visual-prototype` are unchanged.
+
+## 0.20.0
+
+### Minor Changes
+
+- 37d0f37: Add `update_tasks` batch tool: mark several plan tasks done/skipped in a single
+  call with one coalesced `tasks.jsonl` write (avoids the file-write contention
+  from repeated `update_task` calls). Each item is `{ task_id, status, notes? }`;
+  blocking stays single-task via `update_task`.
+
 ## 0.19.0
 
 ### Minor Changes

package/README.md

@@ -27,6 +27,7 @@ pi install npm:@dreki-gg/pi-questionnaire
 | Command  | `/todos`       | Show current plan progress                     |
 | Shortcut | `Ctrl+Alt+P`   | Toggle plan mode                               |
 | 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     | `update_plan`  | Close/reopen a plan: done, superseded, abandoned, in-progress |

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

@@ -0,0 +1,130 @@
+import { describe, expect, test } from 'bun:test';
+import { registerUpdateTasksTool } from '../tools/update-tasks.js';
+import type { PlanData, TaskRecord, TaskStatus } from '../types.js';
+
+const now = '2026-05-27T12:00:00.000Z';
+
+interface CapturedTool {
+  execute: (
+    id: string,
+    params: {
+      updates: Array<{ task_id: string; status: 'done' | 'skipped'; 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 }> = [];
+  // Count how many times the coalesced write callback fires — must be ≤ 1 per call.
+  let writeCount = 0;
+  const pi = {
+    registerTool: (config: CapturedTool) => {
+      tool = config;
+    },
+  } as unknown as Parameters<typeof registerUpdateTasksTool>[0];
+
+  registerUpdateTasksTool(pi, {
+    resolvePlan: async () => ({ plan, candidates }),
+    onTasksUpdated: (batch) => {
+      writeCount += 1;
+      for (const { taskId, status, notes } of batch) {
+        const target = plan?.tasks.find((candidate) => candidate.id === taskId);
+        if (target) target.status = status;
+        updates.push({ taskId, status, notes });
+      }
+    },
+  });
+
+  return { tool: tool!, updates, getWriteCount: () => writeCount };
+}
+
+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_tasks tool', () => {
+  test('marks multiple pending tasks (mixed statuses) in a SINGLE write and reports progress', async () => {
+    const { tool, updates, getWriteCount } = setup(
+      basePlan([planTask('t-001'), planTask('t-002'), planTask('t-003')]),
+    );
+    const result = await tool.execute('c', {
+      updates: [
+        { task_id: 't-001', status: 'done', notes: 'a' },
+        { task_id: 't-002', status: 'skipped', notes: 'b' },
+      ],
+    });
+    expect(updates).toEqual([
+      { taskId: 't-001', status: 'done', notes: 'a' },
+      { taskId: 't-002', status: 'skipped', notes: 'b' },
+    ]);
+    // The whole point of the batch tool: one coalesced write, not one per task.
+    expect(getWriteCount()).toBe(1);
+    expect(result.content?.[0]?.text).toMatch(/Progress: 2\/3/);
+    expect(result.terminate).toBeUndefined();
+  });
+
+  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' }] });
+    expect((result.details as { skipped?: boolean }).skipped).toBe(true);
+    expect(result.content?.[0]?.text).toMatch(/alpha, beta/);
+    expect(updates).toHaveLength(0);
+  });
+
+  test('no write when every item is a no-op or not_found', async () => {
+    const { tool, getWriteCount } = setup(basePlan([planTask('t-001', 'done')]));
+    await tool.execute('c', {
+      updates: [
+        { task_id: 't-001', status: 'done' },
+        { task_id: 't-999', status: 'done' },
+      ],
+    });
+    expect(getWriteCount()).toBe(0);
+  });
+
+  test('mixed batch: valid applied, unknown id reported as not_found', async () => {
+    const { tool, updates } = setup(basePlan([planTask('t-001'), planTask('t-002')]));
+    const result = await tool.execute('c', {
+      updates: [
+        { task_id: 't-001', status: 'done' },
+        { task_id: 't-999', status: 'done' },
+      ],
+    });
+    expect(updates).toEqual([{ taskId: 't-001', status: 'done', notes: undefined }]);
+    const details = result.details as { results?: Array<{ task_id: string; outcome: string }> };
+    expect(details.results?.find((r) => r.task_id === 't-999')?.outcome).toBe('not_found');
+  });
+
+  test('idempotent: re-marking the same status is a per-item no-op', async () => {
+    const { tool, updates } = setup(basePlan([planTask('t-001', 'done'), planTask('t-002')]));
+    const result = await tool.execute('c', {
+      updates: [
+        { task_id: 't-001', status: 'done' },
+        { task_id: 't-002', status: 'done' },
+      ],
+    });
+    expect(updates).toEqual([{ taskId: 't-002', status: 'done', notes: undefined }]);
+    const details = result.details as { results?: Array<{ task_id: string; outcome: string }> };
+    expect(details.results?.find((r) => r.task_id === 't-001')?.outcome).toBe('noop');
+  });
+
+  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' }] });
+    expect(updates).toEqual([{ taskId: 't-001', status: 'skipped', notes: undefined }]);
+  });
+});

package/extensions/plan-mode/constants.ts

@@ -26,6 +26,7 @@ export const EXEC_TOOLS = [
   'edit',
   'write',
   'update_task',
+  'update_tasks',
   'add_task',
   'plan_status',
   'update_plan',

package/extensions/plan-mode/index.ts

@@ -26,7 +26,7 @@ import {
   EXEC_MODEL,
   EXEC_THINKING,
 } from './constants.js';
-import type { ThinkingLevel } from './types.js';
+import type { ThinkingLevel, TaskStatus } from './types.js';
 import { PlanModeState } from './state.js';
 import { makePlanRuntime } from './effects/runtime.js';
 import { loadHandoff, readAndClearExecPending } from './storage/plan-storage.js';
@@ -43,6 +43,7 @@ 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 { registerUpdateTasksTool } from './tools/update-tasks.js';
 import { registerAddTaskTool } from './tools/add-task.js';
 import { registerPlanStatusTool } from './tools/plan-status.js';
 import { registerUpdatePlanTool } from './tools/update-plan.js';
@@ -72,15 +73,64 @@ export default function planMode(pi: ExtensionAPI): void {
 
   registerPreviewPrototypeTool(pi, runPlanIO);
 
+  // Shared task-write closure: mutate the in-memory task, persist tasks.jsonl,
+  // and re-derive registry status. Used by both update_task and update_tasks.
+  const onTaskUpdated = async (
+    taskId: string,
+    status: Exclude<TaskStatus, 'pending'>,
+    notes?: string,
+  ) => {
+    if (!state.plan || !state.planDir) return;
+    const task = state.plan.tasks.find((candidate) => candidate.id === taskId);
+    if (!task) return;
+    task.status = status;
+    task.updated_at = new Date().toISOString();
+    if (notes) task.notes = notes;
+    await runPlanIO(
+      writeTasksJsonl(
+        state.planDir,
+        {
+          _type: 'meta',
+          title: state.plan.title,
+          plan_name: state.plan.planName,
+          created_at: state.plan.tasks[0]?.created_at ?? task.updated_at,
+        },
+        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 task updates now close the plan too.
+    await runPlanIO(
+      reconcilePlanStatus(
+        state.plan.planName,
+        isPlanFinalizable(state.plan.tasks),
+        state.plan.title,
+      ),
+    );
+    state.persist(pi);
+  };
+
   registerUpdateTaskTool(pi, {
     resolvePlan: (opts) => resolveActivePlan(state, pi, runPlanIO, opts),
-    onTaskUpdated: async (taskId, status, notes) => {
+    onTaskUpdated,
+  });
+
+  registerUpdateTasksTool(pi, {
+    resolvePlan: (opts) => resolveActivePlan(state, pi, runPlanIO, opts),
+    // Coalesced batch write: mutate every task in memory first, then perform a
+    // SINGLE tasks.jsonl write + ONE registry reconcile. This is the whole point
+    // of update_tasks — repeated single-task writes caused file-write contention.
+    onTasksUpdated: async (updates) => {
       if (!state.plan || !state.planDir) return;
-      const task = state.plan.tasks.find((candidate) => candidate.id === taskId);
-      if (!task) return;
-      task.status = status;
-      task.updated_at = new Date().toISOString();
-      if (notes) task.notes = notes;
+      const now = new Date().toISOString();
+      for (const { taskId, status, notes } of updates) {
+        const task = state.plan.tasks.find((candidate) => candidate.id === taskId);
+        if (!task) continue;
+        task.status = status;
+        task.updated_at = now;
+        if (notes) task.notes = notes;
+      }
       await runPlanIO(
         writeTasksJsonl(
           state.planDir,
@@ -88,14 +138,11 @@ export default function planMode(pi: ExtensionAPI): void {
             _type: 'meta',
             title: state.plan.title,
             plan_name: state.plan.planName,
-            created_at: state.plan.tasks[0]?.created_at ?? task.updated_at,
+            created_at: state.plan.tasks[0]?.created_at ?? now,
           },
           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,

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

@@ -0,0 +1,172 @@
+/**
+ * update_tasks tool — batch sibling of update_task.
+ *
+ * Marks several tasks done/skipped in a single call. Unlike update_task it
+ * never blocks (blocking pauses the turn, which is ambiguous mid-batch) and
+ * therefore never terminates. Each item mirrors update_task's per-task
+ * semantics: idempotent no-ops, corrections, and soft not_found handling.
+ */
+
+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 { TaskStatus } from '../types.js';
+import type { ResolvedPlan } from '../resolve-plan.js';
+
+export interface UpdateTasksCallbacks {
+  /** Resolve the active plan, attaching from disk when none is in memory. */
+  resolvePlan: (opts?: { name?: string }) => Promise<ResolvedPlan>;
+  /**
+   * Apply ALL accepted updates in one shot. The implementation mutates the
+   * in-memory tasks, then performs a SINGLE coalesced tasks.jsonl write and
+   * registry reconcile — avoiding the per-task write storm that caused file
+   * write contention with repeated update_task calls.
+   */
+  onTasksUpdated: (
+    updates: Array<{
+      taskId: string;
+      status: Exclude<TaskStatus, 'pending' | 'blocked' | 'deferred'>;
+      notes?: string;
+    }>,
+  ) => 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 };
+}
+
+type ItemOutcome = 'updated' | 'noop' | 'not_found';
+
+interface ItemResult {
+  task_id: string;
+  outcome: ItemOutcome;
+  status?: 'done' | 'skipped';
+  prior?: string;
+}
+
+export function registerUpdateTasksTool(pi: ExtensionAPI, callbacks: UpdateTasksCallbacks): void {
+  pi.registerTool({
+    name: 'update_tasks',
+    label: 'Update Tasks',
+    description:
+      'Mark several plan tasks done or skipped in one call. Use when you finished multiple tasks in a turn. Cannot block — use update_task for that.',
+    promptSnippet: 'Mark multiple plan tasks done or skipped in one call',
+    promptGuidelines: [
+      'Use update_tasks to resolve several finished tasks at once instead of repeated update_task calls.',
+      'Each item is { task_id, status: done|skipped, notes? }. To block a task, use update_task instead.',
+      'Always include notes summarizing what was done or why skipped.',
+    ],
+    parameters: Type.Object({
+      updates: Type.Array(
+        Type.Object({
+          task_id: Type.String({ description: 'Task ID (for example, t-001)' }),
+          status: StringEnum(['done', 'skipped'] as const),
+          notes: Type.Optional(
+            Type.String({ description: 'What was done or why skipped' }),
+          ),
+        }),
+        { 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.',
+        }),
+      ),
+    }),
+
+    async execute(_toolCallId, params) {
+      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 results: ItemResult[] = [];
+      const accepted: Array<{ taskId: string; status: 'done' | 'skipped'; notes?: string }> = [];
+      for (const update of params.updates) {
+        const task = plan.tasks.find((candidate) => candidate.id === update.task_id);
+        if (!task) {
+          results.push({ task_id: update.task_id, outcome: 'not_found' });
+          continue;
+        }
+        // Idempotent: re-marking the same status is a no-op (safe to retry).
+        if (task.status === update.status) {
+          results.push({ task_id: update.task_id, outcome: 'noop', status: update.status });
+          continue;
+        }
+        // A different status on an already-resolved task is a CORRECTION — apply
+        // it. The plan queue recomputes from the new status.
+        results.push({
+          task_id: update.task_id,
+          outcome: 'updated',
+          status: update.status,
+          prior: task.status,
+        });
+        accepted.push({ taskId: update.task_id, status: update.status, notes: update.notes });
+      }
+
+      // SINGLE coalesced write: apply every accepted change in one callback,
+      // which performs exactly one tasks.jsonl write + one registry reconcile.
+      if (accepted.length > 0) await callbacks.onTasksUpdated(accepted);
+
+      const updated = results.filter((r) => r.outcome === 'updated');
+      const noop = results.filter((r) => r.outcome === 'noop');
+      const notFound = results.filter((r) => r.outcome === 'not_found');
+
+      const done = plan.tasks.filter((candidate) => candidate.status === 'done').length;
+      const skipped = plan.tasks.filter((candidate) => candidate.status === 'skipped').length;
+      const resolved = done + skipped;
+      const next = plan.tasks.find((candidate) => candidate.status === 'pending');
+
+      const parts = [`Updated ${updated.length} task(s).`];
+      if (noop.length) parts.push(`${noop.length} no-op.`);
+      if (notFound.length) {
+        const ids = plan.tasks.map((candidate) => candidate.id).join(', ');
+        parts.push(`Not found: ${notFound.map((r) => r.task_id).join(', ')} (valid: ${ids}).`);
+      }
+      let text = parts.join(' ');
+      text += ` Progress: ${resolved}/${plan.tasks.length}`;
+      text += next ? `\n\nNext task ${next.id}: ${next.description}` : '\n\nAll tasks resolved!';
+
+      // Never terminate: update_tasks has no blocked path, and completion is
+      // handled out-of-band by the agent_end handler in index.ts.
+      return { content: [{ type: 'text' as const, text }], details: { results } };
+    },
+
+    renderCall(args, theme) {
+      const updates = (args as { updates?: Array<{ task_id?: string }> }).updates ?? [];
+      let content = theme.fg('toolTitle', theme.bold('update_tasks '));
+      content += theme.fg('muted', updates.map((u) => u.task_id ?? '?').join(', '));
+      return new Text(content, 0, 0);
+    },
+
+    renderResult(result, _options, theme) {
+      const details = result.details as { results?: ItemResult[] } | undefined;
+      const results = details?.results ?? [];
+      if (results.length === 0) return new Text(theme.fg('dim', 'Updated'), 0, 0);
+      const icon: Record<string, string> = {
+        done: theme.fg('success', '✓'),
+        skipped: theme.fg('warning', '⊘'),
+      };
+      const line = results
+        .map((r) => {
+          if (r.outcome === 'not_found') return theme.fg('error', `✗ ${r.task_id}`);
+          if (r.outcome === 'noop') return theme.fg('dim', `= ${r.task_id}`);
+          return `${icon[r.status ?? ''] ?? ''} ${r.task_id}`;
+        })
+        .join('  ');
+      return new Text(line, 0, 0);
+    },
+  });
+}

package/package.json

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

package/skills/technical-options/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: technical-options
 description: Generate and rank competing options for a technical decision using parallel evaluators. Use when the user wants a structured comparison of implementation approaches, architecture alternatives, or engineering tradeoffs before choosing one. Not for binary yes/no or pure preference decisions.
+disable-model-invocation: true
 ---
 
 # Technical Options