@@ -57,7 +57,7 @@ This replaces: `yoctocolors`, `yoctomarkdown`, `yoctoselect`, and all our custom
5757
5858 ## Tools
5959
60-Two built-in tools, plus a read-only image tool. Plugins may add more (see [Plugins](#plugins)).
60+Four built-in tools, plus a read-only image tool. Plugins may add more (see [Plugins](#plugins)).
6161
6262 ### `shell`
6363
@@ -85,6 +85,31 @@ Implementation details:
8585 - Returns a confirmation or error message — no diff output (the agent already knows what it wrote).
8686 - Encoding: reads and writes UTF-8. Preserves the file's existing line endings.
8787
88+### `todoWrite`
89+
90+Creates or updates the session todo list incrementally. Use it to track multi-step or non-trivial work, keep progress visible, and mark tasks complete explicitly.
91+
92+Implementation details:
93+
94+- Takes a `todos` array. Each item must include `content` and `status`.
95+- `content` is the exact matching key. If an item with the same content already exists, its status is updated in place. Otherwise a new item is appended.
96+- Allowed statuses: `pending`, `in_progress`, `completed`, `cancelled`.
97+- `cancelled` removes the matching item entirely.
98+- Items omitted from a call remain unchanged.
99+- Successful results return the full current todo-list snapshot in insertion order. Surviving items keep their relative order; newly added items are appended.
100+- Todo content must not be empty or whitespace-only and must stay within a small fixed length limit.
101+- Todo state is session-local and derived from the latest successful todo snapshot persisted in message history, so `/undo`, `/fork`, session reload, and session switching all restore the correct list automatically.
102+
103+### `todoRead`
104+
105+Returns the current session todo list.
106+
107+Implementation details:
108+
109+- Takes no arguments.
110+- Returns the full current todo-list snapshot, which may be empty.
111+- The returned snapshot uses the same shape as `todoWrite` success results.
112+
88113 ### `readImage`
89114
90115 Reads an image file and returns it as `ImageContent` (base64 + mimeType). This lets the model inspect screenshots, diagrams, or any image in the repo without the user explicitly attaching it.
@@ -209,21 +234,26 @@ The core runtime. Streaming is the default behavior throughout the turn: user-vi
209234 3. **Stream to LLM** — call `streamSimple(model, context, options)` from pi-ai. Iterate over the event stream:
210235 - `text_delta` / `thinking_delta` / `toolcall_delta` → update the in-progress assistant message and the UI incrementally (stream raw markdown text, show thinking if enabled, accumulate tool call arguments as they arrive).
211236 - `toolcall_end` → finalize the structured tool call in the in-progress `AssistantMessage`.
212- - `done` → append the `AssistantMessage` to history and DB. Update cumulative stats. If `stopReason` is `"toolUse"`, go to step 4. If `"stop"` or `"length"` and queued steering messages exist, go to step 5. Otherwise return to the input prompt.
237+ - `done` → append the `AssistantMessage` to history and DB. Update cumulative stats. If `stopReason` is `"toolUse"`, go to step 4. If `"stop"` or `"length"` and queued steering messages exist, go to step 6. If `"stop"` or `"length"` and incomplete todo items remain, go to step 5. Otherwise return to the input prompt.
213238 - `error` → display error in the log, return to the input prompt.
214239
215240 4. **Tool execution** — when the LLM requests tool calls:
216- - Execute each tool call. For `shell`: run the command, capture output, truncate if needed. For `edit`: perform the replacement. For `readImage`: read and base64-encode the file. For plugin tools: delegate to the plugin.
241+ - Execute each tool call. For `shell`: run the command, capture output, truncate if needed. For `edit`: perform the replacement. For `todoWrite`: apply the incremental todo changes and return the full current list. For `todoRead`: return the full current list. For `readImage`: read and base64-encode the file. For plugin tools: delegate to the plugin.
217242 - Each result becomes a `ToolResultMessage` appended to history and DB (same turn number).
218- - After all tool results are appended, if queued steering messages exist go to step 5; otherwise loop back to step 2 (re-stream with the updated context).
243+ - After all tool results are appended, if queued steering messages exist go to step 6; otherwise loop back to step 2 (re-stream with the updated context).
244+
245+5. **Todo reminders** — when the assistant tries to stop while incomplete todo items still exist:
246+ - Inject a model-visible reminder listing the current `pending` and `in_progress` items, then loop back to step 2.
247+ - Reminders are ephemeral: they are included in model context for the follow-up request but are not rendered in the conversation pane and are not persisted to the session DB.
248+ - If the exact same incomplete-todo set was already reminded during the current run, do not inject a duplicate reminder. In that case the turn ends normally instead of looping forever.
219249
220-5. **Steering messages** — if the user submits a model-visible message while an active run is already in progress, mini-coder queues it instead of dropping it or interrupting the current work.
250+6. **Steering messages** — if the user submits a model-visible message while an active run is already in progress, mini-coder queues it instead of dropping it or interrupting the current work.
221251 - Steering messages are consumed FIFO at the next model-request boundary: after the current assistant message is finalized and after any tool calls already requested by that assistant message have completed and their tool results have been appended.
222252 - When consumed, each steering message is appended to history and DB as a normal `UserMessage`, starting a new conversational turn.
223253 - After appending the next queued steering message, loop back to step 2 so the next `streamSimple(...)` call sees the updated history.
224254 - Submitting a steering message does not abort the current stream or running tool. Use `Escape` to interrupt immediately.
225255
226-6. **Interrupt** — if the user presses `Escape` during streaming with no overlay open:
256+7. **Interrupt** — if the user presses `Escape` during streaming with no overlay open:
227257 - Abort the stream via `AbortSignal`.
228258 - The partial `AssistantMessage` (with `stopReason: "aborted"`) is appended to history and DB as-is. This preserves context so the LLM knows what it was doing when interrupted.
229259 - Return to the input prompt with focus on the input. The user can continue the conversation or `/undo` the interrupted turn.
@@ -305,11 +335,13 @@ The current environment is:
305335
306336 ### Task management
307337
308-- Use the /tmp or equivalent temp directory to make a To-do list for your task.
309-- This to-do list is **extremly** helpful for breaking down your task into smaller less complex steps.
310-- Not using a to-do list may cause you to forget important steps, or loose focus of the user request, that would be unacceptable.
311-- Keep the to-do list up-to-date above all, mark your completions as soon as you verify them.
312-- A to-do item is only complete if verification was successful and thorough.
338+- Use `todoWrite` proactively for multi-step or non-trivial tasks.
339+- Capture new requirements in the todo list as soon as you understand them.
340+- Use `todoRead` when you need to inspect the current list before updating it or when the user asks for the current plan/status.
341+- Keep the todo list up-to-date above all; mark tasks `in_progress` before starting them and `completed` as soon as verification succeeds.
342+- A todo item is only complete if the requested work is actually finished and verified to the degree the task requires.
343+- Use `cancelled` to remove tasks that are no longer relevant.
344+- Skip todo tools for single trivial tasks and purely conversational/informational requests.
313345 - You have the option to delegate tasks to copies of yourself with `mc -p "subtask prompt"` in the shell.
314346 - Delegate when you are orchestarting a large to-do/plan execution.
315347 ```
@@ -526,16 +558,17 @@ Tool blocks share a common frame: a left border (`│`) plus a compact header pi
526558 - **Assistant messages**: streamed raw markdown rendered via cel-tui's `SyntaxHighlight` component on the default background so the log stays copy-friendly and preserves markdown markers. Thinking/reasoning content is collapsible (shown or hidden according to the user's persisted `/reasoning` preference; defaults to shown when no setting exists).
527559 - **Tool calls — shell**: rendered in the shared tool frame. The assistant tool call streams the command as it arrives. The command preview and shell tool result body use [verbose tool rendering](#verbose-tool-rendering). Shell tool results render the tool output content below a `shell <-` header.
528560 - **Tool calls — edit**: rendered in the shared tool frame. The in-progress tool-call preview shows the target path followed by the streamed `oldText` and `newText` bodies. Old text is styled as removed and new text as added, but the preview does not render literal `-`/`+` diff prefixes. The preview body uses [verbose tool rendering](#verbose-tool-rendering). Successful results render a compact confirmation block (`edit <-` plus the file path); errors render the returned error text.
561+- **Tool calls — todoWrite / todoRead**: rendered in the shared tool frame. Successful results render the full current todo list as a structured themed checklist with status markers (`[ ]`, `[~]`, `[x]`). This checklist is always shown in full and never truncated, regardless of `/verbose`. Errors render the returned error text.
529562 - **Tool calls — readImage**: rendered in the shared tool frame. The assistant tool call streams the path as it arrives. Successful results render a compact result block (`read image <-` plus the file path) rather than rendering the image itself.
530563 - **Tool calls — plugin tools**: rendered in the shared tool frame, prefixed with plugin/tool name when available.
531-- **UI messages**: internal app messages such as `/help` output, OAuth progress, `/fork` notices, and other session-local notices. They are rendered in the conversation log, persisted with the session, excluded from model context, and do not participate in conversational turn numbering.
564+- **UI messages**: internal app messages such as `/help` output, OAuth progress, `/fork` notices, and other session-local notices. They are rendered in the conversation log, persisted with the session, excluded from model context, and do not participate in conversational turn numbering. `/todo` output is also UI-only, but it renders using the same structured todo-checklist block as todo tool results instead of plain info text.
532565 - **Errors**: one-line summary, styled distinctly.
533566
534567 #### Verbose tool rendering
535568
536569 `/verbose` controls a single persisted UI preference for how tool-call previews and selected tool-result bodies are displayed in the conversation log.
537570
538-- Scope: shell tool-call bodies, shell tool-result bodies, edit tool-call preview bodies, and edit error results only. Successful edit results stay compact in both modes.
571+- Scope: shell tool-call bodies, shell tool-result bodies, edit tool-call preview bodies, and edit error results only. Successful edit results stay compact in both modes. Todo tool results ignore `/verbose` and always show the full current list.
539572 - Default: off when no saved setting exists.
540573 - Off: show as many trailing logical lines as fit within a fixed rendered-height preview, followed by `And X lines more` when earlier lines are hidden. The preview height stays stable for a given block, so wrapped long lines do not make the log jump while content streams.
541574 - On: show the full stored tool result or preview body.
@@ -727,7 +760,8 @@ add tests for undo_
727760 | `/fork` | Fork the current conversation into a new session. Copies the full message history, continues from here independently, and appends a UI-only `Forked session.` notice in the new session. The original session is preserved. …
728761 | `/undo` | Remove the last conversational turn from history: the most recent user message and all assistant/tool messages that followed in that turn. Persisted UI messages are not part of turns and are not removed by `/undo`. Context-only — does not revert filesystem changes. …
729762 | `/reasoning` | Toggle display of model thinking/reasoning content in the log. The new on/off state is persisted immediately and restored on launch. When no setting exists yet, reasoning defaults to shown. …
730-| `/verbose` | Toggle [verbose tool rendering](#verbose-tool-rendering) for shell previews/results, edit previews, and edit errors. Successful edit results stay compact regardless of this setting. …
763+| `/verbose` | Toggle [verbose tool rendering](#verbose-tool-rendering) for shell previews/results, edit previews, and edit errors. Successful edit results stay compact regardless of this setting. Todo tool results always render in full. …
764+| `/todo` | Append the current session todo list to the conversation pane as a UI-only checklist block. The message is persisted with the session, excluded from model context, and does not create a session by itself when no session exists yet. …
731765 | `/login` | Interactive OAuth login. Shows a selector with available OAuth providers and their login status (logged in / not logged in). Selecting a provider starts the browser-based OAuth flow. Uses pi-ai's OAuth registry. Credentials are persisted to the app data directory and used for provider discovery on subsequent launches. …
732766 | `/logout` | Interactive OAuth logout. Shows a selector with logged-in OAuth providers. Selecting one clears its saved credentials. …
733767 | `/effort` | Interactive effort selector. Shows the four reasoning levels (`low`, `medium`, `high`, `xhigh`) with the current level highlighted. Updates the status bar immediately, and the selected effort is persisted immediately as the user's global default. The session record's `effort` field is not updated (it reflects the initial choice, like `/model`). …
@@ -754,7 +788,7 @@ Prompt source in headless mode:
754788 - If headless mode was selected because `stdout` is not a TTY but `stdin` is still interactive, startup fails with a clear error unless `-p` was provided. Headless mode does not fall back to an interactive prompt.
755789 - Empty or whitespace-only headless input is an error.
756790
757-Input parsing in headless mode reuses the same rules as the interactive input area for plain text, `/skill:name`, and standalone image-file paths. Interactive slash commands such as `/model`, `/session`, `/new`, `/fork`, `/undo`, `/login`, `/logout`, `/effort`, and `/help` are not available in headless mode and should fail clearly rather than attempting to open interactive UI.
791+Input parsing in headless mode reuses the same rules as the interactive input area for plain text, `/skill:name`, and standalone image-file paths. Interactive slash commands such as `/model`, `/session`, `/new`, `/fork`, `/undo`, `/login`, `/logout`, `/effort`, `/todo`, and `/help` are not available in headless mode and should fail clearly rather than attempting to open interactive UI.
758792
759793 ### Headless text output
760794
@@ -895,6 +929,8 @@ CREATE INDEX idx_prompt_history_created_at ON prompt_history(created_at, id);
895929
896930 **Messages as JSON blobs**: pi-ai's `Message` type (UserMessage, AssistantMessage, ToolResultMessage) is already serializable, and we also persist internal UI-only log entries in the same table. We store the full object as JSON in `data` rather than normalizing into columns. Session load returns the complete chronological log; model context construction filters out UI-only messages before replaying the remaining pi-ai messages into a pi-ai `Context`.
897931
932+**Todo state lives in message history**: there is no separate todo table. The current todo list is reconstructed from the latest successful persisted todo snapshot found in session messages. Because that snapshot rides along with normal message history, `/undo`, `/fork`, session reload, and session switching all restore the expected todo state automatically.
933+
898934 **Turn grouping**: the `turn` column groups only conversational messages. A turn is: one user message + the assistant messages and tool result messages produced after that user message until the next user message is consumed. Persisted UI messages are stored alongside them but have `turn = NULL`, so they remain visible in session history without becoming part of `/undo`. Queued steering messages submitted mid-run still start their own turn when they are consumed; tool results already requested b …
899935
900936 **Cumulative stats are computed, not stored**: the status bar's cumulative `in`, `out`, and `$cost` values are computed by summing `usage` from assistant messages on session load (deserialize all messages, filter for `role: "assistant"`, sum their `usage` fields). The message count per session is small (hundreds), so this is fast. No separate counters to keep in sync. During an active session, a running in-memory accumulator is updated after each assistant message to avoid re-scanning. `context% …