🤖 refactor: remove plan subagent auto-handoff

Remove plan-mode subagent auto-handoff after propose_plan, drop the executor-routing settings and backend router, reject plan-like task creation, and update related docs/stories/tests.

---

_Generated with `mux` • Model: `openai:gpt-5.4` • Thinking: `high` • Cost: `$2.78`_

<!-- mux-attribution: model=openai:gpt-5.4 thinking=high costs=2.78 -->

Author: ammar-agent

docs/AGENTS.md

@@ -59,6 +59,7 @@ description: Agent instructions for AI assistants working on the Mux codebase
 Use `agent-browser` for web automation. Run `agent-browser --help` for all commands.
 
 Core workflow:
+
 1. `agent-browser open <url>` - Navigate to page
 2. `agent-browser snapshot -i` - Get interactive elements with refs (@e1, @e2)
 3. `agent-browser click @e1` / `fill @e2 "text"` - Interact using refs
@@ -69,7 +70,7 @@ Core workflow:
 - If a PR has Codex review comments, address + resolve them, then re-request review by commenting `@codex review` on the PR.
 - Prefer `gh` CLI for GitHub interactions over manual web/curl flows.
 - In Orchestrator mode, delegate implementation/verification commands to `exec` or `explore` sub-agents and integrate their patches; do not bypass delegation with direct local edits.
-- In Orchestrator mode, route higher-complexity implementation tasks to `plan` sub-agents so they can research and produce a precise plan before auto-handoff to implementation.
+- In Orchestrator mode, keep implementation tasks on `exec` sub-agents; use a top-level plan workspace when you need a separate planning phase before delegation.
 
 - User preference: when work is already on an open PR, push branch updates at the end of each completed change set so the PR stays current.
 - **PR creation gate:** Do **not** open/create a pull request unless the user explicitly asks (e.g., "open a PR", "create PR", "submit this"). By default, complete local validation, commit/push branch updates as requested, and let the user review before deciding whether to open a PR.

docs/agents/index.mdx

@@ -526,9 +526,9 @@ Example dependency chain (schema download → generation):
 Patch integration loop (default):
 
 1. Identify a batch of independent subtasks.
-2. Spawn one implementation sub-agent task per subtask with `run_in_background: true` (`exec` for low complexity, `plan` for higher complexity).
+2. Spawn one `exec` implementation sub-agent task per subtask with `run_in_background: true`.
 3. Await the batch via `task_await`.
-4. For each successful implementation task (`exec` directly, or `plan` after auto-handoff to implementation), integrate patches one at a time:
+4. For each successful implementation task, integrate patches one at a time:
    - Treat every successful child task with a `taskId` as pending patch integration, whether the completion arrived inline from `task` or later from `task_await`.
    - Complete each dry-run + real-apply pair before starting the next patch. Applying one patch changes `HEAD`, which can invalidate later dry-run results.
    - Dry-run apply: `task_apply_git_patch` with `dry_run: true`.

src/browser/components/icons/EmojiIcon/EmojiIcon.tsx

