fix(todo): address todo_write review feedback

docs/architecture.md

@@ -146,6 +146,7 @@ forever:
       session('assistant/message' {content, usage?})     log records what tool dispatch uses
       each tool-call (sequential, abort-checked between calls):
         session('tool/call'); ctx.tools.execute()     ⟵ waterfall tools/execute
+          tool execution may append tool-owned session events, e.g. `todo/write`
         session('tool/result')
       drain steering → session('steering/message'); emit agent/steering
       emit agent/step-end

docs/rfc/implemented/feature/2026-06-29-todo-write-tool.md

@@ -4,7 +4,7 @@ Status: implemented
 
 ## Problem
 
-The harness gives the model bash and subagent tools but no way to record a structured task list. A todo list serves two co-equal purposes: it steers the model to plan multi-step work and keep exactly one task active (anti-drift on long tasks), and it gives the human a live progress checklist. The ACP protocol has a native `plan` sessionUpdate that editors (Zed) already render, but the bridge never emitted one. Every reference coding agent surveyed (claude-code, opencode, codex, oh-my-pi, pi) ships some form of this; the harness had nothing.
+The harness gives the model bash and subagent tools but no way to record a structured task list. A todo list serves two co-equal purposes: it steers the model to plan multi-step work and keep the active task unambiguous (at most one active, exactly one while work remains), and it gives the human a live progress checklist. The ACP protocol has a native `plan` sessionUpdate that editors (Zed) already render, but the bridge never emitted one. Every reference coding agent surveyed (claude-code, opencode, codex, oh-my-pi, pi) ships some form of this; the harness had nothing.
 
 ## Decision
 

examples/acp-agent/cordis.snapshot.yml

@@ -16,7 +16,9 @@
 - id: llm-replay
   name: '@deepseek-ai/dsh-llm-replay'
 
-# Local bash executor (the agent's only tool, via agent-core's tool-bash schema).
+# Local bash executor for agent-core's tool-bash schema.
+# FIXME(config-comments): keep this executor note from implying bash is the
+# whole tool set; subagent and todo_write are loaded below.
 - id: bash
   name: '@deepseek-ai/dsh-bash-local'
   config:
@@ -43,9 +45,10 @@
       final result) — give it a complete, standalone instruction.
 
       For multi-step work, use the todo_write tool to track a task list:
-      send the WHOLE list each call (it replaces the previous one), keep
-      exactly one task in_progress, and mark a task completed as soon as it
-      is done. Skip it for trivial single-step tasks.
+      send the WHOLE list each call (it replaces the previous one), keep at
+      most one task in_progress (exactly one while work remains), and mark a
+      task completed as soon as it is done. Skip it for trivial single-step
+      tasks.
 
 # The subagent seam + both in-process backends + two model-facing tools —
 # identical to cordis.yml's wiring (only the LLM backend differs above): spawn

examples/acp-agent/cordis.yml

@@ -23,7 +23,9 @@
       - deepseek-v4-flash
       - deepseek-v4-pro
 
-# Local bash executor (the agent's only tool, via agent-core's tool-bash schema).
+# Local bash executor for agent-core's tool-bash schema.
+# FIXME(config-comments): keep this executor note from implying bash is the
+# whole tool set; subagent and todo_write are loaded below.
 - id: bash
   name: '@deepseek-ai/dsh-bash-local'
   config:
@@ -52,9 +54,10 @@
       final result) — give it a complete, standalone instruction.
 
       For multi-step work, use the todo_write tool to track a task list:
-      send the WHOLE list each call (it replaces the previous one), keep
-      exactly one task in_progress, and mark a task completed as soon as it
-      is done. Skip it for trivial single-step tasks.
+      send the WHOLE list each call (it replaces the previous one), keep at
+      most one task in_progress (exactly one while work remains), and mark a
+      task completed as soon as it is done. Skip it for trivial single-step
+      tasks.
 
 # The subagent seam + both in-process backends + two model-facing tools, as leaf
 # entries after the app (which provides ctx.agents/ctx.tools). spawn (a fresh

examples/coding-agent/cordis.yml

@@ -28,7 +28,9 @@
       - deepseek-v4-flash
       - deepseek-v4-pro
 
