packages/todo/tool-todo/README.md

# @deepseek-ai/dsh-tool-todo

English | [中文](README.zh.md)

The model-facing `todo_write` tool: the agent's whole task list, replaced wholesale on each call.

## What it does

Registers one tool, `todo_write(todos: [{ content, status }])`, on `ctx.tools`. The model sends the ENTIRE list every call — there are no partial updates or per-item edits. Each call appends a `todo/write` event (the full list snapshot) to the calling agent's session log via `agent.session.append('todo/write', { todos })`; the current list is the most recent such event (last-write-wins on replay).

`status` is one of `pending`, `in_progress`, or `completed`.

## Single owner

The list belongs to the ONE agent session that called the tool. There is no subagent/shared/swarm scope: a non-agent caller (no `exec.agent`) has nowhere to write the list and is rejected. This is a deliberate scope limit — see the Agent Note.

## Validation

Beyond the schema's type/required/enum checks, `execute` rejects an empty or duplicate `content`, and any item key beyond `content`/`status` — an extended item shape (ids, nesting) fails loud instead of silently flattening, keeping the logged snapshot equal to what the model believes it wrote. Any number of tasks may be `in_progress` at once — parallel work (concurrent subagents, background commands) legitimately runs several tasks simultaneously. Ordering and the discipline of keeping the list current are left to the model via the tool description.

## Rendering

The canonical result is `{ todos, counts: { pending, inProgress, completed } }`; its Native renderer returns the compact update acknowledgement. The tool also writes the full `todo/write` session event. UIs subscribe to the event stream and render that durable list themselves: the [TUI app](../../examples/tui-demo) shows it as a persistent plan, and the [web client](../../client/ui-conversation) renders a plan strip plus a dedicated tool row off `ConversationSnapshot.todos` ([Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-web-todo-display.md)).

## Export shape

A function/namespace plugin: it exports `name` / `inject` / `apply` and NO default. A stray `export default` would collapse the module via the Loader's `unwrapExports` and drop `inject` (see [docs/postmortem/0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md)).

## Model Experience

### Tool schema

#### What the model sees

The model sees the generated [`todo_write` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-todo).

#### Token effect

Fixed schema cost on every request where the tool is visible.

#### KV Cache effect

Prefix-stable while the definition and visibility are unchanged. Plugin lifecycle or scoped restrictions may invalidate reuse from this schema.

### Tool-call history and result

#### What the model sees

Each assistant tool call retains the entire replacement list in its arguments. Success returns exactly `Updated todo list: <pending> pending, <inProgress> in progress, <completed> completed.` Stable failures are ``Error: invalid todo: `content` must be a non-empty string``, `Error: invalid todos: duplicate content "<content>"`, and `Error: todo_write requires an owning agent session`. The full `todo/write` session event is UI and replay state, not a second model message.

#### Token effect

Token growth scales with every full list the model submits, and those call arguments remain until compaction. The result itself is small and fixed-shape.

#### KV Cache effect

Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.

## Known Limitations and Deferred Work

- **Single-owner scope only** — the list belongs to the one calling agent session; subagent/shared/swarm scopes are a deliberate cut (see § Single owner), and a non-agent caller is rejected.
- **The item shape is deliberately minimal** — `content` plus three-state `status`; whole-list replacement needs no stable id, priority, or active-form fields.
- **Whole-list replacement is the only operation** — no partial updates, no read-back tool; the model must resend the entire list each call.
feat(tool-todo): add the model-facing todo_write tool 2026-06-29 10:30:52 +08:00			`# @deepseek-ai/dsh-tool-todo`

docs: translate remaining READMEs 2026-07-26 05:03:53 +08:00			`English \| [中文](README.zh.md)`

feat(tool-todo): add the model-facing todo_write tool 2026-06-29 10:30:52 +08:00			The model-facing `todo_write` tool: the agent's whole task list, replaced wholesale on each call.

			`## What it does`

			Registers one tool, `todo_write(todos: [{ content, status }])`, on `ctx.tools`. The model sends the ENTIRE list every call — there are no partial updates or per-item edits. Each call appends a `todo/write` event (the full list snapshot) to the calling agent's session log via `agent.session.append('todo/write', { todos })`; the current list is the most recent such event (last-write-wins on replay).

refactor(acp): reduce bridge to automation protocol 2026-07-24 01:40:25 +08:00			`status` is one of `pending`, `in_progress`, or `completed`.
feat(tool-todo): add the model-facing todo_write tool 2026-06-29 10:30:52 +08:00
			`## Single owner`

Rename RFCs to Agent Notes 2026-07-19 22:50:49 +08:00			The list belongs to the ONE agent session that called the tool. There is no subagent/shared/swarm scope: a non-agent caller (no `exec.agent`) has nowhere to write the list and is rejected. This is a deliberate scope limit — see the Agent Note.
feat(tool-todo): add the model-facing todo_write tool 2026-06-29 10:30:52 +08:00
			`## Validation`

