fix: Reduce agent eagerness to re-enter plan mode mid-task (#1208)

Author: charlesvien

packages/agent/src/adapters/claude/session/instructions.ts

@@ -0,0 +1,19 @@
+const BRANCH_NAMING = `
+# Branch Naming
+
+When working in a detached HEAD state, create a descriptive branch name based on the work being done before committing. Do this automatically without asking the user.
+`;
+
+const PLAN_MODE = `
+# Plan Mode
+
+Only enter plan mode (EnterPlanMode) when the user is requesting a significant change in approach or direction mid-task. Do NOT enter plan mode for:
+- Confirmations or approvals ("yes", "looks good", "continue", "go ahead")
+- Minor clarifications or small adjustments
+- Answers to questions you asked (unless you are still in the initial planning phase and have not yet started executing)
+- Feedback that does not require replanning
+
+When in doubt, continue executing and incorporate the feedback inline.
+`;
+
+export const APPENDED_INSTRUCTIONS = BRANCH_NAMING + PLAN_MODE;

packages/agent/src/adapters/claude/session/options.ts

@@ -18,6 +18,7 @@ import {
 } from "../hooks";
 import type { CodeExecutionMode } from "../tools";
 import type { EffortLevel } from "../types";
+import { APPENDED_INSTRUCTIONS } from "./instructions";
 import { DEFAULT_MODEL } from "./models";
 import type { SettingsManager } from "./settings";
 
@@ -47,27 +48,21 @@ export interface BuildOptionsParams {
   effort?: EffortLevel;
 }
 
-const BRANCH_NAMING_INSTRUCTIONS = `
-# Branch Naming
-
-When working in a detached HEAD state, create a descriptive branch name based on the work being done before committing. Do this automatically without asking the user.
-`;
-
 export function buildSystemPrompt(
   customPrompt?: unknown,
 ): Options["systemPrompt"] {
   const defaultPrompt: Options["systemPrompt"] = {
     type: "preset",
     preset: "claude_code",
-    append: BRANCH_NAMING_INSTRUCTIONS,
+    append: APPENDED_INSTRUCTIONS,
   };
 
   if (!customPrompt) {
     return defaultPrompt;
   }
 
   if (typeof customPrompt === "string") {
-    return customPrompt + BRANCH_NAMING_INSTRUCTIONS;
+    return customPrompt + APPENDED_INSTRUCTIONS;
   }
 
   if (
@@ -78,7 +73,7 @@ export function buildSystemPrompt(
   ) {
     return {
       ...defaultPrompt,
-      append: customPrompt.append + BRANCH_NAMING_INSTRUCTIONS,
+      append: customPrompt.append + APPENDED_INSTRUCTIONS,
     };
   }