fix(core): require opt-in for plan mode prompt (#5433)

docs/users/features/approval-mode.md

@@ -52,6 +52,8 @@ If you are in Normal Mode, **Shift+Tab** (or **Tab** on Windows) first switches
 
 The `/plan` command provides a quick shortcut for entering and exiting Plan Mode:
 
+Regular planning requests do not switch modes by themselves. If you want the read-only Plan Mode workflow, use `/plan`, the keyboard shortcut, or set the approval mode to `plan` explicitly.
+
 ```bash
 /plan                          # Enter plan mode
 /plan refactor the auth module # Enter plan mode and start planning

packages/core/src/core/__snapshots__/prompts.test.ts.snap

@@ -14,7 +14,7 @@ exports[`Core System Prompt (prompts.ts) > should append userMemory with separat
 - **Confirm Ambiguity/Expansion:** Do not take significant actions beyond the clear scope of the request without confirming with the user. If asked *how* to do something, explain first, don't just do it.
 - **Do Not revert changes:** Do not revert changes to the codebase unless asked to do so by the user. Only revert changes made by you if they have resulted in an error or if the user has explicitly asked you to revert the changes.
 - **Denied Tool Calls:** If a tool call is denied, do not try to complete the denied action through another tool, shell indirection, generated script, alias, symlink, config change, hook, command file, MCP configuration, encoded payload, or equivalent path. If that action is required, stop and ask the user for explicit approval. You may continue with unrelated safe work or a genuinely safer alternative that does not accomplish the denied action.
-- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation or ask clarifying questions. When the work requires a shared plan before execution, enter plan mode (via enter_plan_mode if available, or the user's plan mode toggle) unless the user explicitly asked not to use plan mode.
+- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation, make a plan in the current mode, or ask clarifying questions. Do not enter plan mode or call enter_plan_mode on your own just because the task involves planning or complexity. Use plan mode only when the user explicitly asks you to switch to plan mode, has already enabled it, or confirms they want it.
 
 
 # Task Management
@@ -245,7 +245,7 @@ exports[`Core System Prompt (prompts.ts) > should include git instructions when
 - **Confirm Ambiguity/Expansion:** Do not take significant actions beyond the clear scope of the request without confirming with the user. If asked *how* to do something, explain first, don't just do it.
 - **Do Not revert changes:** Do not revert changes to the codebase unless asked to do so by the user. Only revert changes made by you if they have resulted in an error or if the user has explicitly asked you to revert the changes.
 - **Denied Tool Calls:** If a tool call is denied, do not try to complete the denied action through another tool, shell indirection, generated script, alias, symlink, config change, hook, command file, MCP configuration, encoded payload, or equivalent path. If that action is required, stop and ask the user for explicit approval. You may continue with unrelated safe work or a genuinely safer alternative that does not accomplish the denied action.
-- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation or ask clarifying questions. When the work requires a shared plan before execution, enter plan mode (via enter_plan_mode if available, or the user's plan mode toggle) unless the user explicitly asked not to use plan mode.
+- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation, make a plan in the current mode, or ask clarifying questions. Do not enter plan mode or call enter_plan_mode on your own just because the task involves planning or complexity. Use plan mode only when the user explicitly asks you to switch to plan mode, has already enabled it, or confirms they want it.
 
 
 # Task Management
@@ -491,7 +491,7 @@ exports[`Core System Prompt (prompts.ts) > should include non-sandbox instructio
 - **Confirm Ambiguity/Expansion:** Do not take significant actions beyond the clear scope of the request without confirming with the user. If asked *how* to do something, explain first, don't just do it.
 - **Do Not revert changes:** Do not revert changes to the codebase unless asked to do so by the user. Only revert changes made by you if they have resulted in an error or if the user has explicitly asked you to revert the changes.
 - **Denied Tool Calls:** If a tool call is denied, do not try to complete the denied action through another tool, shell indirection, generated script, alias, symlink, config change, hook, command file, MCP configuration, encoded payload, or equivalent path. If that action is required, stop and ask the user for explicit approval. You may continue with unrelated safe work or a genuinely safer alternative that does not accomplish the denied action.
-- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation or ask clarifying questions. When the work requires a shared plan before execution, enter plan mode (via enter_plan_mode if available, or the user's plan mode toggle) unless the user explicitly asked not to use plan mode.
+- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation, make a plan in the current mode, or ask clarifying questions. Do not enter plan mode or call enter_plan_mode on your own just because the task involves planning or complexity. Use plan mode only when the user explicitly asks you to switch to plan mode, has already enabled it, or confirms they want it.
 
 
 # Task Management
@@ -717,7 +717,7 @@ exports[`Core System Prompt (prompts.ts) > should include sandbox-specific instr
 - **Confirm Ambiguity/Expansion:** Do not take significant actions beyond the clear scope of the request without confirming with the user. If asked *how* to do something, explain first, don't just do it.
 - **Do Not revert changes:** Do not revert changes to the codebase unless asked to do so by the user. Only revert changes made by you if they have resulted in an error or if the user has explicitly asked you to revert the changes.
 - **Denied Tool Calls:** If a tool call is denied, do not try to complete the denied action through another tool, shell indirection, generated script, alias, symlink, config change, hook, command file, MCP configuration, encoded payload, or equivalent path. If that action is required, stop and ask the user for explicit approval. You may continue with unrelated safe work or a genuinely safer alternative that does not accomplish the denied action.
-- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation or ask clarifying questions. When the work requires a shared plan before execution, enter plan mode (via enter_plan_mode if available, or the user's plan mode toggle) unless the user explicitly asked not to use plan mode.
+- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation, make a plan in the current mode, or ask clarifying questions. Do not enter plan mode or call enter_plan_mode on your own just because the task involves planning or complexity. Use plan mode only when the user explicitly asks you to switch to plan mode, has already enabled it, or confirms they want it.
 
 
 # Task Management
@@ -943,7 +943,7 @@ exports[`Core System Prompt (prompts.ts) > should include seatbelt-specific inst
 - **Confirm Ambiguity/Expansion:** Do not take significant actions beyond the clear scope of the request without confirming with the user. If asked *how* to do something, explain first, don't just do it.
 - **Do Not revert changes:** Do not revert changes to the codebase unless asked to do so by the user. Only revert changes made by you if they have resulted in an error or if the user has explicitly asked you to revert the changes.
 - **Denied Tool Calls:** If a tool call is denied, do not try to complete the denied action through another tool, shell indirection, generated script, alias, symlink, config change, hook, command file, MCP configuration, encoded payload, or equivalent path. If that action is required, stop and ask the user for explicit approval. You may continue with unrelated safe work or a genuinely safer alternative that does not accomplish the denied action.
-- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation or ask clarifying questions. When the work requires a shared plan before execution, enter plan mode (via enter_plan_mode if available, or the user's plan mode toggle) unless the user explicitly asked not to use plan mode.
+- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation, make a plan in the current mode, or ask clarifying questions. Do not enter plan mode or call enter_plan_mode on your own just because the task involves planning or complexity. Use plan mode only when the user explicitly asks you to switch to plan mode, has already enabled it, or confirms they want it.
 
 
 # Task Management
@@ -1169,7 +1169,7 @@ exports[`Core System Prompt (prompts.ts) > should not include git instructions w
 - **Confirm Ambiguity/Expansion:** Do not take significant actions beyond the clear scope of the request without confirming with the user. If asked *how* to do something, explain first, don't just do it.
 - **Do Not revert changes:** Do not revert changes to the codebase unless asked to do so by the user. Only revert changes made by you if they have resulted in an error or if the user has explicitly asked you to revert the changes.
 - **Denied Tool Calls:** If a tool call is denied, do not try to complete the denied action through another tool, shell indirection, generated script, alias, symlink, config change, hook, command file, MCP configuration, encoded payload, or equivalent path. If that action is required, stop and ask the user for explicit approval. You may continue with unrelated safe work or a genuinely safer alternative that does not accomplish the denied action.
-- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation or ask clarifying questions. When the work requires a shared plan before execution, enter plan mode (via enter_plan_mode if available, or the user's plan mode toggle) unless the user explicitly asked not to use plan mode.
+- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation, make a plan in the current mode, or ask clarifying questions. Do not enter plan mode or call enter_plan_mode on your own just because the task involves planning or complexity. Use plan mode only when the user explicitly asks you to switch to plan mode, has already enabled it, or confirms they want it.
 
 
 # Task Management
@@ -1395,7 +1395,7 @@ exports[`Core System Prompt (prompts.ts) > should return the base prompt when no
 - **Confirm Ambiguity/Expansion:** Do not take significant actions beyond the clear scope of the request without confirming with the user. If asked *how* to do something, explain first, don't just do it.
 - **Do Not revert changes:** Do not revert changes to the codebase unless asked to do so by the user. Only revert changes made by you if they have resulted in an error or if the user has explicitly asked you to revert the changes.
 - **Denied Tool Calls:** If a tool call is denied, do not try to complete the denied action through another tool, shell indirection, generated script, alias, symlink, config change, hook, command file, MCP configuration, encoded payload, or equivalent path. If that action is required, stop and ask the user for explicit approval. You may continue with unrelated safe work or a genuinely safer alternative that does not accomplish the denied action.
-- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation or ask clarifying questions. When the work requires a shared plan before execution, enter plan mode (via enter_plan_mode if available, or the user's plan mode toggle) unless the user explicitly asked not to use plan mode.
+- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation, make a plan in the current mode, or ask clarifying questions. Do not enter plan mode or call enter_plan_mode on your own just because the task involves planning or complexity. Use plan mode only when the user explicitly asks you to switch to plan mode, has already enabled it, or confirms they want it.
 
 
 # Task Management
@@ -1621,7 +1621,7 @@ exports[`Core System Prompt (prompts.ts) > should return the base prompt when us
 - **Confirm Ambiguity/Expansion:** Do not take significant actions beyond the clear scope of the request without confirming with the user. If asked *how* to do something, explain first, don't just do it.
 - **Do Not revert changes:** Do not revert changes to the codebase unless asked to do so by the user. Only revert changes made by you if they have resulted in an error or if the user has explicitly asked you to revert the changes.
 - **Denied Tool Calls:** If a tool call is denied, do not try to complete the denied action through another tool, shell indirection, generated script, alias, symlink, config change, hook, command file, MCP configuration, encoded payload, or equivalent path. If that action is required, stop and ask the user for explicit approval. You may continue with unrelated safe work or a genuinely safer alternative that does not accomplish the denied action.
-- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation or ask clarifying questions. When the work requires a shared plan before execution, enter plan mode (via enter_plan_mode if available, or the user's plan mode toggle) unless the user explicitly asked not to use plan mode.
+- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation, make a plan in the current mode, or ask clarifying questions. Do not enter plan mode or call enter_plan_mode on your own just because the task involves planning or complexity. Use plan mode only when the user explicitly asks you to switch to plan mode, has already enabled it, or confirms they want it.
 
 
 # Task Management
@@ -1847,7 +1847,7 @@ exports[`Core System Prompt (prompts.ts) > should return the base prompt when us
 - **Confirm Ambiguity/Expansion:** Do not take significant actions beyond the clear scope of the request without confirming with the user. If asked *how* to do something, explain first, don't just do it.
 - **Do Not revert changes:** Do not revert changes to the codebase unless asked to do so by the user. Only revert changes made by you if they have resulted in an error or if the user has explicitly asked you to revert the changes.
 - **Denied Tool Calls:** If a tool call is denied, do not try to complete the denied action through another tool, shell indirection, generated script, alias, symlink, config change, hook, command file, MCP configuration, encoded payload, or equivalent path. If that action is required, stop and ask the user for explicit approval. You may continue with unrelated safe work or a genuinely safer alternative that does not accomplish the denied action.
-- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation or ask clarifying questions. When the work requires a shared plan before execution, enter plan mode (via enter_plan_mode if available, or the user's plan mode toggle) unless the user explicitly asked not to use plan mode.
+- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation, make a plan in the current mode, or ask clarifying questions. Do not enter plan mode or call enter_plan_mode on your own just because the task involves planning or complexity. Use plan mode only when the user explicitly asks you to switch to plan mode, has already enabled it, or confirms they want it.
 
 
 # Task Management
@@ -2073,7 +2073,7 @@ exports[`Model-specific tool call formats > should preserve model-specific forma
 - **Confirm Ambiguity/Expansion:** Do not take significant actions beyond the clear scope of the request without confirming with the user. If asked *how* to do something, explain first, don't just do it.
 - **Do Not revert changes:** Do not revert changes to the codebase unless asked to do so by the user. Only revert changes made by you if they have resulted in an error or if the user has explicitly asked you to revert the changes.
 - **Denied Tool Calls:** If a tool call is denied, do not try to complete the denied action through another tool, shell indirection, generated script, alias, symlink, config change, hook, command file, MCP configuration, encoded payload, or equivalent path. If that action is required, stop and ask the user for explicit approval. You may continue with unrelated safe work or a genuinely safer alternative that does not accomplish the denied action.
-- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation or ask clarifying questions. When the work requires a shared plan before execution, enter plan mode (via enter_plan_mode if available, or the user's plan mode toggle) unless the user explicitly asked not to use plan mode.
+- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation, make a plan in the current mode, or ask clarifying questions. Do not enter plan mode or call enter_plan_mode on your own just because the task involves planning or complexity. Use plan mode only when the user explicitly asks you to switch to plan mode, has already enabled it, or confirms they want it.
 
 
 # Task Management
@@ -2322,7 +2322,7 @@ exports[`Model-specific tool call formats > should preserve model-specific forma
 - **Confirm Ambiguity/Expansion:** Do not take significant actions beyond the clear scope of the request without confirming with the user. If asked *how* to do something, explain first, don't just do it.
 - **Do Not revert changes:** Do not revert changes to the codebase unless asked to do so by the user. Only revert changes made by you if they have resulted in an error or if the user has explicitly asked you to revert the changes.
 - **Denied Tool Calls:** If a tool call is denied, do not try to complete the denied action through another tool, shell indirection, generated script, alias, symlink, config change, hook, command file, MCP configuration, encoded payload, or equivalent path. If that action is required, stop and ask the user for explicit approval. You may continue with unrelated safe work or a genuinely safer alternative that does not accomplish the denied action.
-- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation or ask clarifying questions. When the work requires a shared plan before execution, enter plan mode (via enter_plan_mode if available, or the user's plan mode toggle) unless the user explicitly asked not to use plan mode.
+- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation, make a plan in the current mode, or ask clarifying questions. Do not enter plan mode or call enter_plan_mode on your own just because the task involves planning or complexity. Use plan mode only when the user explicitly asks you to switch to plan mode, has already enabled it, or confirms they want it.
 
 
 # Task Management
@@ -2634,7 +2634,7 @@ exports[`Model-specific tool call formats > should use JSON format for qwen-vl m
 - **Confirm Ambiguity/Expansion:** Do not take significant actions beyond the clear scope of the request without confirming with the user. If asked *how* to do something, explain first, don't just do it.
 - **Do Not revert changes:** Do not revert changes to the codebase unless asked to do so by the user. Only revert changes made by you if they have resulted in an error or if the user has explicitly asked you to revert the changes.
 - **Denied Tool Calls:** If a tool call is denied, do not try to complete the denied action through another tool, shell indirection, generated script, alias, symlink, config change, hook, command file, MCP configuration, encoded payload, or equivalent path. If that action is required, stop and ask the user for explicit approval. You may continue with unrelated safe work or a genuinely safer alternative that does not accomplish the denied action.
-- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation or ask clarifying questions. When the work requires a shared plan before execution, enter plan mode (via enter_plan_mode if available, or the user's plan mode toggle) unless the user explicitly asked not to use plan mode.
+- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation, make a plan in the current mode, or ask clarifying questions. Do not enter plan mode or call enter_plan_mode on your own just because the task involves planning or complexity. Use plan mode only when the user explicitly asks you to switch to plan mode, has already enabled it, or confirms they want it.
 
 
 # Task Management
@@ -2883,7 +2883,7 @@ exports[`Model-specific tool call formats > should use XML format for qwen3-code
 - **Confirm Ambiguity/Expansion:** Do not take significant actions beyond the clear scope of the request without confirming with the user. If asked *how* to do something, explain first, don't just do it.
 - **Do Not revert changes:** Do not revert changes to the codebase unless asked to do so by the user. Only revert changes made by you if they have resulted in an error or if the user has explicitly asked you to revert the changes.
 - **Denied Tool Calls:** If a tool call is denied, do not try to complete the denied action through another tool, shell indirection, generated script, alias, symlink, config change, hook, command file, MCP configuration, encoded payload, or equivalent path. If that action is required, stop and ask the user for explicit approval. You may continue with unrelated safe work or a genuinely safer alternative that does not accomplish the denied action.
-- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation or ask clarifying questions. When the work requires a shared plan before execution, enter plan mode (via enter_plan_mode if available, or the user's plan mode toggle) unless the user explicitly asked not to use plan mode.
+- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation, make a plan in the current mode, or ask clarifying questions. Do not enter plan mode or call enter_plan_mode on your own just because the task involves planning or complexity. Use plan mode only when the user explicitly asks you to switch to plan mode, has already enabled it, or confirms they want it.
 
 
 # Task Management
@@ -3191,7 +3191,7 @@ exports[`Model-specific tool call formats > should use bracket format for generi
 - **Confirm Ambiguity/Expansion:** Do not take significant actions beyond the clear scope of the request without confirming with the user. If asked *how* to do something, explain first, don't just do it.
 - **Do Not revert changes:** Do not revert changes to the codebase unless asked to do so by the user. Only revert changes made by you if they have resulted in an error or if the user has explicitly asked you to revert the changes.
 - **Denied Tool Calls:** If a tool call is denied, do not try to complete the denied action through another tool, shell indirection, generated script, alias, symlink, config change, hook, command file, MCP configuration, encoded payload, or equivalent path. If that action is required, stop and ask the user for explicit approval. You may continue with unrelated safe work or a genuinely safer alternative that does not accomplish the denied action.
-- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation or ask clarifying questions. When the work requires a shared plan before execution, enter plan mode (via enter_plan_mode if available, or the user's plan mode toggle) unless the user explicitly asked not to use plan mode.
+- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation, make a plan in the current mode, or ask clarifying questions. Do not enter plan mode or call enter_plan_mode on your own just because the task involves planning or complexity. Use plan mode only when the user explicitly asks you to switch to plan mode, has already enabled it, or confirms they want it.
 
 
 # Task Management
@@ -3417,7 +3417,7 @@ exports[`Model-specific tool call formats > should use bracket format when no mo
 - **Confirm Ambiguity/Expansion:** Do not take significant actions beyond the clear scope of the request without confirming with the user. If asked *how* to do something, explain first, don't just do it.
 - **Do Not revert changes:** Do not revert changes to the codebase unless asked to do so by the user. Only revert changes made by you if they have resulted in an error or if the user has explicitly asked you to revert the changes.
 - **Denied Tool Calls:** If a tool call is denied, do not try to complete the denied action through another tool, shell indirection, generated script, alias, symlink, config change, hook, command file, MCP configuration, encoded payload, or equivalent path. If that action is required, stop and ask the user for explicit approval. You may continue with unrelated safe work or a genuinely safer alternative that does not accomplish the denied action.
-- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation or ask clarifying questions. When the work requires a shared plan before execution, enter plan mode (via enter_plan_mode if available, or the user's plan mode toggle) unless the user explicitly asked not to use plan mode.
+- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation, make a plan in the current mode, or ask clarifying questions. Do not enter plan mode or call enter_plan_mode on your own just because the task involves planning or complexity. Use plan mode only when the user explicitly asks you to switch to plan mode, has already enabled it, or confirms they want it.
 
 
 # Task Management

packages/core/src/core/prompts.test.ts

@@ -67,6 +67,21 @@ describe('Core System Prompt (prompts.ts)', () => {
     expect(prompt).toContain('stop and ask the user for explicit approval');
   });
 
+  it('does not tell the model to enter plan mode without user opt-in', () => {
+    vi.stubEnv('SANDBOX', undefined);
+    const prompt = getCoreSystemPrompt();
+
+    expect(prompt).toContain(
+      'Do not enter plan mode or call enter_plan_mode on your own',
+    );
+    expect(prompt).toContain(
+      'Use plan mode only when the user explicitly asks you to switch to plan mode',
+    );
+    expect(prompt).not.toContain(
+      'When the work requires a shared plan before execution, enter plan mode',
+    );
+  });
+
   it('should return the base prompt when userMemory is empty string', () => {
     vi.stubEnv('SANDBOX', undefined);
     const prompt = getCoreSystemPrompt('');

packages/core/src/core/prompts.ts

@@ -150,7 +150,7 @@ You are Qwen Code, an interactive CLI agent developed by Alibaba Group, speciali
 - **Confirm Ambiguity/Expansion:** Do not take significant actions beyond the clear scope of the request without confirming with the user. If asked *how* to do something, explain first, don't just do it.
 - **Do Not revert changes:** Do not revert changes to the codebase unless asked to do so by the user. Only revert changes made by you if they have resulted in an error or if the user has explicitly asked you to revert the changes.
 - **Denied Tool Calls:** If a tool call is denied, do not try to complete the denied action through another tool, shell indirection, generated script, alias, symlink, config change, hook, command file, MCP configuration, encoded payload, or equivalent path. If that action is required, stop and ask the user for explicit approval. You may continue with unrelated safe work or a genuinely safer alternative that does not accomplish the denied action.
-- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation or ask clarifying questions. When the work requires a shared plan before execution, enter plan mode (via ${ToolNames.ENTER_PLAN_MODE} if available, or the user's plan mode toggle) unless the user explicitly asked not to use plan mode.
+- **Plan before uncertain work:** If the task is not yet clear enough to safely execute, do not make small speculative edits. Continue read-only investigation, make a plan in the current mode, or ask clarifying questions. Do not enter plan mode or call ${ToolNames.ENTER_PLAN_MODE} on your own just because the task involves planning or complexity. Use plan mode only when the user explicitly asks you to switch to plan mode, has already enabled it, or confirms they want it.
 
 
 # Task Management

packages/core/src/tools/enterPlanMode.test.ts

@@ -48,6 +48,19 @@ describe('EnterPlanModeTool', () => {
       expect(tool.kind).toBe('think');
     });
 
+    it('should require user opt-in in the tool description', () => {
+      expect(tool.description).toContain(
+        'only after the user explicitly asks to switch into plan mode',
+      );
+      expect(tool.description).toContain(
+        'If plan mode seems helpful but the user has not asked for it, ask first',
+      );
+      expect(tool.description).not.toContain(
+        'before doing uncertain or complex work',
+      );
+      expect(tool.description).not.toContain('if complexity rises');
+    });
+
     it('should not defer (always visible)', () => {
       expect(tool.shouldDefer).toBe(false);
     });

packages/core/src/tools/enterPlanMode.ts

@@ -18,16 +18,16 @@ const debugLogger = createDebugLogger('ENTER_PLAN_MODE');
 
 export type EnterPlanModeParams = Record<string, never>;
 
-const enterPlanModeToolDescription = `Use this tool to lower into plan mode before doing uncertain or complex work. Entering plan mode is a privilege reduction, so it does not require user confirmation.
+const enterPlanModeToolDescription = `Use this tool only after the user explicitly asks to switch into plan mode or confirms they want plan mode. Entering plan mode is a privilege reduction, so it does not require user confirmation at execution time.
 
 ## When to Use This Tool
-Use this tool when the task is not yet clear enough to safely execute, for example when it requires multi-file changes, design choices, investigation before a plan can be summarized, or when requirements are ambiguous. While investigating, if complexity rises or you find yourself repeatedly needing to ask the user, enter plan mode and consolidate a plan.
+Use this tool when the user has opted into plan mode for a task that should be read-only while the plan is formed, such as multi-file changes, design choices, or ambiguous requirements.
 
 ## When NOT to Use This Tool
-If the request is already clear, small, and low-risk, you may execute directly without entering plan mode. Do not make speculative small edits before you have thought the change through.
+Do not use this tool just because a task involves planning, is complex, or requires investigation. In the current mode, you can still think, inspect files, ask clarifying questions, and present a plan without switching modes.
 
 ## Important
-Do NOT use this tool if the user has explicitly asked you not to use plan mode.`;
+If plan mode seems helpful but the user has not asked for it, ask first. Do NOT use this tool if the user has explicitly asked you not to use plan mode.`;
 
 const enterPlanModeToolSchemaData: FunctionDeclaration = {
   name: 'enter_plan_mode',
@@ -154,7 +154,7 @@ export class EnterPlanModeTool extends BaseDeclarativeTool<
       >,
       true, // isOutputMarkdown
       false, // canUpdateOutput
-      false, // shouldDefer — always visible so the model can enter plan mode
+      false, // shouldDefer — always visible so explicit plan-mode requests work
       false, // alwaysLoad
       'plan mode enter start',
     );