add todo tool (#5182)

Co-authored-by: Matt Rubens <[email protected]>

Author: qdaxb

packages/types/src/global-settings.ts

@@ -47,6 +47,7 @@ export const globalSettingsSchema = z.object({
 	alwaysAllowExecute: z.boolean().optional(),
 	alwaysAllowFollowupQuestions: z.boolean().optional(),
 	followupAutoApproveTimeoutMs: z.number().optional(),
+	alwaysAllowUpdateTodoList: z.boolean().optional(),
 	allowedCommands: z.array(z.string()).optional(),
 	allowedMaxRequests: z.number().nullish(),
 	autoCondenseContext: z.boolean().optional(),
@@ -195,6 +196,7 @@ export const EVALS_SETTINGS: RooCodeSettings = {
 	alwaysAllowSubtasks: true,
 	alwaysAllowExecute: true,
 	alwaysAllowFollowupQuestions: true,
+	alwaysAllowUpdateTodoList: true,
 	followupAutoApproveTimeoutMs: 0,
 	allowedCommands: ["*"],
 

packages/types/src/index.ts

@@ -20,3 +20,4 @@ export * from "./terminal.js"
 export * from "./tool.js"
 export * from "./type-fu.js"
 export * from "./vscode.js"
+export * from "./todo.js"

packages/types/src/message.ts

@@ -106,6 +106,7 @@ export const clineSays = [
 	"condense_context",
 	"condense_context_error",
 	"codebase_search_result",
+	"user_edit_todos",
 ] as const
 
 export const clineSaySchema = z.enum(clineSays)

packages/types/src/todo.ts

@@ -0,0 +1,19 @@
+import { z } from "zod"
+
+/**
+ * TodoStatus
+ */
+export const todoStatusSchema = z.enum(["pending", "in_progress", "completed"] as const)
+
+export type TodoStatus = z.infer<typeof todoStatusSchema>
+
+/**
+ * TodoItem
+ */
+export const todoItemSchema = z.object({
+	id: z.string(),
+	content: z.string(),
+	status: todoStatusSchema,
+})
+
+export type TodoItem = z.infer<typeof todoItemSchema>

packages/types/src/tool.ts

@@ -33,6 +33,7 @@ export const toolNames = [
 	"new_task",
 	"fetch_instructions",
 	"codebase_search",
+	"update_todo_list",
 ] as const
 
 export const toolNamesSchema = z.enum(toolNames)

src/core/assistant-message/presentAssistantMessage.ts

@@ -26,6 +26,7 @@ import { attemptCompletionTool } from "../tools/attemptCompletionTool"
 import { newTaskTool } from "../tools/newTaskTool"
 
 import { checkpointSave } from "../checkpoints"
+import { updateTodoListTool } from "../tools/updateTodoListTool"
 
 import { formatResponse } from "../prompts/responses"
 import { validateToolUse } from "../tools/validateToolUse"
@@ -205,6 +206,8 @@ export async function presentAssistantMessage(cline: Task) {
 						return `[${block.name} to '${block.params.mode_slug}'${block.params.reason ? ` because: ${block.params.reason}` : ""}]`
 					case "codebase_search": // Add case for the new tool
 						return `[${block.name} for '${block.params.query}']`
+					case "update_todo_list":
+						return `[${block.name}]`
 					case "new_task": {
 						const mode = block.params.mode ?? defaultModeSlug
 						const message = block.params.message ?? "(no message)"
@@ -410,6 +413,9 @@ export async function presentAssistantMessage(cline: Task) {
 				case "write_to_file":
 					await writeToFileTool(cline, block, askApproval, handleError, pushToolResult, removeClosingTag)
 					break
+				case "update_todo_list":
+					await updateTodoListTool(cline, block, askApproval, handleError, pushToolResult, removeClosingTag)
+					break
 				case "apply_diff": {
 					// Get the provider and state to check experiment settings
 					const provider = cline.providerRef.deref()

src/core/environment/getEnvironmentDetails.ts

@@ -18,6 +18,7 @@ import { arePathsEqual } from "../../utils/path"
 import { formatResponse } from "../prompts/responses"
 
 import { Task } from "../task/Task"
+import { formatReminderSection } from "./reminder"
 
 export async function getEnvironmentDetails(cline: Task, includeFileDetails: boolean = false) {
 	let details = ""
@@ -273,5 +274,6 @@ export async function getEnvironmentDetails(cline: Task, includeFileDetails: boo
 		}
 	}
 
-	return `<environment_details>\n${details.trim()}\n</environment_details>`
+	const reminderSection = formatReminderSection(cline.todoList)
+	return `<environment_details>\n${details.trim()}\n${reminderSection}\n</environment_details>`
 }

src/core/environment/reminder.ts

@@ -0,0 +1,38 @@
+import { TodoItem, TodoStatus } from "@roo-code/types"
+
+/**
+ * Format the reminders section as a markdown block in English, with basic instructions.
+ */
+export function formatReminderSection(todoList?: TodoItem[]): string {
+	if (!todoList || todoList.length === 0) {
+		return ""
+	}
+	const statusMap: Record<TodoStatus, string> = {
+		pending: "Pending",
+		in_progress: "In Progress",
+		completed: "Completed",
+	}
+	const lines: string[] = [
+		"====",
+		"",
+		"REMINDERS",
+		"",
+		"Below is your current list of reminders for this task. Keep them updated as you progress.",
+		"",
+	]
+
+	lines.push("| # | Content | Status |")
+	lines.push("|---|---------|--------|")
+	todoList.forEach((item, idx) => {
+		const escapedContent = item.content.replace(/\\/g, "\\\\").replace(/\|/g, "\\|")
+		lines.push(`| ${idx + 1} | ${escapedContent} | ${statusMap[item.status] || item.status} |`)
+	})
+	lines.push("")
+
+	lines.push(
+		"",
+		"IMPORTANT: When task status changes, remember to call the `update_todo_list` tool to update your progress.",
+		"",
+	)
+	return lines.join("\n")
+}

src/core/prompts/__tests__/__snapshots__/add-custom-instructions/architect-mode-prompt.snap

@@ -368,6 +368,76 @@ Example:
 </new_task>
 
 
+## update_todo_list
+
+**Description:**
+Replace the entire TODO list with an updated checklist reflecting the current state. Always provide the full list; the system will overwrite the previous one. This tool is designed for step-by-step task tracking, allowing you to confirm completion of each step before updating, update multiple task statuses at once (e.g., mark one as completed and start the next), and dynamically add new todos discovered during long or complex tasks.
+
+**Checklist Format:**
+- Use a single-level markdown checklist (no nesting or subtasks).
+- List todos in the intended execution order.
+- Status options:
+	 - [ ] Task description (pending)
+	 - [x] Task description (completed)
+	 - [-] Task description (in progress)
+
+**Status Rules:**
+- [ ] = pending (not started)
+- [x] = completed (fully finished, no unresolved issues)
+- [-] = in_progress (currently being worked on)
+
+**Core Principles:**
+- Before updating, always confirm which todos have been completed since the last update.
+- You may update multiple statuses in a single update (e.g., mark the previous as completed and the next as in progress).
+- When a new actionable item is discovered during a long or complex task, add it to the todo list immediately.
+- Do not remove any unfinished todos unless explicitly instructed.
+- Always retain all unfinished tasks, updating their status as needed.
+- Only mark a task as completed when it is fully accomplished (no partials, no unresolved dependencies).
+- If a task is blocked, keep it as in_progress and add a new todo describing what needs to be resolved.
+- Remove tasks only if they are no longer relevant or if the user requests deletion.
+
+**Usage Example:**
+<update_todo_list>
+<todos>
+[x] Analyze requirements
+[x] Design architecture
+[-] Implement core logic
+[ ] Write tests
+[ ] Update documentation
+</todos>
+</update_todo_list>
+
+*After completing "Implement core logic" and starting "Write tests":*
+<update_todo_list>
+<todos>
+[x] Analyze requirements
+[x] Design architecture
+[x] Implement core logic
+[-] Write tests
+[ ] Update documentation
+[ ] Add performance benchmarks
+</todos>
+</update_todo_list>
+
+**When to Use:**
+- The task involves multiple steps or requires ongoing tracking.
+- You need to update the status of several todos at once.
+- New actionable items are discovered during task execution.
+- The user requests a todo list or provides multiple tasks.
+- The task is complex and benefits from clear, stepwise progress tracking.
+
+**When NOT to Use:**
+- There is only a single, trivial task.
+- The task can be completed in one or two simple steps.
+- The request is purely conversational or informational.
+
+**Task Management Guidelines:**
+- Mark task as completed immediately after all work of the current task is done.
+- Start the next task by marking it as in_progress.
+- Add new todos as soon as they are identified.
+- Use clear, descriptive task names.
+
+
 # Tool Use Guidelines
 
 1. In <thinking> tags, assess what information you already have and what information you need to proceed with the task.

src/core/prompts/__tests__/__snapshots__/add-custom-instructions/ask-mode-prompt.snap

@@ -265,6 +265,76 @@ Example:
 </new_task>
 
 
+## update_todo_list
+
+**Description:**
+Replace the entire TODO list with an updated checklist reflecting the current state. Always provide the full list; the system will overwrite the previous one. This tool is designed for step-by-step task tracking, allowing you to confirm completion of each step before updating, update multiple task statuses at once (e.g., mark one as completed and start the next), and dynamically add new todos discovered during long or complex tasks.
+
+**Checklist Format:**
+- Use a single-level markdown checklist (no nesting or subtasks).
+- List todos in the intended execution order.
+- Status options:
+	 - [ ] Task description (pending)
+	 - [x] Task description (completed)
+	 - [-] Task description (in progress)
+
+**Status Rules:**
+- [ ] = pending (not started)
+- [x] = completed (fully finished, no unresolved issues)
+- [-] = in_progress (currently being worked on)
+
+**Core Principles:**
+- Before updating, always confirm which todos have been completed since the last update.
+- You may update multiple statuses in a single update (e.g., mark the previous as completed and the next as in progress).
+- When a new actionable item is discovered during a long or complex task, add it to the todo list immediately.
+- Do not remove any unfinished todos unless explicitly instructed.
+- Always retain all unfinished tasks, updating their status as needed.
+- Only mark a task as completed when it is fully accomplished (no partials, no unresolved dependencies).
+- If a task is blocked, keep it as in_progress and add a new todo describing what needs to be resolved.
+- Remove tasks only if they are no longer relevant or if the user requests deletion.
+
+**Usage Example:**
+<update_todo_list>
+<todos>
+[x] Analyze requirements
+[x] Design architecture
+[-] Implement core logic
+[ ] Write tests
+[ ] Update documentation
+</todos>
+</update_todo_list>
+
+*After completing "Implement core logic" and starting "Write tests":*
+<update_todo_list>
+<todos>
+[x] Analyze requirements
+[x] Design architecture
+[x] Implement core logic
+[-] Write tests
+[ ] Update documentation
+[ ] Add performance benchmarks
+</todos>
+</update_todo_list>
+
+**When to Use:**
+- The task involves multiple steps or requires ongoing tracking.
+- You need to update the status of several todos at once.
+- New actionable items are discovered during task execution.
+- The user requests a todo list or provides multiple tasks.
+- The task is complex and benefits from clear, stepwise progress tracking.
+
+**When NOT to Use:**
+- There is only a single, trivial task.
+- The task can be completed in one or two simple steps.
+- The request is purely conversational or informational.
+
+**Task Management Guidelines:**
+- Mark task as completed immediately after all work of the current task is done.
+- Start the next task by marking it as in_progress.
+- Add new todos as soon as they are identified.
+- Use clear, descriptive task names.
+
+
 # Tool Use Guidelines
 
 1. In <thinking> tags, assess what information you already have and what information you need to proceed with the task.