feat(core): make todo_write opt-in

docs/design/todo-write-opt-in.md

@@ -0,0 +1,75 @@
+# Make `todo_write` opt-in
+
+## Summary
+
+Disable the built-in `todo_write` tool by default in every interaction mode and
+allow users to restore it with `tools.todoWrite.enabled`. The default system
+prompt and Agent tool description must not advertise Todo-only behavior when
+the tool is unavailable.
+
+## Motivation
+
+`todo_write` rewrites a session checklist in a separate model turn. In
+headless mode that bookkeeping is not rendered as a dedicated progress view:
+text output hides the call, while JSON formats expose it only as a generic tool
+event. The extra tool round therefore adds latency and tokens without providing
+the interactive progress experience that originally justified the tool.
+
+Newer models can maintain and revise a working approach without a mandatory
+checklist. Qwen Code also has shared task tools for the separate agent-team use
+case. Removing Todo from the default tool surface avoids steering ordinary
+sessions toward bookkeeping while preserving it for users and integrations
+that deliberately depend on it.
+
+## Design
+
+Add `tools.todoWrite.enabled`, a restart-required boolean setting whose default
+is `false`. The CLI passes the resolved value into `Config`; SDK callers can use
+the corresponding configuration parameter. Only this flag enables the tool.
+Tool allowlists, eager-tool selection, and permission rules continue to control
+registered tools but do not opt a disabled tool into existence.
+
+When disabled:
+
+- the tool registry does not register `todo_write`, eagerly or as a deferred
+  tool;
+- an attempted call returns an actionable error naming the opt-in setting;
+- the default system prompt omits the Todo task-management section and all
+  `todo_write` guidance while retaining adaptive planning guidance;
+- the Agent tool omits `todo_id` from its model-facing schema and usage notes;
+- the bundled new-application workflow does not require an unavailable tool.
+
+When enabled, the existing Todo implementation remains unchanged. Persistence,
+hooks, active-Todo reminders, ACP rendering, and the daemon Todo Stop Guard
+remain downstream consumers of successful Todo calls. The Stop Guard is
+therefore effective only when both it and `tools.todoWrite.enabled` are on.
+
+Custom system prompts remain user-owned and are not rewritten. Existing
+sessions may still contain historical Todo calls, but disabling the tool only
+changes future tool declarations and guidance; history loading and rendering
+continue to accept those records.
+
+## Compatibility and rollout
+
+This intentionally changes the default tool surface. Users who rely on Todo
+must add:
+
+```json
+{
+  "tools": {
+    "todoWrite": {
+      "enabled": true
+    }
+  }
+}
+```
+
+No Todo data is deleted. Removing the setting restores the new default.
+
+## Verification
+
+Unit tests cover CLI setting propagation, registry behavior with the flag off
+and on, prompt guidance with the flag off and on, Agent schema guidance, and
+eager/deferred registration. Headless integration coverage verifies that the
+default tool declaration excludes `todo_write` and that explicitly enabling
+the setting restores a successful call.

docs/developers/tools/introduction.md

@@ -47,7 +47,7 @@ Qwen Code's built-in tools can be broadly categorized as follows:
 - **[Shell Tool](./shell.md) (`run_shell_command`):** For executing shell commands.
 - **[Monitor Tool](./monitor.md) (`monitor`):** For running long-lived shell commands that stream output back as background task notifications.
 - **[Web Fetch Tool](./web-fetch.md) (`web_fetch`):** For retrieving content from URLs.
-- **[Todo Write Tool](./todo-write.md) (`todo_write`):** For creating and managing structured task lists during coding sessions.
+- **[Todo Write Tool](./todo-write.md) (`todo_write`):** An opt-in tool for creating and managing structured task lists during coding sessions.
 - **[Agent Tool](./task.md) (`agent`):** For delegating complex tasks to specialized subagents.
 - **[Exit Plan Mode Tool](./exit-plan-mode.md) (`exit_plan_mode`):** For exiting plan mode and proceeding with implementation.
 

docs/developers/tools/todo-write.md

@@ -6,6 +6,19 @@ This document describes the `todo_write` tool for Qwen Code.
 
 Use `todo_write` to create and manage a structured task list for your current coding session. This tool helps the AI assistant track progress and organize complex tasks, providing you with visibility into what work is being performed.
 
+The tool is disabled by default. Enable it in `settings.json` and restart Qwen
+Code:
+
+```json
+{
+  "tools": {
+    "todoWrite": {
+      "enabled": true
+    }
+  }
+}
+```
+
 ### Arguments
 
 `todo_write` takes one argument:
@@ -17,7 +30,7 @@ Use `todo_write` to create and manage a structured task list for your current co
 
 ## How to use `todo_write` with Qwen Code
 
-The AI assistant will automatically use this tool when working on complex, multi-step tasks. You don't need to explicitly request it, but you can ask the assistant to create a todo list if you want to see the planned approach for your request.
+When the tool is enabled, the AI assistant may use it for complex, multi-step tasks. You can also ask the assistant to create a todo list if you want to see the planned approach for your request.
 
 The tool stores todo lists in your home directory (`~/.qwen/todos/`) with session-specific files, so each coding session maintains its own task list.
 
@@ -58,6 +71,7 @@ todo_write(todos=[
 
 ## Important notes
 
-- **Automatic usage:** The AI assistant manages todo lists automatically during complex tasks.
+- **Opt-in:** Set `tools.todoWrite.enabled` to `true` and restart Qwen Code before using the tool.
+- **Automatic usage when enabled:** The AI assistant manages todo lists during complex tasks.
 - **Progress visibility:** You'll see todo lists updated in real-time as work progresses.
 - **Session isolation:** Each coding session has its own todo list that doesn't interfere with others.