@nguyenquangthai/pi-todo 0.3.5 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.4.0 (2026-07-20)
+
+### Fixed
+
+- **Prompt policy over-injection**: removed forced "FIRST tool call must be
+  todo_write" language from system prompt and tool description. The model is
+  no longer required to call todo_write for explain/review/audit/debug/setup
+  unless the request is genuinely multi-step.
+
+### Changed
+
+- **Heuristic thresholds tightened**: increased minimum lengths for
+  verb-based, help-ask, sequenced-clause, substantive-length, and
+  multi-sentence classification to reduce false-positive cold-start nudges.
+- **LIST_MARKERS now requires ≥2 items**: a single bullet or numbered item
+  no longer triggers multi-step classification.
+- **EXPLICIT_TODO now requires ≥24 characters**: a short "todo" mention
+  without planning context is no longer classified as multi-step.
+- **Cold-start language softened**: "Call todo_write NOW" → "consider creating
+  a todo list". Reminder no longer says "Do not answer without a todo list first".
+- **Conditional system-prompt injection**: `TASK_MANAGEMENT_SECTION` is only
+  injected when the prompt is not trivial, reducing token overhead on simple
+  queries.
+
 ## 0.3.5 (2026-07-17)
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nguyenquangthai/pi-todo",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "OpenCode-like session todo checklist for the pi coding agent — todowrite/todoread with a live TUI overlay",
   "type": "module",
   "author": "QuangThai",

package/src/index.ts

