feat(todo): add todo_write tool for task tracking (#2362)

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Tushar <tusharmath@gmail.com>

Author: 3 people

Cargo.lock

@@ -0,0 +1,18 @@
+# Evaluation for checking appropriate todo_write tool usage
+run:
+  - git clone --depth=1 --branch main https://github.com/antinomyhq/forge .
+  - FORGE_OVERRIDE_PROVIDER=open_router FORGE_OVERRIDE_MODEL={{model}} FORGE_DEBUG_REQUESTS='{{dir}}/context.json' forgee -p '{{task}}'
+parallelism: 3
+timeout: 240
+early_exit: true
+validations:
+  - name: "Uses todo_write tool for multi-step tasks"
+    type: shell
+    command: |
+      # Check if todo_write was called at least once
+      jq -e '[.messages[]?.tool_calls[]? | select(.function?.name == "todo_write")] | length > 0' {{dir}}/context.json
+
+sources:
+  - value:
+      - model: "anthropic/claude-sonnet-4.5"
+  - csv: todo_write_usage_tasks.csv

benchmarks/evals/todo_write_usage/task.yml

@@ -0,0 +1,7 @@
+task
+"Add a dark mode toggle to the application. Create the toggle component, add state management, implement CSS styles, and update existing components to support theme switching."
+"Refactor the authentication system: extract the login logic into a separate service, update all imports, add unit tests, and update the documentation."
+"Implement a new feature for exporting user data. Add the export button to the UI, create the export service with CSV and JSON support, add backend API endpoint, and write integration tests."
+"Optimize the application performance. Profile the code to identify bottlenecks, implement memoization where needed, add virtualization for long lists, optimize images, and measure the improvement."
+"Update the project dependencies. Review the package.json for outdated packages, update them one by one testing after each, update the lock file, run all tests, and document any breaking changes."
+"Set up CI/CD pipeline. Configure GitHub Actions workflow, add build steps, set up testing, add deployment to staging, configure production deployment with approval, and document the process."

benchmarks/evals/todo_write_usage/todo_write_usage_tasks.csv

@@ -418,6 +418,61 @@ mod tests {
         insta::assert_snapshot!(actual);
     }
 
+    #[test]
+    fn test_template_engine_renders_todo_write() {
+        use forge_domain::{
+            ContextSummary, Role, SummaryBlock, SummaryMessage, SummaryTool, SummaryToolCall, Todo,
+            TodoChange, TodoChangeKind, TodoStatus,
+        };
+
+        // Create test data with todo_write tool call showing a diff
+        let changes = vec![
+            TodoChange {
+                todo: Todo::new("Implement user authentication")
+                    .id("1")
+                    .status(TodoStatus::Completed),
+                kind: TodoChangeKind::Updated,
+            },
+            TodoChange {
+                todo: Todo::new("Add database migrations")
+                    .id("2")
+                    .status(TodoStatus::InProgress),
+                kind: TodoChangeKind::Added,
+            },
+            TodoChange {
+                todo: Todo::new("Write documentation")
+                    .id("3")
+                    .status(TodoStatus::Pending),
+                kind: TodoChangeKind::Removed,
+            },
+        ];
+
+        let messages = vec![
+            SummaryBlock::new(
+                Role::User,
+                vec![SummaryMessage::content("Create a task plan")],
+            ),
+            SummaryBlock::new(
+                Role::Assistant,
+                vec![
+                    SummaryToolCall {
+                        id: Some(forge_domain::ToolCallId::new("call_1")),
+                        tool: SummaryTool::TodoWrite { changes },
+                        is_success: true,
+                    }
+                    .into(),
+                ],
+            ),
+        ];
+
+        let context_summary = ContextSummary { messages };
+        let data = serde_json::json!({"messages": context_summary.messages});
+
+        let actual = render_template(&data);
+
+        insta::assert_snapshot!(actual);
+    }
+
     #[tokio::test]
     async fn test_render_summary_frame_snapshot() {
         // Load the conversation fixture

crates/forge_app/src/compact.rs

@@ -119,6 +119,12 @@ impl FormatContent for ToolCatalog {
                     .sub_title(input.name.to_lowercase())
                     .into(),
             ),
+            ToolCatalog::TodoWrite(input) => Some(
+                TitleFormat::debug("Update Todos")
+                    .sub_title(format!("{} item(s)", input.todos.len()))
+                    .into(),
+            ),
+            ToolCatalog::TodoRead(_) => Some(TitleFormat::debug("Read Todos").into()),
         }
     }
 }

