From 0cb264870d875ea23cbc3938ce8b25d754b6c9d2 Mon Sep 17 00:00:00 2001
From: 7Sageer <7sageer@djwcb.cn>
Date: Wed, 8 Jul 2026 15:09:47 +0800
Subject: [PATCH] fix(agent-core-v2): align plan mode guidance with v1

---
 .../policies/plan-mode-guard-deny.ts                 |  2 +-
 .../src/agent/plan/tools/enter-plan-mode.md          |  8 +-------
 .../src/agent/plan/tools/exit-plan-mode.md           | 12 ++++--------
 3 files changed, 6 insertions(+), 16 deletions(-)

diff --git a/packages/agent-core-v2/src/agent/permissionPolicy/policies/plan-mode-guard-deny.ts b/packages/agent-core-v2/src/agent/permissionPolicy/policies/plan-mode-guard-deny.ts
index 88297584b..f09f3e0e4 100644
--- a/packages/agent-core-v2/src/agent/permissionPolicy/policies/plan-mode-guard-deny.ts
+++ b/packages/agent-core-v2/src/agent/permissionPolicy/policies/plan-mode-guard-deny.ts
@@ -33,7 +33,7 @@ export class PlanModeGuardDenyPermissionPolicyService implements PermissionPolic
       return {
         kind: 'deny',
         message:
-          'TaskStop is not available in plan mode. Call ExitPlanMode to exit plan mode before stopping a task.',
+          'TaskStop is not available in plan mode. Call ExitPlanMode to exit plan mode before stopping a background task.',
       };
     }
 
diff --git a/packages/agent-core-v2/src/agent/plan/tools/enter-plan-mode.md b/packages/agent-core-v2/src/agent/plan/tools/enter-plan-mode.md
index d792e71b7..a4b7438b1 100644
--- a/packages/agent-core-v2/src/agent/plan/tools/enter-plan-mode.md
+++ b/packages/agent-core-v2/src/agent/plan/tools/enter-plan-mode.md
@@ -23,10 +23,4 @@ When NOT to use:
 - User gave very specific, detailed instructions
 - Pure research/exploration tasks
 
-## What Happens in Plan Mode
-In plan mode, you will:
-1. Identify 2-3 key questions about the codebase that are critical to your plan. If you are not confident about the codebase structure or relevant code paths, use `Agent(subagent_type="explore")` to investigate these questions first - this is strongly recommended for non-trivial tasks.
-2. Explore the codebase using Glob, Grep, Read, and other read-only tools for any remaining quick lookups. Use Bash only when needed; Bash follows the normal permission mode and rules.
-3. Design an implementation approach based on your findings
-4. Write your plan to the current plan file with Write or Edit
-5. Present your plan to the user via ExitPlanMode for approval
+Once you are in plan mode, a reminder walks you through the workflow (explore → design → write the plan file → `ExitPlanMode`) and enforces read-only access. For non-trivial tasks where you are unsure of the codebase structure or relevant code paths, use `Agent(subagent_type="explore")` to investigate first when the `Agent` tool is available.
diff --git a/packages/agent-core-v2/src/agent/plan/tools/exit-plan-mode.md b/packages/agent-core-v2/src/agent/plan/tools/exit-plan-mode.md
index b83f47f38..028376269 100644
--- a/packages/agent-core-v2/src/agent/plan/tools/exit-plan-mode.md
+++ b/packages/agent-core-v2/src/agent/plan/tools/exit-plan-mode.md
@@ -8,15 +8,11 @@ Use this tool when you are in plan mode and have finished writing your plan to t
 ## When to Use
 Only use this tool for tasks that require planning implementation steps. For research tasks (searching files, reading code, understanding the codebase), do NOT use this tool.
 
+## What a good plan contains
+List specific, verifiable steps grounded in the actual codebase — real files, functions, and commands, in a sensible order. Each step should be concrete enough to act on and to check. Avoid vague filler like "improve performance" or "add tests"; say what to change and where.
+
 ## Multiple Approaches
-If your plan contains multiple alternative approaches:
-- Pass them via the `options` parameter so the user can choose which approach to execute.
-- Each option should have a concise label and a brief description of trade-offs.
-- If you recommend one option, append "(Recommended)" to its label.
-- In yolo and manual modes, the user will see all options alongside Reject and Revise choices.
-- Provide up to 3 options; the host adds the standard rejection and revision controls. When the plan offers a real choice, 2-3 distinct approaches work best.
-- Passing a single option is allowed and is equivalent to a plain plan approval (no approach choice is surfaced to the user).
-- Do NOT use "Reject", "Reject and Exit", "Revise", or "Approve" as option labels - these are reserved by the system.
+If your plan offers multiple alternative approaches, pass them via the `options` parameter so the user can choose which one to execute — see the `options` parameter for the format, count, and reserved labels. In yolo and manual modes the user sees all options alongside the host's Reject and Revise controls.
 
 ## Before Using
 - In auto permission mode, do NOT use AskUserQuestion; make the best decision from available context.