> ## Documentation Index
> Fetch the complete documentation index at: https://continuum-three-olive.vercel.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Plan Mode

> Have an agent explore read-only and propose a plan before it writes anything — then flip to Code with one click.

Continuum collapses an agent's permission tiers into a single two-state pill: **Plan** and **Code**.

* **Plan** — the agent explores read-only and proposes what it intends to do before touching any files.
* **Code** — the agent writes and runs with **maximum permissions** for that provider.

Picking Code is a one-click flip. There is no confirmation sheet and no per-repo trust step: **Code always skips approvals**, for every provider, in every repo.

<Warning>
  Continuum used to gate Code behind a per-repo trust list — a "Trust this repo?" prompt, and a daemon that returned `403` when an untrusted repo tried to enable it. **That gate was removed.** Skip-approvals now resolves purely from which pole the pill is on. Plan still never bypasses anything.

  The practical consequence: flipping to Code is exactly as consequential as running the CLI yourself with permissions skipped. Treat it that way, especially on a repo you didn't write.
</Warning>

## Where you toggle Plan / Code

| Surface                      | Control                                                                                                                       |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Mac composer**             | The **Plan ↔ Code pill** in the composer's chip row. Click anywhere on it to flip; `⌘⇧1` selects Plan and `⌘⇧2` selects Code. |
| **Mac new-session composer** | The same pill in the floating new-session box, so a session starts in the mode you want.                                      |
| **iPhone new-session sheet** | A Plan ↔ Code flip matching the Mac pill, set before the session spawns.                                                      |
| **iPhone session controls**  | The Plan / Code button in the session controls strip.                                                                         |
| **Watch**                    | The Plan / Code toggle in session detail.                                                                                     |

The pill uses a distinct glyph for each state plus a label — never color alone. On a provider with no Plan pole, the pill is omitted entirely rather than shown in a state it can't honor.

<Note>
  The composer has no Local/Worktree picker — that choice belongs to the [new-session composer](/docs/features/sessions), and a running session shows a read-only worktree badge. Don't confuse that badge with the Plan / Code pill; they're separate controls sitting on different rows.
</Note>

## How it maps to each provider

"Plan mode" means something slightly different depending on whether the provider runs as Claude's direct PTY or through a managed harness.

| Provider                                 | Plan-mode behavior                                                                                                                                                                                        |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Claude** (direct PTY)                  | Native plan mode. Continuum spawns the CLI with `--permission-mode plan`. When Claude emits its `ExitPlanMode` tool call, the session flips to a **plan-pending** state and the plan surfaces for review. |
| **Codex** (app-server harness)           | Plan keeps the harness in an approval-prompting policy: the agent proposes work and surfaces inline permission prompts you approve or deny. Code skips them.                                              |
| **Gemini / Antigravity** (harness)       | Same harness model — Plan keeps approvals on, Code skips them.                                                                                                                                            |
| **Grok** (ACP harness)                   | Same harness model.                                                                                                                                                                                       |
| **OpenCode Go, OpenRouter, Z.ai Coding** | Real Plan pole, driven through the OpenCode connector.                                                                                                                                                    |
| **Cursor**                               | **No plan mode at all.** Cursor sessions get no pill and are normalized to Code at every session boundary — a Cursor session always runs with maximum permissions.                                        |

<Info>
  Cursor is the only exception, and Continuum defines plan support as literally "every provider except Cursor." The daemon's approval-policy resolution and the client's pill both read that one definition, so they can never disagree about whether a session has a Plan pole — and you can never be shown a Plan pill that spawns a Code session.
</Info>

<Warning>
  Earlier builds mapped Cursor's Plan pole to the agent's read-only-ish "ask" floor. That's no longer how it works — there is no Plan pole to map. If you need a read-only exploration pass on a Cursor-heavy repo, run it on a provider that has one.
</Warning>

### Claude: the Approve & Run path

Claude is the provider with a discrete plan-then-approve handshake:

<Steps>
  <Step title="Send with the pill on Plan">
    Continuum spawns Claude with `--permission-mode plan`.
  </Step>

  <Step title="Claude works read-only">
    When it's ready it calls `ExitPlanMode`. Continuum watches the session's JSONL for that call, flips the session to plan-pending, and captures the plan text.
  </Step>

  <Step title="Review the plan">
    The plan renders inline in the transcript as a **read-only** card — headings, bold lead-ins, inline code, and lists intact, with an estimated tool-call count and cost in its header. The card carries no buttons; see [Where you approve](#where-you-approve).
  </Step>

  <Step title="Approve">
    The daemon suspends the plan-mode runtime and respawns Claude in the **same working directory** with no plan flag and write access restored, then marks the plan approved.
  </Step>
</Steps>

### Harness providers: permission prompts, plus a live approve

For Codex, Gemini, Grok, and the OpenCode-connector providers, work flows through the harness rather than a Claude-style plan card. When the runtime requests permission — an edit, a command, a plan update — Continuum renders an inline **permission prompt** carrying the agent's own options; you approve or deny it. The Plan ↔ Code pill governs whether those prompts appear at all:

* **Plan** → approvals stay on (the agent asks before acting).
* **Code** → approvals are skipped (maximum permissions).

Cursor is the exception again: with no Plan pole it always runs as Code, so its approvals are always skipped and you won't see these prompts.

A harness session's live plan updates still render as a plan summary in the transcript, so you can read the proposed steps before approving any of its prompts.

**Approve works on harness sessions too.** When the agent is blocked on its own `ExitPlanMode` request, approving answers that request in place with a code-capable mode — the turn keeps its momentum instead of being killed and respawned. Only when there's no live pending approval (a plan captured before the bridge came up, say) does Continuum fall back to reconfiguring the harness, carrying the transcript across. Either way the session lands on Code and the composer pill agrees.

<Warning>
  The older "Codex seeds a synthetic plan and Approve respawns it with `workspace-write`" flow is retired, and so is the era when approving worked only for Claude. A **retired** runtime — a legacy pane-backed or chat-SDK session — still answers with "legacy session retired", but a live harness session of any provider approves normally.
</Warning>

## The plan tracker

The **Plan** tab in the Mac review pane and on iPhone shows a step timeline. Steps are derived from the plan text by a heuristic shared between both platforms — numbered or "Step"-prefixed lines become individual rows. Tap any step to toggle its completion manually; your explicit choice wins over the heuristic, so a later auto-update can't silently flip it back.

On iPhone, the Plan tab appears when the session has a plan to show: any Codex session, an Antigravity session on a host that supports it, a session carrying plan text, a session with an approved plan, or one currently in the planning state.

## Where you approve

The transcript is for reading; the **actions live in the composer**. When a session goes plan-pending, the Mac composer raises a plan tray directly above the input field carrying two buttons:

* **Approve & run** — approve and let the agent write.
* **Comment** (`⌘⇧Return`) — keep planning. It moves focus to the composer so you can type feedback instead of approving.

The inline plan card in the transcript is deliberately read-only, so there is never a second, competing set of buttons scrolled somewhere up the thread. Sending an ordinary message while a plan is pending is rejected with *"Use Approve & run, or Comment to keep planning"* rather than being silently swallowed.

The review pane's **Plan** tab mirrors the same **Approve & run**, for when you're reading the plan there rather than in the thread. Both routes hit one shared approval path, so they cannot disagree.

Elsewhere:

* **iPhone** — **Approve & run** in the Plan tab. The tap routes through the mobile command outbox, so an offline approval queues and retries rather than failing.
* **Watch** — **Approve plan** in session detail, which relays the approval to the paired iPhone.

<Note>
  Watch approval is **off by default**. Turn on "Approve plans" under the Watch section of iPhone Settings; "Interrupt sessions" is a separate switch, and enabling one never enables the other. Continuum only honors a Watch command for a session actually in that state, and rejects a forged or stale one.
</Note>

Every approval — Claude or harness — is recorded in the audit log alongside the session id, the agent, and the peer that sent it.

## Refining before approving

Press **Comment** (`⌘⇧Return`) instead of approving and tell the agent what's wrong with the plan. It revises and presents an updated proposal; the inline card reflects the latest version. Iterate as many times as you like before approving — a plan you never approve never writes anything.

## Changing Plan / Code mid-session

The pill works mid-session. Flipping it issues a mode change:

* **Claude** respawns its direct PTY in the new mode.
* **Harness providers** reconfigure their bridge in place — the managed harness is restarted with the new approval policy.

Mode swaps are rate-limited to **one per five seconds per session** and recorded in the audit log. The limit is defense-in-depth against a misbehaving client, not something normal use runs into.

## Related

* [Sessions](/docs/features/sessions) — spawn options, providers, worktrees.
* [Autopilot](/docs/features/autopilot) — what the Code pole actually grants each provider.
* [Code](/docs/surfaces/code) — the Plan pane in the review panel.
* [Mobile](/docs/surfaces/mobile) — the Plan tab and Approve buttons on iPhone and Watch.
* [Providers](/docs/providers/overview) — how each provider's runtime is driven.