crates/forge_app/src/fmt/fmt_input.rs

@@ -2,6 +2,7 @@ use forge_display::DiffFormat;
 use forge_domain::{ChatResponseContent, Environment, TitleFormat};
 
 use crate::fmt::content::FormatContent;
+use crate::fmt::todo_fmt::{format_todos, format_todos_diff};
 use crate::operation::ToolOperation;
 use crate::utils::format_display_path;
 
@@ -30,6 +31,12 @@ impl FormatContent for ToolOperation {
                 ));
                 title.into()
             }),
+            ToolOperation::TodoWrite { before, after } => Some(ChatResponseContent::ToolOutput(
+                format_todos_diff(before, after),
+            )),
+            ToolOperation::TodoRead { output } => {
+                Some(ChatResponseContent::ToolOutput(format_todos(output)))
+            }
             ToolOperation::FsRead { input: _, output: _ }
             | ToolOperation::FsRemove { input: _, output: _ }
             | ToolOperation::FsSearch { input: _, output: _ }

crates/forge_app/src/fmt/fmt_output.rs

@@ -1,3 +1,4 @@
 pub mod content;
 pub mod fmt_input;
 pub mod fmt_output;
+pub mod todo_fmt;

crates/forge_app/src/fmt/mod.rs

@@ -0,0 +1,8 @@
+---
+source: crates/forge_app/src/fmt/todo_fmt.rs
+expression: actual
+---
+
+  󰄵 Task 1
+  󰄱 Task 3
+  󰄱 Task 2

crates/forge_app/src/fmt/snapshots/forge_app__fmt__todo_fmt__tests__todo_write_mixed_changes_snapshot.snap

