Merge branch 'main' into feat-telemetry-traces

docs/reference/tools.md

@@ -92,6 +92,21 @@ each tool.
 | [`ask_user`](../tools/ask-user.md) | `Communicate` | Requests clarification or missing information via an interactive dialog.               |
 | [`write_todos`](../tools/todos.md) | `Other`       | Maintains an internal list of subtasks. The model uses this to track its own progress. |
 
+### Task Tracker (Experimental)
+
+<!-- prettier-ignore -->
+> [!NOTE]
+> This is an experimental feature currently under active development. Enable via `experimental.taskTracker`.
+
+| Tool                                            | Kind    | Description                                                                 |
+| :---------------------------------------------- | :------ | :-------------------------------------------------------------------------- |
+| [`tracker_create_task`](../tools/tracker.md)    | `Other` | Creates a new task in the experimental tracker.                             |
+| [`tracker_update_task`](../tools/tracker.md)    | `Other` | Updates an existing task's status, description, or dependencies.            |
+| [`tracker_get_task`](../tools/tracker.md)       | `Other` | Retrieves the full details of a specific task.                              |
+| [`tracker_list_tasks`](../tools/tracker.md)     | `Other` | Lists tasks in the tracker, optionally filtered by status, type, or parent. |
+| [`tracker_add_dependency`](../tools/tracker.md) | `Other` | Adds a dependency between two tasks, ensuring topological execution.        |
+| [`tracker_visualize`](../tools/tracker.md)      | `Other` | Renders an ASCII tree visualization of the current task graph.              |
+
 ### MCP
 
 | Tool                                              | Kind     | Description                                                            |

docs/tools/tracker.md

@@ -0,0 +1,61 @@
+# Tracker tools (`tracker_*`)
+
+<!-- prettier-ignore -->
+> [!NOTE]
+> This is an experimental feature currently under active development.
+
+The `tracker_*` tools allow the Gemini agent to maintain an internal, persistent
+graph of tasks and dependencies for multi-step requests. This suite of tools
+provides a more robust and granular way to manage execution plans than the
+legacy `write_todos` tool.
+
+## Technical reference
+
+The agent uses these tools to manage its execution plan, decompose complex goals
+into actionable sub-tasks, and provide real-time progress updates to the CLI
+interface. The task state is stored in the `.gemini/tmp/tracker/<session-id>`
+directory, allowing the agent to manage its plan for the current session.
+
+### Available Tools
+
+- `tracker_create_task`: Creates a new task in the tracker. You can specify a
+  title, description, and task type (`epic`, `task`, `bug`).
+- `tracker_update_task`: Updates an existing task's status (`open`,
+  `in_progress`, `blocked`, `closed`), description, or dependencies.
+- `tracker_get_task`: Retrieves the full details of a specific task by its
+  6-character hex ID.
+- `tracker_list_tasks`: Lists tasks in the tracker, optionally filtered by
+  status, type, or parent ID.
+- `tracker_add_dependency`: Adds a dependency between two tasks, ensuring
+  topological execution.
+- `tracker_visualize`: Renders an ASCII tree visualization of the current task
+  graph.
+
+## Technical behavior
+
+- **Interface:** Updates the progress indicator and task tree above the CLI
+  input prompt.
+- **Persistence:** Task state is saved automatically to the
+  `.gemini/tmp/tracker/<session-id>` directory. Task states are session-specific
+  and do not persist across different sessions.
+- **Dependencies:** Tasks can depend on other tasks, forming a directed acyclic
+  graph (DAG). The agent must resolve dependencies before starting blocked
+  tasks.
+- **Interaction:** Users can view the current state of the tracker by asking the
+  agent to visualize it, or by running `gemini-cli` commands if implemented.
+
+## Use cases
+
+- Coordinating multi-file refactoring projects.
+- Breaking down a mission into a hierarchy of epics and tasks for better
+  visibility.
+- Tracking bugs and feature requests directly within the context of an active
+  codebase.
+- Providing visibility into the agent's current focus and remaining work.
+
+## Next steps
+
+- Follow the [Task planning tutorial](../cli/tutorials/task-planning.md) for
+  usage details and migration from the legacy todo list.
+- Learn about [Session management](../cli/session-management.md) for context on
+  persistent state.