Merge branch 'web2-todo' into feat/todo-multi-in-progress 2026-07-27 14:01:00 +08:00			Beyond the schema's type/required/enum checks, `execute` rejects an empty or duplicate `content`, and any item key beyond `content`/`status` — an extended item shape (ids, nesting) fails loud instead of silently flattening, keeping the logged snapshot equal to what the model believes it wrote. Any number of tasks may be `in_progress` at once — parallel work (concurrent subagents, background commands) legitimately runs several tasks simultaneously. Ordering and the discipline of keeping the list current are left to the model via the tool description.
feat(tool-todo): add the model-facing todo_write tool 2026-06-29 10:30:52 +08:00
			`## Rendering`

Merge remote-tracking branch 'origin/master' into web2-todo 2026-07-26 03:33:57 +08:00			The canonical result is `{ todos, counts: { pending, inProgress, completed } }`; its Native renderer returns the compact update acknowledgement. The tool also writes the full `todo/write` session event. UIs subscribe to the event stream and render that durable list themselves: the [TUI app](../../examples/tui-demo) shows it as a persistent plan, and the [web client](../../client/ui-conversation) renders a plan strip plus a dedicated tool row off `ConversationSnapshot.todos` ([Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-web-todo-display.md)).
feat(tool-todo): add the model-facing todo_write tool 2026-06-29 10:30:52 +08:00
			`## Export shape`

			A function/namespace plugin: it exports `name` / `inject` / `apply` and NO default. A stray `export default` would collapse the module via the Loader's `unwrapExports` and drop `inject` (see [docs/postmortem/0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md)).
Add a gated Known Limitations and Deferred Work section to every package README 2026-07-10 01:51:50 +08:00
docs: address model experience review 2026-07-12 02:55:26 +08:00			`## Model Experience`

docs: replace model experience tables with sections 2026-07-13 22:26:33 +08:00			`### Tool schema`

docs: structure model experience fields 2026-07-19 18:08:42 +08:00			`#### What the model sees`
docs: replace model experience tables with sections 2026-07-13 22:26:33 +08:00
docs: structure model experience fields 2026-07-19 18:08:42 +08:00			The model sees the generated [`todo_write` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-todo).
docs: replace model experience tables with sections 2026-07-13 22:26:33 +08:00
docs: structure model experience fields 2026-07-19 18:08:42 +08:00			`#### Token effect`

			`Fixed schema cost on every request where the tool is visible.`

			`#### KV Cache effect`

			`Prefix-stable while the definition and visibility are unchanged. Plugin lifecycle or scoped restrictions may invalidate reuse from this schema.`
docs: document package KV cache effects 2026-07-19 17:39:50 +08:00
docs: replace model experience tables with sections 2026-07-13 22:26:33 +08:00			`### Tool-call history and result`

docs: structure model experience fields 2026-07-19 18:08:42 +08:00			`#### What the model sees`

feat(todo): allow several in_progress todos at once 2026-07-26 02:50:47 +08:00			Each assistant tool call retains the entire replacement list in its arguments. Success returns exactly `Updated todo list: <pending> pending, <inProgress> in progress, <completed> completed.` Stable failures are ``Error: invalid todo: `content` must be a non-empty string``, `Error: invalid todos: duplicate content "<content>"`, and `Error: todo_write requires an owning agent session`. The full `todo/write` session event is UI and replay state, not a second model message.
docs: structure model experience fields 2026-07-19 18:08:42 +08:00
			`#### Token effect`

			`Token growth scales with every full list the model submits, and those call arguments remain until compaction. The result itself is small and fixed-shape.`
docs: replace model experience tables with sections 2026-07-13 22:26:33 +08:00
docs: structure model experience fields 2026-07-19 18:08:42 +08:00			`#### KV Cache effect`
docs: apply verbatim model experience guidance repo-wide 2026-07-13 21:33:23 +08:00
docs: structure model experience fields 2026-07-19 18:08:42 +08:00			`Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.`
docs: document package KV cache effects 2026-07-19 17:39:50 +08:00
Add a gated Known Limitations and Deferred Work section to every package README 2026-07-10 01:51:50 +08:00			`## Known Limitations and Deferred Work`

			`- Single-owner scope only — the list belongs to the one calling agent session; subagent/shared/swarm scopes are a deliberate cut (see § Single owner), and a non-agent caller is rejected.`
refactor(acp): reduce bridge to automation protocol 2026-07-24 01:40:25 +08:00			- The item shape is deliberately minimal — `content` plus three-state `status`; whole-list replacement needs no stable id, priority, or active-form fields.
Add a gated Known Limitations and Deferred Work section to every package README 2026-07-10 01:51:50 +08:00			`- Whole-list replacement is the only operation — no partial updates, no read-back tool; the model must resend the entire list each call.`