feat(tool-todo): add the model-facing todo_write tool

Add @deepseek-ai/dsh-tool-todo (a new packages/todo/ group): a model-facing
todo_write(todos: [{content, status}]) tool with whole-list-replace semantics.
Each call appends the full list as a todo/write event to the calling agent's
session log; the current list is the most recent such event (last-write-wins).
Single-owner — a non-agent caller is rejected. Beyond the schema's
type/required/enum checks, execute rejects empty/duplicate content and more than
one in_progress task, narrowing the loosely-typed args into a real TodoItem[].

Both UIs render off the existing session/event: the stdio UI prints a glyphed
checklist; the ACP bridge maps the list to a `plan` sessionUpdate (todosToPlan
synthesizes the priority ACP requires; status maps 1:1). Wired into the
coding-agent, acp-agent, and snapshot example configs with a system-prompt nudge.

Tests: unit (schema, validation, append/replace, no-agent rejection, presentCall,
HMR-safety, Loader export-shape guard), full-loop integration through the agent
loop, the ACP todosToPlan mapping + stream-update arm, the stdio render arm, and
a session/load replay that re-emits the plan. New-group TS wiring added to
tsconfig.base/json/build. RFC + a doc-inventory sweep (architecture, packages
README, AGENTS layout, cookbook group list, example READMEs) ship with it.

The todo-plan ACP snapshot scenario is recorded separately (needs an API key).

examples/README.md

@@ -15,7 +15,7 @@ Run with: `pnpm run demo:echo`. When prompted, type "echo <something>" to trigge
 
 ## coding-agent
 
-The real thing: DeepSeek V4 + the bash tool suite on the same `@deepseek-ai/dsh-stdio-agent` app. Where echo-agent proves the skeleton with mocks, this is a usable coding assistant.
+The real thing: DeepSeek V4 + the bash tool suite, `subagent` delegation, and the `todo_write` task tracker on the same `@deepseek-ai/dsh-stdio-agent` app. Where echo-agent proves the skeleton with mocks, this is a usable coding assistant.
 
 Run with: `pnpm run demo:coding` (needs `DEEPSEEK_API_KEY` in the environment or a gitignored repo-root `.env`). See [coding-agent/README.md](coding-agent/README.md) for details.
 

examples/acp-agent/cordis.snapshot.yml

@@ -42,6 +42,11 @@
       a fresh child agent (it works in its own context and returns only its
       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.
+
 # The subagent seam + both in-process backends + two model-facing tools —
 # identical to cordis.yml's wiring (only the LLM backend differs above): spawn
 # and fork are each reachable via a dsh-tool-subagent bound to it with a distinct
@@ -70,3 +75,8 @@
   config:
     provider: fork
     toolName: subagent_fork
+
+# The model-facing todo_write tool — identical to cordis.yml's wiring, so a
+# replayed todo_write tool call resolves to a real tool during snapshot replay.
+- id: tool-todo
+  name: '@deepseek-ai/dsh-tool-todo'

examples/acp-agent/cordis.yml

@@ -51,6 +51,11 @@
       a fresh child agent (it works in its own context and returns only its
       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.
+
 # 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
 # child) and fork (a child seeded with the parent's completed-turn prefix) are
@@ -81,3 +86,8 @@
   config:
     provider: fork
     toolName: subagent_fork
+
+# The model-facing todo_write tool: whole-list task tracking written to the
+# session log (todo/write), surfaced to the ACP client as a `plan` update.
+- id: tool-todo
+  name: '@deepseek-ai/dsh-tool-todo'

examples/coding-agent/README.md

@@ -12,7 +12,7 @@ The first REAL agent wiring: DeepSeek V4 + the bash tool suite + stdio chat
 pnpm run demo:coding
 ```
 
-Type a coding task. The agent's only tools are `bash` (+ `bash_output` / `bash_kill` for background tasks): file reads, writes, searches, and test runs all happen through shell commands, each in a fresh `bash -c` (the system prompt tells the model to pass `workdir` instead of `cd`). Reasoning streams dimmed; tool calls/results render inline.
+Type a coding task. The agent works through `bash` (+ `bash_output` / `bash_kill` for background tasks): file reads, writes, searches, and test runs all happen through shell commands, each in a fresh `bash -c` (the system prompt tells the model to pass `workdir` instead of `cd`). It can also delegate with `subagent`/`subagent_fork` and track multi-step work with `todo_write` (a whole-list task tracker rendered as a checklist). Reasoning streams dimmed; tool calls/results render inline.
 
 ```
 > fix the failing test in /path/to/project

examples/coding-agent/cordis.yml

@@ -44,7 +44,7 @@
     # under ./.sessions); unset starts a fresh session each run.
     resumeSessionId: !!js process.env.RESUME_SESSION_ID
     persistenceRoot: './.sessions'
-    welcome: 'coding-agent ready. Give it a coding task (its tools are bash and subagent).'
+    welcome: 'coding-agent ready. Give it a coding task (its tools are bash, subagent, and todo_write).'
     systemPrompt: |
       You are coding-agent, a CLI coding assistant.
 
@@ -65,6 +65,11 @@
       failures before moving on. Verify your work by running the code or
       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.
+
 # 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
 # child) and fork (a child seeded with the parent's completed-turn prefix) are
@@ -96,3 +101,8 @@
   config:
     provider: fork
     toolName: subagent_fork
+
+# The model-facing todo_write tool: whole-list task tracking written to the
+# session log (todo/write), rendered as a stdio checklist / ACP plan.
+- id: tool-todo
+  name: '@deepseek-ai/dsh-tool-todo'