@@ -48,7 +48,6 @@ const EMOJI_TO_ICON: Record<string, LucideIcon> = {
   "🔗": Link,
   "🔄": RefreshCw,
   "🧪": Beaker,
-  // Used by auto-handoff routing status while selecting the executor.
   "🤔": CircleHelp,
 
   // Directions

src/browser/features/Settings/Sections/TasksSection.tsx

@@ -34,9 +34,7 @@ import {
 import {
   DEFAULT_TASK_SETTINGS,
   TASK_SETTINGS_LIMITS,
-  isPlanSubagentExecutorRouting,
   normalizeTaskSettings,
-  type PlanSubagentExecutorRouting,
   type TaskSettings,
 } from "@/common/types/tasks";
 import { getThinkingOptionLabel, type ThinkingLevel } from "@/common/types/thinking";
@@ -173,8 +171,6 @@ function areTaskSettingsEqual(a: TaskSettings, b: TaskSettings): boolean {
     a.maxParallelAgentTasks === b.maxParallelAgentTasks &&
     a.maxTaskNestingDepth === b.maxTaskNestingDepth &&
     a.proposePlanImplementReplacesChatHistory === b.proposePlanImplementReplacesChatHistory &&
-    a.planSubagentExecutorRouting === b.planSubagentExecutorRouting &&
-    a.planSubagentDefaultsToOrchestrator === b.planSubagentDefaultsToOrchestrator &&
     a.bashOutputCompactionMinLines === b.bashOutputCompactionMinLines &&
     a.bashOutputCompactionMinTotalBytes === b.bashOutputCompactionMinTotalBytes &&
     a.bashOutputCompactionMaxKeptLines === b.bashOutputCompactionMaxKeptLines &&
@@ -499,25 +495,10 @@ export function TasksSection() {
     );
   };
 
-  const setPlanSubagentExecutorRouting = (value: string) => {
-    if (!isPlanSubagentExecutorRouting(value)) {
-      return;
-    }
-
-    setTaskSettings((prev) =>
-      normalizeTaskSettings({
-        ...prev,
-        planSubagentExecutorRouting: value,
-      })
-    );
-  };
   const setNewWorkspaceDefaultAgentId = (agentId: string) => {
     setGlobalDefaultAgentIdRaw(coerceAgentId(agentId));
   };
 
-  const planSubagentExecutorRouting: PlanSubagentExecutorRouting =
-    taskSettings.planSubagentExecutorRouting ?? "exec";
-
   const setAgentModel = (agentId: string, value: string) => {
     setAgentAiDefaults((prev) =>
       updateAgentDefaultEntry(prev, agentId, (updated) => {
@@ -917,28 +898,6 @@ export function TasksSection() {
               aria-label="Toggle plan Implement replaces conversation with plan"
             />
           </div>
-
-          <div className="flex items-center justify-between gap-4">
-            <div className="flex-1">
-              <div className="text-foreground text-sm">Plan sub-agents: executor routing</div>
-              <div className="text-muted text-xs">
-                Choose how plan sub-agent tasks route after propose_plan.
-              </div>
-            </div>
-            <Select
-              value={planSubagentExecutorRouting}
-              onValueChange={setPlanSubagentExecutorRouting}
-            >
-              <SelectTrigger className="border-border-medium bg-background-secondary h-9 w-44">
-                <SelectValue />
-              </SelectTrigger>
-              <SelectContent>
-                <SelectItem value="exec">Exec</SelectItem>
-                <SelectItem value="orchestrator">Orchestrator</SelectItem>
-                <SelectItem value="auto">Auto (Agent chooses)</SelectItem>
-              </SelectContent>
-            </Select>
-          </div>
         </div>
 
         {saveError ? <div className="text-danger-light mt-4 text-xs">{saveError}</div> : null}

src/browser/features/Tools/ProposePlan/ProposePlanToolCall.stories.tsx

@@ -6,12 +6,7 @@ import {
   createUserMessage,
   createAssistantMessage,
   createProposePlanTool,
-  createStatusTool,
 } from "@/browser/stories/mockFactory";
-import {
-  PLAN_AUTO_ROUTING_STATUS_EMOJI,
-  PLAN_AUTO_ROUTING_STATUS_MESSAGE,
-} from "@/common/constants/planAutoRoutingStatus";
 
 const meta = { ...appMeta, title: "App/Chat/Tools/ProposePlan" };
 export default meta;
@@ -167,84 +162,6 @@ graph TD
   },
 };
 
-/**
- * Captures the handoff pause after a plan is presented and before the executor stream starts.
- *
- * This reproduces the visual state where the sidebar shows "Deciding execution strategy…"
- * while the proposed plan remains visible in the conversation.
- */
-export const ProposePlanAutoRoutingDecisionGap: AppStory = {
-  render: () => (
-    <AppWithMocks
-      setup={() =>
-        setupSimpleChatStory({
-          workspaceId: "ws-plan-auto-routing-gap",
-          workspaceName: "feature/plan-auto-routing",
-          messages: [
-            createUserMessage(
-              "msg-1",
-              "Plan and implement a safe migration rollout for auth tokens.",
-              {
-                historySequence: 1,
-                timestamp: STABLE_TIMESTAMP - 240000,
-              }
-            ),
-            createAssistantMessage("msg-2", "Here is the implementation plan.", {
-              historySequence: 2,
-              timestamp: STABLE_TIMESTAMP - 230000,
-              toolCalls: [
-                createProposePlanTool(
-                  "call-plan-1",
-                  `# Auth Token Migration Rollout
-
-## Goals
-
-- Migrate token validation to the new signing service.
-- Maintain compatibility during rollout.
-- Keep rollback simple and low risk.
-
-## Steps
-
-1. Add dual-read token validation behind a feature flag.
-2. Ship telemetry for token verification outcomes.
-3. Enable new validator for 10% of traffic.
-4. Ramp to 100% after stability checks.
-5. Remove legacy validator once metrics stay healthy.
-
-## Rollback
-
-- Disable the rollout flag to return to legacy validation immediately.
-- Keep telemetry running to confirm recovery.`
-                ),
-              ],
-            }),
-            createAssistantMessage("msg-3", "Selecting the right executor for this plan.", {
-              historySequence: 3,
-              timestamp: STABLE_TIMESTAMP - 220000,
-              toolCalls: [
-                createStatusTool(
-                  "call-status-1",
-                  PLAN_AUTO_ROUTING_STATUS_EMOJI,
-                  PLAN_AUTO_ROUTING_STATUS_MESSAGE
-                ),
-              ],
-            }),
-          ],
-        })
-      }
-    />
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Chromatic regression story for the plan auto-routing gap: after `propose_plan` succeeds, " +
-          "the sidebar stays in a working state with a 'Deciding execution strategy…' status before executor kickoff.",
-      },
-    },
-  },
-};
-
 /**
  * Mobile viewport version of ProposePlan.
  *

src/common/config/schemas/appConfigOnDisk.ts

@@ -8,8 +8,8 @@ import { TaskSettingsSchema } from "./taskSettings";
 
 export { RuntimeEnablementOverridesSchema } from "../../schemas/runtimeEnablement";
 export type { RuntimeEnablementOverrides } from "../../schemas/runtimeEnablement";
-export { PlanSubagentExecutorRoutingSchema, TaskSettingsSchema } from "./taskSettings";
-export type { PlanSubagentExecutorRouting, TaskSettings } from "./taskSettings";
+export { TaskSettingsSchema } from "./taskSettings";
+export type { TaskSettings } from "./taskSettings";
 
 export const AgentAiDefaultsEntrySchema = z.object({
   modelString: z.string().optional(),

src/common/config/schemas/taskSettings.ts

@@ -12,10 +12,6 @@ export const SYSTEM1_BASH_OUTPUT_COMPACTION_LIMITS = {
   bashOutputCompactionTimeoutMs: { min: 1_000, max: 120_000, default: 5_000 },
 } as const;
 
-export const PlanSubagentExecutorRoutingSchema = z.enum(["exec", "orchestrator", "auto"]);
-
-export type PlanSubagentExecutorRouting = z.infer<typeof PlanSubagentExecutorRoutingSchema>;
-
 export const TaskSettingsSchema = z.object({
   maxParallelAgentTasks: z
     .number()
@@ -30,8 +26,6 @@ export const TaskSettingsSchema = z.object({
     .max(TASK_SETTINGS_LIMITS.maxTaskNestingDepth.max)
     .optional(),
   proposePlanImplementReplacesChatHistory: z.boolean().optional(),
-  planSubagentExecutorRouting: PlanSubagentExecutorRoutingSchema.optional(),
-  planSubagentDefaultsToOrchestrator: z.boolean().optional(),
   bashOutputCompactionMinLines: z
     .number()
     .int()

src/common/constants/planAutoRoutingStatus.ts

@@ -53,36 +53,12 @@ describe("normalizeTaskSettings", () => {
     expect(normalized).toEqual(DEFAULT_TASK_SETTINGS);
   });
 
-  test("preserves explicit planSubagentExecutorRouting values", () => {
+  test("ignores removed plan subagent handoff settings", () => {
     const normalized = normalizeTaskSettings({
-      planSubagentExecutorRouting: "auto",
-    });
-
-    expect(normalized.planSubagentExecutorRouting).toBe("auto");
-    expect(normalized.planSubagentDefaultsToOrchestrator).toBe(false);
-  });
-
-  test("migrates deprecated planSubagentDefaultsToOrchestrator when routing is unset", () => {
-    expect(
-      normalizeTaskSettings({
-        planSubagentDefaultsToOrchestrator: true,
-      }).planSubagentExecutorRouting
-    ).toBe("orchestrator");
-
-    expect(
-      normalizeTaskSettings({
-        planSubagentDefaultsToOrchestrator: false,
-      }).planSubagentExecutorRouting
-    ).toBe("exec");
-  });
-
-  test("prefers planSubagentExecutorRouting when both new and deprecated fields are set", () => {
-    const normalized = normalizeTaskSettings({
-      planSubagentExecutorRouting: "exec",
+      planSubagentExecutorRouting: "orchestrator",
       planSubagentDefaultsToOrchestrator: true,
     });
 
-    expect(normalized.planSubagentExecutorRouting).toBe("exec");
-    expect(normalized.planSubagentDefaultsToOrchestrator).toBe(false);
+    expect(normalized).toEqual(DEFAULT_TASK_SETTINGS);
   });
 });

src/common/types/tasks.test.ts

@@ -1,7 +1,4 @@
-import type {
-  PlanSubagentExecutorRouting,
-  TaskSettings as TaskSettingsOnDisk,
-} from "@/common/config/schemas/taskSettings";
+import type { TaskSettings as TaskSettingsOnDisk } from "@/common/config/schemas/taskSettings";
 import {
   SYSTEM1_BASH_OUTPUT_COMPACTION_LIMITS,
   TASK_SETTINGS_LIMITS,
@@ -13,7 +10,7 @@ import type {
 import assert from "@/common/utils/assert";
 import { coerceThinkingLevel, type ThinkingLevel } from "./thinking";
 
-export type { PlanSubagentExecutorRouting, SubagentAiDefaults, SubagentAiDefaultsEntry };
+export type { SubagentAiDefaults, SubagentAiDefaultsEntry };
 export {
   SYSTEM1_BASH_OUTPUT_COMPACTION_LIMITS,
   TASK_SETTINGS_LIMITS,
@@ -29,8 +26,6 @@ export const DEFAULT_TASK_SETTINGS: TaskSettings = {
   maxParallelAgentTasks: TASK_SETTINGS_LIMITS.maxParallelAgentTasks.default,
   maxTaskNestingDepth: TASK_SETTINGS_LIMITS.maxTaskNestingDepth.default,
   proposePlanImplementReplacesChatHistory: false,
-  planSubagentExecutorRouting: "auto",
-  planSubagentDefaultsToOrchestrator: false,
 
   bashOutputCompactionMinLines:
     SYSTEM1_BASH_OUTPUT_COMPACTION_LIMITS.bashOutputCompactionMinLines.default,
@@ -84,12 +79,6 @@ function clampInt(value: unknown, fallback: number, min: number, max: number): n
   return rounded;
 }
 
-export function isPlanSubagentExecutorRouting(
-  value: unknown
-): value is PlanSubagentExecutorRouting {
-  return value === "exec" || value === "orchestrator" || value === "auto";
-}
-
 export function normalizeTaskSettings(raw: unknown): TaskSettings {
   const record = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : ({} as const);
 
@@ -111,28 +100,6 @@ export function normalizeTaskSettings(raw: unknown): TaskSettings {
       ? record.proposePlanImplementReplacesChatHistory
       : (DEFAULT_TASK_SETTINGS.proposePlanImplementReplacesChatHistory ?? false);
 
-  const normalizedPlanSubagentExecutorRouting = isPlanSubagentExecutorRouting(
-    record.planSubagentExecutorRouting
-  )
-    ? record.planSubagentExecutorRouting
-    : undefined;
-
-  const migratedPlanSubagentExecutorRouting =
-    normalizedPlanSubagentExecutorRouting ??
-    (typeof record.planSubagentDefaultsToOrchestrator === "boolean"
-      ? record.planSubagentDefaultsToOrchestrator
-        ? "orchestrator"
-        : "exec"
-      : undefined);
-
-  const planSubagentExecutorRouting =
-    migratedPlanSubagentExecutorRouting ??
-    DEFAULT_TASK_SETTINGS.planSubagentExecutorRouting ??
-    "exec";
-
-  // Keep the deprecated boolean in sync for downgrade compatibility.
-  const planSubagentDefaultsToOrchestrator = planSubagentExecutorRouting === "orchestrator";
-
   const bashOutputCompactionMinLines = clampInt(
     record.bashOutputCompactionMinLines,
     SYSTEM1_BASH_OUTPUT_COMPACTION_LIMITS.bashOutputCompactionMinLines.default,
@@ -168,8 +135,6 @@ export function normalizeTaskSettings(raw: unknown): TaskSettings {
     maxParallelAgentTasks,
     maxTaskNestingDepth,
     proposePlanImplementReplacesChatHistory,
-    planSubagentExecutorRouting,
-    planSubagentDefaultsToOrchestrator,
     bashOutputCompactionMinLines,
     bashOutputCompactionMinTotalBytes,
     bashOutputCompactionMaxKeptLines,
@@ -191,16 +156,6 @@ export function normalizeTaskSettings(raw: unknown): TaskSettings {
     "normalizeTaskSettings: proposePlanImplementReplacesChatHistory must be a boolean"
   );
 
-  assert(
-    isPlanSubagentExecutorRouting(planSubagentExecutorRouting),
-    "normalizeTaskSettings: planSubagentExecutorRouting must be exec, orchestrator, or auto"
-  );
-
-  assert(
-    typeof planSubagentDefaultsToOrchestrator === "boolean",
-    "normalizeTaskSettings: planSubagentDefaultsToOrchestrator must be a boolean"
-  );
-
   assert(
     Number.isInteger(bashOutputCompactionMinLines),
     "normalizeTaskSettings: bashOutputCompactionMinLines must be an integer"