(feat): Add a ToDo tool to track ongoing task lists

packages/cli/src/config/config.ts

@@ -82,6 +82,7 @@ export interface CliArgs {
   includeDirectories: string[] | undefined;
   screenReader: boolean | undefined;
   useSmartEdit: boolean | undefined;
+  useWriteTodos: boolean | undefined;
   promptWords: string[] | undefined;
   outputFormat: string | undefined;
 }
@@ -647,6 +648,7 @@ export async function loadCliConfig(
     enableToolOutputTruncation: settings.tools?.enableToolOutputTruncation,
     eventEmitter: appEvents,
     useSmartEdit: argv.useSmartEdit ?? settings.useSmartEdit,
+    useWriteTodos: argv.useWriteTodos ?? settings.useWriteTodos,
     output: {
       format: (argv.outputFormat ?? settings.output?.format) as OutputFormat,
     },

packages/cli/src/config/settingsSchema.ts

@@ -824,6 +824,15 @@ const SETTINGS_SCHEMA = {
     description: 'Enable the smart-edit tool instead of the replace tool.',
     showInDialog: false,
   },
+  useWriteTodos: {
+    type: 'boolean',
+    label: 'Use Write Todos',
+    category: 'Advanced',
+    requiresRestart: false,
+    default: false,
+    description: 'Enable the write_todos_list tool.',
+    showInDialog: false,
+  },
   security: {
     type: 'object',
     label: 'Security',

packages/cli/src/gemini.test.tsx

@@ -257,6 +257,7 @@ describe('gemini.tsx main function kitty protocol', () => {
       includeDirectories: undefined,
       screenReader: undefined,
       useSmartEdit: undefined,
+      useWriteTodos: undefined,
       promptWords: undefined,
       outputFormat: undefined,
     });

packages/core/src/config/config.ts

@@ -50,6 +50,7 @@ import {
 import { shouldAttemptBrowserLaunch } from '../utils/browser.js';
 import type { MCPOAuthConfig } from '../mcp/oauth-provider.js';
 import { ideContextStore } from '../ide/ideContext.js';
+import { WriteTodosTool } from '../tools/write-todos.js';
 import type { FileSystemService } from '../services/fileSystemService.js';
 import { StandardFileSystemService } from '../services/fileSystemService.js';
 import {
@@ -245,6 +246,7 @@ export interface ConfigParameters {
   enableToolOutputTruncation?: boolean;
   eventEmitter?: EventEmitter;
   useSmartEdit?: boolean;
+  useWriteTodos?: boolean;
   policyEngineConfig?: PolicyEngineConfig;
   output?: OutputSettings;
   useModelRouter?: boolean;
@@ -332,6 +334,7 @@ export class Config {
   private readonly fileExclusions: FileExclusions;
   private readonly eventEmitter?: EventEmitter;
   private readonly useSmartEdit: boolean;
+  private readonly useWriteTodos: boolean;
   private readonly messageBus: MessageBus;
   private readonly policyEngine: PolicyEngine;
   private readonly outputSettings: OutputSettings;
@@ -421,6 +424,7 @@ export class Config {
     this.enableToolOutputTruncation =
       params.enableToolOutputTruncation ?? false;
     this.useSmartEdit = params.useSmartEdit ?? true;
+    this.useWriteTodos = params.useWriteTodos ?? false;
     this.useModelRouter = params.useModelRouter ?? false;
     this.extensionManagement = params.extensionManagement ?? true;
     this.storage = new Storage(this.targetDir);
@@ -947,6 +951,10 @@ export class Config {
     return this.useSmartEdit;
   }
 
+  getUseWriteTodos(): boolean {
+    return this.useWriteTodos;
+  }
+
   getOutputFormat(): OutputFormat {
     return this.outputSettings?.format
       ? this.outputSettings.format
@@ -1047,6 +1055,9 @@ export class Config {
     registerCoreTool(ShellTool, this);
     registerCoreTool(MemoryTool);
     registerCoreTool(WebSearchTool, this);
+    if (this.getUseWriteTodos()) {
+      registerCoreTool(WriteTodosTool, this);
+    }
 
     await registry.discoverAllTools();
     return registry;

packages/core/src/index.ts

@@ -96,6 +96,7 @@ export * from './tools/web-search.js';
 export * from './tools/read-many-files.js';
 export * from './tools/mcp-client.js';
 export * from './tools/mcp-tool.js';
+export * from './tools/write-todos.js';
 
 // MCP OAuth
 export { MCPOAuthProvider } from './mcp/oauth-provider.js';

packages/core/src/tools/write-todos.test.ts

@@ -0,0 +1,109 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, it } from 'vitest';
+import { WriteTodosTool, type WriteTodosToolParams } from './write-todos.js';
+
+describe('WriteTodosTool', () => {
+  const tool = new WriteTodosTool();
+  const signal = new AbortController().signal;
+
+  describe('validation', () => {
+    it('should not throw for valid parameters', async () => {
+      const params: WriteTodosToolParams = {
+        todos: [
+          { description: 'Task 1', status: 'pending' },
+          { description: 'Task 2', status: 'in_progress' },
+          { description: 'Task 3', status: 'completed' },
+        ],
+      };
+      await expect(tool.buildAndExecute(params, signal)).resolves.toBeDefined();
+    });
+
+    it('should not throw for an empty list', async () => {
+      const params: WriteTodosToolParams = {
+        todos: [],
+      };
+      await expect(tool.buildAndExecute(params, signal)).resolves.toBeDefined();
+    });
+
+    it('should throw an error if todos is not an array', async () => {
+      const params = {
+        todos: 'not-an-array',
+      } as unknown as WriteTodosToolParams;
+      await expect(tool.buildAndExecute(params, signal)).rejects.toThrow(
+        'params/todos must be array',
+      );
+    });
+
+    it('should throw an error if a todo item is not an object', async () => {
+      const params = {
+        todos: ['not-an-object'],
+      } as unknown as WriteTodosToolParams;
+      await expect(tool.buildAndExecute(params, signal)).rejects.toThrow(
+        'params/todos/0 must be object',
+      );
+    });
+
+    it('should throw an error if a todo description is missing or empty', async () => {
+      const params: WriteTodosToolParams = {
+        todos: [{ description: '  ', status: 'pending' }],
+      };
+      await expect(tool.buildAndExecute(params, signal)).rejects.toThrow(
+        'Each todo must have a non-empty description string',
+      );
+    });
+
+    it('should throw an error if a todo status is invalid', async () => {
+      const params = {
+        todos: [{ description: 'Task 1', status: 'invalid-status' }],
+      } as unknown as WriteTodosToolParams;
+      await expect(tool.buildAndExecute(params, signal)).rejects.toThrow(
+        'params/todos/0/status must be equal to one of the allowed values',
+      );
+    });
+
+    it('should throw an error if more than one task is in_progress', async () => {
+      const params: WriteTodosToolParams = {
+        todos: [
+          { description: 'Task 1', status: 'in_progress' },
+          { description: 'Task 2', status: 'in_progress' },
+        ],
+      };
+      await expect(tool.buildAndExecute(params, signal)).rejects.toThrow(
+        'Invalid parameters: Only one task can be "in_progress" at a time.',
+      );
+    });
+  });
+
+  describe('execute', () => {
+    it('should return a success message for clearing the list', async () => {
+      const params: WriteTodosToolParams = {
+        todos: [],
+      };
+      const result = await tool.buildAndExecute(params, signal);
+      expect(result.llmContent).toBe('Successfully cleared the todo list.');
+      expect(result.returnDisplay).toBe('Successfully cleared the todo list.');
+    });
+
+    it('should return a formatted todo list on success', async () => {
+      const params: WriteTodosToolParams = {
+        todos: [
+          { description: 'First task', status: 'completed' },
+          { description: 'Second task', status: 'in_progress' },
+          { description: 'Third task', status: 'pending' },
+        ],
+      };
+      const result = await tool.buildAndExecute(params, signal);
+      const expectedOutput = `Successfully updated the todo list. The current list is now:
+1. [completed] First task
+2. [in_progress] Second task
+3. [pending] Third task`;
+      expect(result.llmContent).toBe(expectedOutput);
+      expect(result.returnDisplay).toBe(expectedOutput);
+    });
+  });
+});