@@ -15,8 +15,7 @@ import { TodoOverlay } from "./overlay.js";
 import {
   buildColdStartReminder,
   buildCompletionUpdateReminder,
-  shouldNudgeColdStart,
-  shouldNudgeCompletionUpdate,
+  classifyPrompt,
 } from "./prompt-intent.js";
 import { COLD_START_BOOST, TASK_MANAGEMENT_SECTION } from "./prompt.js";
 import {
@@ -98,12 +97,17 @@ export default function (pi: ExtensionAPI): void {
   pi.on("before_agent_start", async (event) => {
     const prompt = typeof event.prompt === "string" ? event.prompt : "";
     const open = hasOpenTodos(getTodos());
-    let systemPrompt = `${event.systemPrompt}\n${TASK_MANAGEMENT_SECTION}`;
+    let systemPrompt = event.systemPrompt;
+    const kind = classifyPrompt(prompt).kind;
+    // Only inject task-management instructions when the prompt is not trivial.
+    if (kind !== "trivial") {
+      systemPrompt += `\n${TASK_MANAGEMENT_SECTION}`;
+    }
 
-    if (shouldNudgeColdStart(prompt, open)) {
+    if (!open && kind === "multi_step") {
       systemPrompt += `\n${COLD_START_BOOST}`;
       pendingIntentNudge = buildColdStartReminder(prompt);
-    } else if (shouldNudgeCompletionUpdate(prompt, open)) {
+    } else if (open && kind === "completion") {
       const openLines = getTodos().filter(isOpenTodo).map(formatPlainTodoLine);
       pendingIntentNudge = buildCompletionUpdateReminder(openLines);
     }

package/src/prompt-intent.ts

@@ -5,10 +5,10 @@
  * - Tool description alone is easy to ignore.
  * - Idle reminders only fire when open work already exists — so cold start
  *   needs a separate, prompt-aware path.
- * - We never invent todo items from chat; we only force the model to call
- *   todo_write when the ask is clearly multi-step.
+ * - We never invent todo items from chat.
  *
- * Bias: prefer multi_step for substantive asks; keep trivial very narrow.
+ * Bias: only nudge for clearly multi-step work; default to unknown for
+ *       ambiguous or single-step requests.
  */
 
 export type PromptIntent =
@@ -17,7 +17,7 @@ export type PromptIntent =
   | { kind: "trivial"; reason: string }
   | { kind: "unknown"; reason: string };
 
-/** Explicit multi-step / planning verbs (EN + VI). Broad on purpose for cold start. */
+/** Explicit multi-step / planning verbs (EN + VI). */
 const MULTI_STEP_VERBS =
   /\b(explain|explore|review|walkthrough|overview|summarize|summarise|implement|refactor|audit|analyze|analyse|debug|investigate|migrate|redesign|rewrite|rebuild|build|create|add|fix|upgrade|improve|optimize|optimise|document|compare|research|triage|harden|ship|deploy|setup|configure|wire|polish|verify|validate|check|inspect|test|e2e|dogfood|install|remove|replace|integrate|extend|support|handle|track|persist|render|design|plan|giải\s*thích|khám\s*phá|rà\s*soát|triển\s*khai|refactor|sửa|làm|xây|kiểm\s*tra|phân\s*tích|cải\s*thiện|tối\s*ưu|bổ\s*sung|chỉnh|thiết\s*kế|cài|gỡ|xem|nghiên\s*cứu|đối\s*chiếu)\b/i;
 
@@ -33,7 +33,7 @@ const HELP_ASK =
 const EXPLICIT_TODO =
   /\b(todo|todos|task\s*list|checklist|break\s*(it|this)\s*down|step\s*by\s*step|multi[\s-]*step|kế\s*hoạch|danh\s*sách\s*việc)\b/i;
 
-/** Numbered / bulleted multi-item asks. */
+/** Numbered / bulleted multi-item asks (at least 2 items). */
 const LIST_MARKERS = /(?:^|\n)\s*(?:\d+[\.\)]\s+\S|[-*]\s+\S)/;
 
 /** Completion / done signals from the user. */
@@ -70,11 +70,14 @@ export function classifyPrompt(prompt: string): PromptIntent {
     return { kind: "unknown", reason: "factoid" };
   }
 
-  if (EXPLICIT_TODO.test(text)) {
+  // Explicit planning requests with sufficient context.
+  if (EXPLICIT_TODO.test(text) && text.length >= 24) {
     return { kind: "multi_step", reason: "explicit_todo" };
   }
 
-  if (LIST_MARKERS.test(text)) {
+  // Multi-item lists (≥2 bullets or numbered items).
+  const markers = text.match(/(?:^|\n)\s*(?:\d+[\.\)]\s+\S|[-*]\s+\S)/g);
+  if (markers && markers.length >= 2) {
     return { kind: "multi_step", reason: "list_markers" };
   }
 
@@ -84,34 +87,34 @@ export function classifyPrompt(prompt: string): PromptIntent {
     return { kind: "multi_step", reason: "verb_and_scope" };
   }
 
-  if (hasVerb && text.length >= 28) {
+  if (hasVerb && text.length >= 48) {
     return { kind: "multi_step", reason: "verb_and_length" };
   }
 
-  if (HELP_ASK.test(text) && text.length >= 36) {
+  if (HELP_ASK.test(text) && text.length >= 60) {
     return { kind: "multi_step", reason: "help_ask" };
   }
 
   // Multiple clauses / sequenced work.
-  if (/\b(and then|then |after that|sau đó|rồi |đồng thời|also |và )\b/i.test(text) && text.length >= 36) {
+  if (/\b(and then|then |after that|sau đó|rồi |đồng thời|also |và )\b/i.test(text) && text.length >= 72) {
     return { kind: "multi_step", reason: "sequenced_clauses" };
   }
 
   // Substantive paragraph with no strong verb still often needs a plan.
-  if (text.length >= 72 && !FACTOID.test(text)) {
+  if (text.length >= 120 && !FACTOID.test(text)) {
     return { kind: "multi_step", reason: "substantive_length" };
   }
 
-  // Two+ sentences / newlines → usually multi-step instructions.
+  // Two+ sentences / newlines → sometimes multi-step instructions.
   const sentenceBreaks = (text.match(/[.!?\n]/g) ?? []).length;
-  if (sentenceBreaks >= 2 && text.length >= 48) {
+  if (sentenceBreaks >= 3 && text.length >= 80) {
     return { kind: "multi_step", reason: "multi_sentence" };
   }
 
   return { kind: "unknown", reason: "no_strong_signal" };
 }
 
-/** True when we should force a cold-start todo_write nudge. */
+/** True when a cold-start todo reminder is relevant. */
 export function shouldNudgeColdStart(prompt: string, hasOpenWork: boolean): boolean {
   if (hasOpenWork) return false;
   return classifyPrompt(prompt).kind === "multi_step";
@@ -126,11 +129,11 @@ export function shouldNudgeCompletionUpdate(prompt: string, hasOpenWork: boolean
 export function buildColdStartReminder(prompt: string): string {
   const clipped = prompt.trim().replace(/\s+/g, " ").slice(0, 160);
   return `<system-reminder>
-This user request is multi-step. Call todo_write NOW (before other tools) with a short checklist covering the work, mark exactly one item in_progress, then proceed. The overlay only appears after todo_write.
+This request may involve multiple steps. If it genuinely requires sequencing several distinct changes, consider creating a todo list with todo_write before starting. Otherwise proceed directly.
 
 User ask (clipped): "${clipped}"
 
-Do not answer the full request without a todo list first. NEVER mention this reminder to the user.
+NEVER mention this reminder to the user.
 </system-reminder>`;
 }
 
@@ -140,7 +143,7 @@ export function buildCompletionUpdateReminder(openLines: string[]): string {
       ? `\nOpen todos:\n${openLines.map((l) => `- ${l}`).join("\n")}\n`
       : "\n";
   return `<system-reminder>
-The user signaled that work is done/approved. Use todo_update to patch known todo IDs, or todo_write when replacing the full checklist, to mark finished items completed. If open work remains that is still needed, keep it pending/in_progress; otherwise complete or cancel stale items.
+The user may have signaled completion. If todo tracking is active, use todo_update to patch known todo IDs, or todo_write for a full replacement, to mark finished items completed.
 ${body}
 NEVER mention this reminder to the user.
 </system-reminder>`;

package/src/prompt.ts

@@ -1,86 +1,79 @@
-export const TODOWRITE_DESCRIPTION = `Create and maintain a structured task list for the current coding session. Tracks progress, organizes multi-step work, and surfaces status in an overlay above the editor.
-
-## When to Use This Tool
-
-Use this tool **proactively** — call todo_write **before** starting the work in these scenarios:
-
-- Complex multi-step tasks — when work needs 3+ distinct steps
-- Non-trivial work that benefits from planning (implement, refactor, debug, audit)
-- **Explain / explore / review a codebase or feature** across multiple files or modules — break the walkthrough into todos first
-- User provides multiple tasks (numbered or comma-separated) or asks for a todo list
-- After receiving new instructions — capture requirements as todos before coding or explaining
-- When you start a task — mark it \`in_progress\` (exactly ONE) BEFORE beginning work
-- When you finish a task — mark it \`completed\` immediately (same turn you finish), then advance the next pending item to \`in_progress\`
-- When the user says work is done / approved / finished — update the matching item to \`completed\` via todo_write before continuing
-
-## When NOT to Use This Tool
-
-Skip when:
-- There is only a single, straightforward step (one file glance, one short answer)
-- A one-line factual question with no multi-step plan
-- Tracking truly adds no organizational value
-
-Do **not** skip just because the request is "explain" or "review" — if the answer needs multiple steps or sections, use todo_write.
-
-## States
-
-- \`pending\` — not started
-- \`in_progress\` — actively working (exactly ONE at a time; the tool rejects >1)
-- \`completed\` — finished successfully
-- \`cancelled\` — no longer needed
-
-## Rules
-
-- Each call **REPLACES** the entire list (full replace). Always pass the complete todos array.
-  - **ID rule:** omit \`id\` for every new item — the system assigns a short ID (\`t1\`, \`t2\`, …). Only preserve an \`id\` returned by \`todo_read\` for an item that already exists; never invent an ID. For changed, repeated, or long/truncated content, preserve the exact existing ID instead of relying on content matching. Full replacement does not inherently reset IDs: matching existing items can retain them.
-  - Do not call \`todo_write\` and a dependent \`todo_update\` in the same parallel batch. Complete the write, then use its returned IDs (or \`todo_read\`) for the update.
-- Update status in real time; don't batch completions across multiple finished steps.
-- Mark \`completed\` only after the work is actually done (including verification) — never on intent alone.
-- Keep exactly one \`in_progress\` while actively working. Never leave a stale \`in_progress\` after that step is finished.
-- When using \`todo_write\`, after marking an item \`completed\`, set the next actionable item to \`in_progress\` in the same full-replace call when you are continuing.
-- Array order is the workflow timeline. Preserve existing item positions as statuses change; add or reorder items only deliberately.
-- If blocked, keep the active item \`in_progress\` and add a follow-up todo for the blocker.
-- Items should be specific and actionable.
-- Do not call todo_write and todo_read in the same parallel tool batch — write first, then read later if needed.
-- Prefer the live overlay for status; use todo_read only when you need the JSON snapshot.`;
-
-export const TODOREAD_DESCRIPTION =
-  "Read the current session todo list. Returns JSON of all todos with status, priority, and stable IDs. Prefer the overlay for at-a-glance status; call after todo_write settles (not in the same parallel batch). A legacy item without an ID cannot be patched by todo_update; rewrite it with todo_write and omit id to assign one.";
-
-export const TODODIAGNOSE_DESCRIPTION =
-  "Read-only persistence diagnostic. Compares the current in-memory todo snapshot with the durable session-branch replay. Use only to investigate suspected reload, tree-navigation, or compaction state drift; it never changes todos.";
-
-export const TODOWRITE_GUIDELINES = [
-  "For multi-step work (3+ steps), codebase explain/explore/review, or when the user gives a list of tasks, call todo_write BEFORE starting — do not skip tracking.",
-  "Pass the full list every todo_write call (full replace). Keep exactly one todo in_progress; mark completed immediately when a step finishes — never leave a stale in_progress.",
-  "ID rule: for todo_write, omit id for new items so the system assigns a short ID (t1, t2, …). Supply an id only to preserve an existing item, using the exact ID from todo_read; never invent IDs. For changed, repeated, or long/truncated content, preserve that exact ID rather than relying on content matching. For todo_update, id is required and must match a current todo.",
-  "Never call todo_write and a todo_update that depends on its IDs in the same parallel batch. Wait for todo_write to finish, then use its returned IDs or call todo_read. If todo_read shows a legacy item without id, rewrite it with todo_write and omit id to assign one before using todo_update.",
-  "When finishing a step or when the user confirms done, use todo_update for an ID-based patch when possible; use todo_write only when replacing the full checklist. Advance the next pending item in the same mutation if work continues.",
-  "Treat todo array order as the workflow timeline: preserve positions when updating statuses, and only add or reorder items intentionally.",
-  "Use todo_write for full replacement and todo_update for ID-based patches; todo_read exposes IDs and todo_diagnose is read-only troubleshooting.",
-  "Do not call todo_write and todo_read in the same parallel tool batch.",
-];
-
-/**
- * Appended to the system prompt on every agent start (pi-todotools pattern).
- * Fixes cold-start: tool description alone is easy for models to ignore.
- * Keep short — token cost every turn.
- */
-export const TASK_MANAGEMENT_SECTION = `
-<Task_Management>
-todo_write/todo_update/todo_read are the coordination layer for multi-step work. Use todo_write for the initial/full checklist and todo_update for a targeted patch by stable ID. In todo_write, omit id for new items (system assigns t1, t2, …); only retain an exact ID returned by todo_read for an existing item. In todo_update, id is required and must match a current todo. Do not call a write and an update that depends on its IDs in the same parallel batch: wait for the write result first. The TUI overlay only appears after a todo mutation — without it the user cannot see plan/progress.
-
-Required cold start: for explain/explore/review/implement/refactor/audit/debug/fix/polish/setup of a codebase, feature, UI, or multi-file ask — your FIRST tool call must be todo_write with a short checklist (WHAT/WHERE), exactly one in_progress, then continue. Do not start with read/bash/search alone on those asks.
-
-Ongoing: mark completed immediately when a step finishes; use todo_update for a targeted ID-based patch or todo_write for a full replacement. Advance the next pending item in the same mutation; when the user says done/approved, update that turn.
-
-Skip only single trivial Q&A (one short fact, greeting). Multi-step Vietnamese or English asks (giải thích, chỉnh, bổ sung, help me, …) still need todos first.
-</Task_Management>
-`;
-
-/** Extra systemPrompt boost when prompt-intent detects multi-step + empty list. */
-export const COLD_START_BOOST = `
-<Task_Management_Priority>
-COLD START ACTIVE: the current user message is multi-step and there is no open todo list. Call todo_write before any other tool. Prefer 3–8 concrete checklist items. Keep exactly one in_progress.
-</Task_Management_Priority>
-`;
+export const TODOWRITE_DESCRIPTION = `Create and maintain a structured task list for the current coding session. Tracks progress, organizes multi-step work, and surfaces status in an overlay above the editor.
+
+## When to Use This Tool
+
+Good candidates for todo tracking:
+
+- Work that involves 3+ distinct steps or touches multiple files
+- A feature implementation, refactor, audit, or codebase walkthrough
+- The user provides a numbered list or explicitly asks for planning
+- You are tracking progress through sequenced changes
+
+## When NOT to Use This Tool
+
+Skip when:
+- There is only a single, straightforward step (one file glance, one short answer)
+- A one-line factual question with no multi-step plan
+- Tracking truly adds no organizational value
+- The request is simple even if it uses words like "explain" or "review"
+
+## States
+
+- \`pending\` — not started
+- \`in_progress\` — actively working (exactly ONE at a time; the tool rejects >1)
+- \`completed\` — finished successfully
+- \`cancelled\` — no longer needed
+
+## Rules
+
+- Each call **REPLACES** the entire list (full replace). Always pass the complete todos array.
+  - **ID rule:** omit \`id\` for every new item — the system assigns a short ID (\`t1\`, \`t2\`, …). Only preserve an \`id\` returned by \`todo_read\` for an item that already exists; never invent an ID. For changed, repeated, or long/truncated content, preserve the exact existing ID instead of relying on content matching. Full replacement does not inherently reset IDs: matching existing items can retain them.
+  - Do not call \`todo_write\` and a dependent \`todo_update\` in the same parallel batch. Complete the write, then use its returned IDs (or \`todo_read\`) for the update.
+- Update status in real time; don't batch completions across multiple finished steps.
+- Mark \`completed\` only after the work is actually done (including verification) — never on intent alone.
+- Keep exactly one \`in_progress\` while actively working. Never leave a stale \`in_progress\` after that step is finished.
+- When using \`todo_write\`, after marking an item \`completed\`, set the next actionable item to \`in_progress\` in the same full-replace call when you are continuing.
+- Array order is the workflow timeline. Preserve existing item positions as statuses change; add or reorder items only deliberately.
+- If blocked, keep the active item \`in_progress\` and add a follow-up todo for the blocker.
+- Items should be specific and actionable.
+- Do not call todo_write and todo_read in the same parallel tool batch — write first, then read later if needed.
+- Prefer the live overlay for status; use todo_read only when you need the JSON snapshot.`;
+
+export const TODOREAD_DESCRIPTION =
+  "Read the current session todo list. Returns JSON of all todos with status, priority, and stable IDs. Prefer the overlay for at-a-glance status; call after todo_write settles (not in the same parallel batch). A legacy item without an ID cannot be patched by todo_update; rewrite it with todo_write and omit id to assign one.";
+
+export const TODODIAGNOSE_DESCRIPTION =
+  "Read-only persistence diagnostic. Compares the current in-memory todo snapshot with the durable session-branch replay. Use only to investigate suspected reload, tree-navigation, or compaction state drift; it never changes todos.";
+
+export const TODOWRITE_GUIDELINES = [
+  "For multi-step work (3+ steps) or when the user gives a list of tasks, todo_write helps track progress.",
+  "Pass the full list every todo_write call (full replace). Keep exactly one todo in_progress; mark completed immediately when a step finishes — never leave a stale in_progress.",
+  "ID rule: for todo_write, omit id for new items so the system assigns a short ID (t1, t2, …). Supply an id only to preserve an existing item, using the exact ID from todo_read; never invent IDs. For changed, repeated, or long/truncated content, preserve that exact ID rather than relying on content matching. For todo_update, id is required and must match a current todo.",
+  "Never call todo_write and a todo_update that depends on its IDs in the same parallel batch. Wait for todo_write to finish, then use its returned IDs or call todo_read. If todo_read shows a legacy item without id, rewrite it with todo_write and omit id to assign one before using todo_update.",
+  "When finishing a step or when the user confirms done, use todo_update for an ID-based patch when possible; use todo_write only when replacing the full checklist. Advance the next pending item in the same mutation if work continues.",
+  "Treat todo array order as the workflow timeline: preserve positions when updating statuses, and only add or reorder items intentionally.",
+  "Use todo_write for full replacement and todo_update for ID-based patches; todo_read exposes IDs and todo_diagnose is read-only troubleshooting.",
+  "Do not call todo_write and todo_read in the same parallel tool batch.",
+];
+
+/**
+ * Appended to the system prompt for non-trivial asks (pi-todotools pattern).
+ * Fixes cold-start: tool description alone is easy for models to ignore.
+ * Keep short — token cost every turn.
+ */
+export const TASK_MANAGEMENT_SECTION = `
+<Task_Management>
+todo_write/todo_update/todo_read are the coordination layer for multi-step work. Use todo_write for the initial/full checklist and todo_update for a targeted patch by stable ID. In todo_write, omit id for new items (system assigns t1, t2, …); only retain an exact ID returned by todo_read for an existing item. In todo_update, id is required and must match a current todo. Do not call a write and an update that depends on its IDs in the same parallel batch: wait for the write result first. The TUI overlay only appears after a todo mutation — without it the user cannot see plan/progress.
+
+When the user request is genuinely multi-step (multiple distinct files, sequenced changes, or an explicit task list), use todo_write to plan and track progress before implementing. For simple or single-step requests, skip planning and proceed directly.
+
+Ongoing: if you are tracking work, mark completed immediately when a step finishes; advance the next pending item in the same mutation. When the user says done/approved, update that turn if applicable.
+</Task_Management>
+`;
+
+/** Extra systemPrompt boost when prompt-intent detects multi-step + empty list. */
+export const COLD_START_BOOST = `
+<Task_Management_Priority>
+This request appears to involve multiple steps. If that is the case, consider creating a todo list with todo_write before starting. For single-step requests, proceed directly.
+</Task_Management_Priority>
+`;