Add eca__todo tool for multi-step task planning and tracking

Introduces a new native tool `eca__todo` to help the agent plan, organize,
and track progress across complex, multi-step tasks.

- Maintains a persistent TODO state per chat in the DB
- Supports operations: plan, add, update, start, complete, delete, clear
- Includes dependency tracking (blocked_by) and cycle detection
- Enforces sequential execution by default to prevent improper batching
- Covered by comprehensive unit and integration tests

Author: zikajk

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Add Todo tool #246
+
 ## 0.109.5
 
 - Fix clear messages to reset usage tokens as well.

resources/prompts/code_agent.md

@@ -27,3 +27,22 @@ You have tools at your disposal to solve the coding task. Follow these rules reg
 2. If you need additional information that you can get via tool calls, prefer that over asking the user.
 3. If you are not sure about file content or codebase structure pertaining to the user's request, use your tools to read files and gather the relevant information: do NOT guess or make up an answer.
 4. You have the capability to call multiple tools in a single response, batch your tool calls together for optimal performance.
+
+{% if toolEnabled_eca__todo %}
+## TODO Tool
+
+You have access to a `eca__todo` tool for tracking multi-step work within this chat.
+
+### Workflow:
+1. Use `plan` to create TODO with goal and tasks
+2. Use `start` before working on a task (marks it as in_progress)
+3. Use `complete` only for tasks that are actually finished; for each targeted task that has `done_when`, verify it first.
+4. Use `add` if you discover additional work
+5. When a plan is fully completed and no further work is needed for the current goal, always use the `clear` operation to clean up the workspace.
+6. Delegate focused work to subagents when helpful. Work sequentially by default; batch operations ONLY for tasks executing simultaneously.
+
+### done_when guidance:
+- `done_when` is optional.
+- Prefer setting it for non-trivial tasks where completion should be objectively verifiable.
+- For trivial tasks, you may omit it to keep tracking lightweight.
+{% endif %}

resources/prompts/tools/todo.md

@@ -0,0 +1,41 @@
+Task management for planning and tracking work.
+
+When to Use:
+- Tasks requiring 3 or more distinct steps
+- User provides multiple tasks (numbered lists, comma-separated items)
+- Non-trivial work that benefits from planning and tracking
+- User explicitly requests task tracking or a todo list
+
+When NOT to Use:
+- Single, trivial task completable in very few steps
+- Purely informational or conversational queries
+- Quick fixes where tracking adds no organizational value
+
+Operations:
+- read: View current TODO state
+- plan: Create/replace TODO with goal and tasks (required: goal, tasks)
+- add: Append task(s) to existing TODO
+- update: Modify a single task metadata by `id` (content, priority, done_when, blocked_by) — cannot change status
+- start: Begin work on tasks by `ids` (sets to in_progress; rejects blocked or done tasks)
+- complete: Mark tasks by `ids` as done (verify done_when criteria first)
+- delete: Remove tasks by `ids`
+- clear: Reset entire TODO (removes goal and all tasks)
+
+Workflow:
+1. Use 'plan' to create TODO with goal and initial tasks
+2. Use 'start' before working on a task — marks it as in_progress
+3. Work sequentially by default. Batch 'start' or 'complete' operations (using multiple 'ids') ONLY for independent tasks being executed simultaneously (e.g., via subagents).
+4. Use 'complete' only for tasks that are actually finished; for each targeted task that has `done_when`, verify it first — the response tells you which tasks got unblocked
+5. Use 'add' if you discover additional work during execution
+6. When a plan is fully completed and no further work is needed for the current goal, always use the 'clear' operation to clean up the workspace.
+
+How to use done_when:
+- `done_when` is optional.
+- Use it for non-trivial tasks where completion must be verifiable (tests passing, behavior implemented, specific file changes, etc.).
+- For trivial/obvious tasks, you may omit `done_when` to avoid overhead.
+
+Task Completion Integrity:
+- Mark tasks complete as soon as they are finished.
+- If a task has `done_when`, ONLY mark it as completed when ALL `done_when` criteria are actually met (for each task in a batch).
+- Do NOT complete if: tests failing, implementation partial, or errors unresolved.
+- When completing reveals follow-up work, use 'add' to append new tasks.

src/eca/db.clj

@@ -60,6 +60,14 @@
                         :messages [{:role (or "user" "assistant" "tool_call" "tool_call_output" "reason")
                                     :content (or :string [::any-map]) ;; string for simple text, map/vector for structured content
                                     :content-id :string}]
+                        :todo {:goal :string
+                               :next-id :number
+                               :tasks [{:id :number
+                                        :content :string
+                                        :status (or :pending :in-progress :done)
+                                        :priority (or :high :medium :low)
+                                        :done-when (or :string nil)
+                                        :blocked-by #{:number}}]}
                         :tool-calls {"<tool-call-id>"
                                      {:status (or :initial :preparing :check-approval :waiting-approval
                                                   :execution-approved :executing :rejected :cleanup

src/eca/features/tools.clj

@@ -13,6 +13,7 @@
    [eca.features.tools.mcp.clojure-mcp]
    [eca.features.tools.shell :as f.tools.shell]
    [eca.features.tools.skill :as f.tools.skill]
+   [eca.features.tools.todo :as f.tools.todo]
    [eca.features.tools.util :as tools.util]
    [eca.logger :as logger]
    [eca.messenger :as messenger]
@@ -148,6 +149,7 @@
           f.tools.editor/definitions
           f.tools.chat/definitions
           f.tools.skill/definitions
+          f.tools.todo/definitions
           (f.tools.agent/definitions config)
           (f.tools.custom/definitions config))))
 
@@ -156,9 +158,11 @@
 
 (defn ^:private filter-subagent-tools
   "Filter tools for subagent execution.
-   Excludes spawn_agent to prevent nesting."
+
+   - Excludes spawn_agent to prevent nesting.
+   - Excludes todo because TODO state is currently chat-local; it should be managed by the parent agent."
   [tools]
-  (filterv #(not= "spawn_agent" (:name %)) tools))
+  (filterv #(not (contains? #{"spawn_agent" "todo"} (:name %))) tools))
 
 (defn all-tools
   "Returns all available tools, including both native ECA tools