@@ -0,0 +1,164 @@
+use forge_domain::Todo;
+
+/// Controls the styling applied to a rendered todo line.
+enum TodoLineStyle {
+    /// Bold styling used for new or changed todos.
+    Bold,
+    /// Dim styling used for unchanged todos.
+    Dim,
+}
+
+/// Renders one todo line with icon and ANSI styling.
+///
+/// # Arguments
+///
+/// * `todo` - Todo item to render.
+/// * `line_style` - Emphasis style for the line.
+fn format_todo_line(todo: &Todo, line_style: TodoLineStyle) -> String {
+    use console::style;
+    use forge_domain::TodoStatus;
+
+    let checkbox = match todo.status {
+        TodoStatus::Completed => "󰄵",
+        TodoStatus::InProgress => "󰄗",
+        TodoStatus::Pending => "󰄱",
+    };
+
+    let content = match todo.status {
+        TodoStatus::Completed => style(todo.content.as_str()).strikethrough().to_string(),
+        _ => todo.content.clone(),
+    };
+
+    let line = format!("  {checkbox} {content}");
+    let styled = match (&todo.status, line_style) {
+        (TodoStatus::Pending, TodoLineStyle::Bold) => style(line).white().bold().to_string(),
+        (TodoStatus::Pending, TodoLineStyle::Dim) => style(line).white().dim().to_string(),
+        (TodoStatus::InProgress, TodoLineStyle::Bold) => style(line).cyan().bold().to_string(),
+        (TodoStatus::InProgress, TodoLineStyle::Dim) => style(line).cyan().dim().to_string(),
+        (TodoStatus::Completed, TodoLineStyle::Bold) => style(line).green().bold().to_string(),
+        (TodoStatus::Completed, TodoLineStyle::Dim) => style(line).green().dim().to_string(),
+    };
+
+    format!("{styled}\n")
+}
+
+/// Formats a todo diff showing all todos in `after` plus removed todos from
+/// `before`.
+///
+/// # Arguments
+///
+/// * `before` - Previous todo list state.
+/// * `after` - New todo list state.
+pub(crate) fn format_todos_diff(before: &[Todo], after: &[Todo]) -> String {
+    use console::style;
+
+    let before_map: std::collections::HashMap<&str, &Todo> =
+        before.iter().map(|todo| (todo.id.as_str(), todo)).collect();
+    let after_ids: std::collections::HashSet<&str> =
+        after.iter().map(|todo| todo.id.as_str()).collect();
+
+    let mut result = "\n".to_string();
+
+    for todo in after {
+        let previous = before_map.get(todo.id.as_str()).copied();
+        let is_new = previous.is_none();
+        let is_changed = previous
+            .map(|item| item.status != todo.status || item.content != todo.content)
+            .unwrap_or(false);
+
+        let line_style = if is_new || is_changed {
+            TodoLineStyle::Bold
+        } else {
+            TodoLineStyle::Dim
+        };
+
+        result.push_str(&format_todo_line(todo, line_style));
+    }
+
+    for todo in before {
+        if !after_ids.contains(todo.id.as_str()) {
+            let content = style(todo.content.as_str()).strikethrough().to_string();
+            result.push_str(&format!("  {}\n", style(format!("󰄱 {content}")).red()));
+        }
+    }
+
+    result
+}
+
+/// Formats todos as ANSI-styled checklist lines.
+///
+/// # Arguments
+///
+/// * `todos` - Todo list to format.
+pub(crate) fn format_todos(todos: &[Todo]) -> String {
+    if todos.is_empty() {
+        return String::new();
+    }
+
+    let mut result = "\n".to_string();
+
+    for todo in todos {
+        result.push_str(&format_todo_line(todo, TodoLineStyle::Dim));
+    }
+
+    result
+}
+
+#[cfg(test)]
+mod tests {
+    use console::strip_ansi_codes;
+    use forge_domain::{ChatResponseContent, Environment, Todo, TodoStatus};
+    use insta::assert_snapshot;
+
+    use crate::fmt::content::FormatContent;
+    use crate::operation::ToolOperation;
+
+    fn fixture_environment() -> Environment {
+        use fake::{Fake, Faker};
+
+        let max_bytes: f64 = 250.0 * 1024.0;
+        let fixture: Environment = Faker.fake();
+
+        fixture
+            .max_search_lines(25)
+            .max_search_result_bytes(max_bytes.ceil() as usize)
+            .fetch_truncation_limit(55)
+            .max_read_size(10)
+            .stdout_max_prefix_length(10)
+            .stdout_max_suffix_length(10)
+            .max_line_length(100)
+            .max_file_size(0)
+    }
+
+    fn fixture_todo(content: &str, id: &str, status: TodoStatus) -> Todo {
+        Todo::new(content).id(id).status(status)
+    }
+
+    fn fixture_todo_write_output(before: Vec<Todo>, after: Vec<Todo>) -> String {
+        let setup = ToolOperation::TodoWrite { before, after };
+        let actual = setup.to_content(&fixture_environment());
+
+        if let Some(ChatResponseContent::ToolOutput(output)) = actual {
+            strip_ansi_codes(output.as_str()).to_string()
+        } else {
+            panic!("Expected ToolOutput content")
+        }
+    }
+
+    #[test]
+    fn test_todo_write_mixed_changes_snapshot() {
+        let setup = (
+            vec![
+                fixture_todo("Task 1", "1", TodoStatus::Pending),
+                fixture_todo("Task 2", "2", TodoStatus::InProgress),
+            ],
+            vec![
+                fixture_todo("Task 1", "1", TodoStatus::Completed),
+                fixture_todo("Task 3", "3", TodoStatus::Pending),
+            ],
+        );
+
+        let actual = fixture_todo_write_output(setup.0, setup.1);
+        assert_snapshot!(actual);
+    }
+}