-# Local bash executor (the model's only tool, via agent-core's tool-bash schema).
+# Local bash executor for agent-core's tool-bash schema.
+# FIXME(config-comments): keep this executor note from implying bash is the
+# whole tool set; subagent and todo_write are loaded below.
 - id: bash
   name: '@deepseek-ai/dsh-bash-local'
   config:
@@ -66,9 +68,10 @@
       tests. Keep answers brief and factual.
 
       For multi-step work, use the todo_write tool to track a task list:
-      send the WHOLE list each call (it replaces the previous one), keep
-      exactly one task in_progress, and mark a task completed as soon as it
-      is done. Skip it for trivial single-step tasks.
+      send the WHOLE list each call (it replaces the previous one), keep at
+      most one task in_progress (exactly one while work remains), and mark a
+      task completed as soon as it is done. Skip it for trivial single-step
+      tasks.
 
 # The subagent seam + BOTH in-process backends + two model-facing tools, as leaf
 # entries after the app (which provides ctx.agents/ctx.tools). spawn (a fresh

examples/coding-agent/tests/harness.ts

@@ -19,14 +19,15 @@ import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
  * file's tests.
  */
 
-export const SYSTEM_PROMPT = 'You are a coding agent. Your only tool is bash; '
-  + 'do file operations with cat/grep/heredocs, check [exit code: N] markers, '
+export const SYSTEM_PROMPT = 'You are a coding agent. Use bash for file operations '
+  + 'with cat/grep/heredocs; check [exit code: N] markers, '
   + 'and report results briefly.'
 
 /** System prompt for the todo_write e2e: nudges the model to plan with the tool. */
 export const TODO_SYSTEM_PROMPT = 'You are a coding agent. For multi-step work, '
   + 'use the todo_write tool to track a task list: send the WHOLE list each call, '
-  + 'keep exactly one task in_progress, and mark a task completed as soon as it is done.'
+  + 'keep at most one task in_progress (exactly one while work remains), and mark '
+  + 'a task completed as soon as it is done.'
 
 export async function codingHarness(workdir: string, persistenceRoot?: string): Promise<Context> {
   const ctx = new Context()

examples/coding-agent/tests/todo-write.e2e.ts

@@ -1,7 +1,6 @@
 import { afterEach, describe, expect, it } from 'vitest'
 import type { Context } from 'cordis'
 import { AgentId } from '@deepseek-ai/dsh-agent'
-import type { TodoItem } from '@deepseek-ai/dsh-session'
 import { codingHarness, TODO_SYSTEM_PROMPT, waitForIdle } from './harness.ts'
 
 /**
@@ -42,14 +41,9 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('todo_write: real model records a
     expect(todoEvents.length).toBeGreaterThan(0)
 
     const todos = (todoEvents.at(-1)!).data.todos
-    expect(todos.length).toBeGreaterThanOrEqual(2)
-    // Every entry has a non-empty content and a valid status…
-    const valid: TodoItem['status'][] = ['pending', 'in_progress', 'completed']
-    for (const todo of todos) {
-      expect(todo.content.trim().length).toBeGreaterThan(0)
-      expect(valid).toContain(todo.status)
-    }
-    // …and the one-in-progress invariant the tool enforces held.
-    expect(todos.filter(t => t.status === 'in_progress').length).toBeLessThanOrEqual(1)
+    expect(todos).toEqual([
+      { content: 'inspect the failing test', status: 'in_progress' },
+      { content: 'apply the fix', status: 'pending' },
+    ])
   }, 120_000)
 })

packages/todo/tool-todo/src/index.ts

@@ -34,9 +34,11 @@ const DESCRIPTION =
   'Record and update a structured task list for the current work. Send the ENTIRE '
   + 'list every call — it REPLACES the previous list (there are no partial updates, '
   + 'no per-item edits). Use it to plan multi-step work and show progress: add one '
-  + 'todo per concrete step before you start. Keep EXACTLY ONE todo `in_progress` at '
-  + 'a time, and mark a todo `completed` the moment it is done (do not batch '
-  + 'completions). Skip the list for trivial single-step tasks. Statuses: `pending` '
+  + 'todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` '
+  + 'at a time; while work remains, exactly one active task should be '
+  + '`in_progress`. Mark a todo `completed` the moment it is done (do not batch '
+  + 'completions), and allow no `in_progress` item only once all work is complete. '
+  + 'Skip the list for trivial single-step tasks. Statuses: `pending` '
   + '(not started), `in_progress` (being worked on now), `completed` (finished).'
 
 /**