Plan mode

Plan mode splits thinking from doing. Once active, the expert only runs read-only research and maintains one plan document; you iterate on it in conversation and click Build when you’re satisfied. It isn’t an approval workflow — there’s no accept/reject button. You’re just chatting, except this turn it can’t touch anything.

When it’s worth it

Situation	Why
Multi-step work across modules	Discovering the wrong direction halfway costs far more than aligning first
Technology choices or architectural tradeoffs	Make it lay out alternatives instead of quietly picking one for you
Irreversible operations (migrations, bulk rewrites, publishing)	Risks and rollback need to be visible before anything runs
You’re unsure it understood the requirement	A plan document is the cheapest alignment medium there is

Conversely, don’t use it for “change one line of copy” or “add a button” — writing a plan first just spends an extra round of tokens on the same work.

How to use it

Activate

Turn on Plan mode in the ”+” menu next to the input box. A status indicator appears.It may also be proposed for you: in a normal conversation, when the expert judges that your request needs planning first, it shows a card suggesting plan mode — entering is your click, it cannot switch itself.

Describe the work

Ask normally. It researches with read-only tools (reading files, searching, querying knowledge bases) and then produces a plan.When the requirement is ambiguous, it asks via a question card with clickable options.

Review the plan card

The plan appears as a card in the conversation. The recommended structure has four sections:

Section	Contents
Current state	What exists today and what you asked for (2-4 sentences)
Approach	The chosen approach; each viable alternative gets one line saying why it lost
Risks	Each risk paired with a mitigation
Breakdown	Numbered steps, each naming the file touched and the concrete action

Target length is 200-800 words. Beyond 800 usually means over-design — split into phases rather than writing a longer plan.

Iterate

Just say what to change: “use a different approach in step 3”, “add a rollback plan”, “merge these two steps”. It revises the whole document and saves again.

“Update it”, “let’s go with this”, “change it to X” are all treated as feedback on the plan, not permission to execute. Executing requires clicking Build.

Build handoff

Clicking Build on the plan card turns plan mode off, sends the execution instruction as a normal message, and the expert starts working through the plan.If you say “go ahead and do it” while still in plan mode, it won’t act — it shows a confirmation card for you to click. Leaving plan mode is always your click. Ignore the card and it stays in plan mode without nagging you again.

Tool gating

In plan mode the tools are filtered out, not “present but refused”. The model never sees them, so it never tries.

Category	In plan mode
Reading files, search, knowledge base queries	✅ Available
Question cards (`Ask`)	✅ Available — planning is exactly where it should ask instead of guess
Writing and editing files	❌ Not visible
Running commands (`bash`)	❌ Not visible
Generating images, video, music	❌ Not visible
Deploying and publishing	❌ Not visible
Delegating to sub-experts	❌ Not visible
Writing the plan document (`plan_write`)	✅ The only write

plan_write is the only world-changing action available, and its write path is not a parameter — the system decides it and the model cannot steer where it writes. That constraint is what makes the whole mode hold: add a path parameter and plan mode degrades into an ordinary file-writing tool.

Where the plan lives

In the current session’s working directory, named <title>.plan.md (older sessions may have plan.md). You can see it in the workspace file panel.

Rule	Detail
One plan per conversation	It never forks a second one
The filename freezes at first write	Retitling mid-conversation doesn’t create a new file
Each write is a full overwrite	Not an incremental append

The plan document lives in the sandbox. In conversations with no sandbox, plan_write reports no_sandbox — tool gating still applies (it still can’t act), but the plan can’t persist. In that case it tells you persistence is unavailable and stops, rather than dumping the full plan into chat as a substitute.

Failure modes and troubleshooting

Symptom	Cause	What to do
It starts executing inside plan mode	Contract violation	Say so directly; normally the write tools aren’t even visible
You said “execute” and nothing happened	By design — it only shows a confirmation card	Click the card, or click Build
The plan card didn’t update; changes only described in chat	`plan_write` wasn’t called	Say “write the changes into the plan document”
Reports `no_sandbox`	This conversation has no cloud sandbox	Move to one that does, or accept a non-persisted plan
The plan keeps growing into thousands of words	Over-design	Ask it to split into phases, each under 800 words
Two plan files appear in the file panel	Filename probing failed on a write	Harmless; the next write converges on one of them
It proposes an approach without researching	Research step skipped	Say “read the relevant files first, then propose”

What a good plan looks like

## Current state
Payment callbacks are handled synchronously in one handler that does
signature verification, state machine transitions, and notification push.
Third-party retries cause duplicate notifications.

## Approach
Split into "verify + write idempotency key" and "async consume".
Alternative: a distributed lock around notifications — rejected, because
the lock only fixes notifications while duplicate state transitions remain.

## Risks
- A wrong idempotency-conflict verdict would swallow legitimate callbacks
  → log and alert on conflict, never drop silently
- Async failures become invisible to the third party
  → failed consumption goes to a dead-letter queue, alert after 30 minutes

## Breakdown
1. `payment/callback.ts`: after verification, insert into `payment_callback_log`
   with unique key `(provider, trade_no)`
2. On conflict return 200 immediately (stops third-party retries), skip the rest
3. Add `workers/payment-callback-consumer.ts` to consume unprocessed rows
4. Move state transitions and notification push from handler into the consumer
5. Add a test asserting three identical `trade_no` deliveries process once

The line worth noticing is the rejected alternative. One sentence on why it lost is more useful than listing three options for you to pick — you wanted its judgment, not the decision handed back.

Tool catalog

Every tool’s parameters and permission tier

Sandbox

The execution environment the plan document depends on

Workspace panels

Viewing the plan document in the file panel

Billing formulas

Planning turns are billed by tokens too

Get Started

Core Concepts

Guides

Platform & Account

Deep Dive

When it’s worth it

How to use it

Tool gating

Where the plan lives

Failure modes and troubleshooting

What a good plan looks like

Tool catalog

Sandbox

Workspace panels

Billing formulas

​When it’s worth it

​How to use it

​Tool gating

​Where the plan lives

​Failure modes and troubleshooting

​What a good plan looks like

​Related

Tool catalog

Sandbox

Workspace panels

Billing formulas

When it’s worth it

How to use it

Tool gating

Where the plan lives

Failure modes and troubleshooting

What a good plan looks like

Related