feat: plan mode — /plan toggle, submit_plan tool, and plan_model for dual-model execution #2788

Problem

Agentic workflows that span many tool calls (write files, run commands, call GitHub APIs) give users no control point between "I described what I want" and "the agent already did it."

The only safeguard today is an instruction asking agents to present a plan and wait — a soft control that works most of the time but has no runtime enforcement, and cannot be toggled at runtime without modifying config files.

Two concrete gaps:

1. No user-controlled mode switch. There is no way to type /plan in the TUI to enter a careful, plan-then-approve mode for a risky task — and then /plan off to return to fluid execution for a simple one.
2. No cost-optimised planning. Planning requires deep reasoning (costly model, used once). Execution is mechanical (cheaper model, used N times). There is no way to route the planning turn to a different model than the execution turns.

Prior Art

Every mature agentic system has converged on this pattern:

Key pattern across all: plan generation is separated from execution, the plan is shown to the user, and execution is gated on approval.

Cursor model-routing (verified, May 2026 changelog):

"Added the ability to control Explore subagent behavior from settings: choose a specific model for Explore subagents to run on, inherit the same model as the parent agent, or disable Explore subagents altogether."
"Added support for general model names for subagent configuration."
"/multitask is now available in the editor for running async subagents."

Anthropic extended thinking API (confirmed from SDK):

response = client.messages.create(
    model="claude-sonnet-4-5",
    thinking={"type": "enabled", "budget_tokens": 1600},
    ...
)
# Response contains separate `thinking` block and `text` block.
# The approval gate is the application's responsibility — no built-in pause.

Proposed Solution

Three composable additions:

1. submit_plan built-in tool

Agent calls submit_plan(title, steps, rationale) before any side-effecting action. The runtime renders the plan in the TUI, pauses, and waits for explicit user approval.

{
  "title": "Implement configurable retry policy",
  "steps": [
    {
      "description": "Add RetryConfig struct to pkg/config/latest/types.go",
      "tool": "edit_file",
      "target": "pkg/config/latest/types.go",
      "expected_outcome": "RetryConfig embedded in ToolsetConfig"
    },
    {
      "description": "task build / task test / task lint",
      "tool": "shell",
      "target": "task build && task test && task lint"
    }
  ],
  "rationale": "Follows existing sessions config pattern; backwards compat — defaults to no retry."
}

Tool output on approval:

{ "approved": true, "plan_id": "uuid" }

On rejection with user note:

{ "approved": false, "reason": "Don't touch dispatcher.go yet, design first" }

TUI rendering (proposed):

╭─ Plan: "Implement configurable retry policy" ──────────────────────╮
│  1. Edit pkg/config/latest/types.go → add RetryConfig struct       │
│  2. Edit pkg/runtime/dispatcher.go  → read RetryConfig per toolset │
│  3. Update agent-schema.json                                        │
│  4. task build / task test / task lint                              │
│                                                                     │
│  Rationale: follows sessions config pattern; backwards compat.      │
│                                                                     │
│  [Approve ↵]   [Reject esc]   [Modify: type changes ...]           │
╰─────────────────────────────────────────────────────────────────────╯

2. /plan TUI command (session-level toggle)

/plan           → enter plan mode for this session
/plan off       → exit plan mode; return to normal execution
/plan status    → show current mode

When plan mode is active, the runtime sets an in-memory flag that enforces plan_mode: strict for the session — no config file change needed. Users decide per-task whether they want a careful review cycle or fluid execution.

This follows the same pattern as Cursor's /multitask command: a slash command that toggles a session-level behaviour without touching config.

3. plan_model agent config field (dual-model execution)

agents:
  coder:
    model: sonnet       # execution model — fast, cheap, used every step
    plan_model: opus    # planning model — deep reasoning, used once per task
    plan_mode: soft     # off | soft | strict

When plan_model is set, the runtime switches to it for the submit_plan turn only, then reverts to model for all execution turns.

Why this matters:

• Planning is a reasoning task. Opus/o1-class models do it significantly better.
• Execution turns are mechanical. Sonnet is sufficient and ~5x cheaper.
• OpenAI's Operator uses exactly this pattern (o1-preview for planning, gpt-4o for execution).
• Cursor now exposes the same knob for subagents (May 2026).
• docker-agent already has this pattern: Toolset.Model for per-toolset routing and model: frontmatter on skills. plan_model on AgentConfig is a natural extension.

plan_mode config values

/plan in the TUI activates strict mode for the session regardless of config.

Affected Components

Phasing

Phase 1 alone is already a meaningful improvement over instruction-only plan-first.

Alternatives Considered

• permissions: ask: list — exists today; forces per-call confirmation (N prompts instead of 1 plan). High friction for multi-step tasks.
• Hook-based enforcement — user_prompt_submit sets a token; pre_tool_use checks it. Stateful shell scripts, fragile, no UX.
• Instruction-only — current approach; works with capable models but degrades under long context and cannot be toggled.
• Skill-based plan template — a /plan-first skill providing a structured format. Still a soft control; useful as a complement, not a replacement.

submit_plan + /plan toggle + plan_model is the only combination that gives good UX (one approval per plan, toggleable per-task), optional enforcement (strict mode), and cost-optimised dual-model execution.