Plan mode

A session is in one of two modes. Build is the normal one: the agent reads, runs commands, and proposes edits you approve on a diff. Plan is the same session with one promise added — nothing it does can change the repository.

Press Tab to switch. The composer changes colour and the caret follows it, so you can see which mode you are in without checking anywhere else.

Use it when you want the answer before the change: how would you restructure this?, what breaks if I rename that?, where does this get called from? The agent looks around properly — reads files, greps, runs the test suite — and replies with a proposal in prose instead of starting work.

What still runs#

Reading is untouched. So is the terminal, which is the part people expect to be switched off:

The terminal has to stay: inspection is most of what planning is, and a mode that cannot run bun test cannot tell you whether the thing you are asking about currently works.

That is also why the refusal is judged on the command, not on the tool. A filtered tool list cannot see arguments, so run_terminal reaching the disk through a redirect is caught when the call is made rather than when the list is built.

What the agent is told#

A refused write comes back to the agent as a result, not an error, so the turn keeps going:

Not applied: edit_file was refused because this session is in plan mode.Nothing was written and the workspace is unchanged. Do not attempt another wayof writing it — every writing tool and any shell command that edits a file isrefused while planning, including redirects and sed -i. Finish investigatingand reply with the plan in prose: what you would change, in which files, andhow it would be verified.

It cannot report the change as applied, and it cannot route around the refusal, so it finishes the plan instead of losing the turn.

Leaving it#

Press Tab again. There is deliberately no tool for it — the mode belongs to the person at the keyboard, and an agent that could leave plan mode would not be much of a guarantee.

Switching mid-turn takes effect on the next turn. The mode is read once when a turn starts, so a turn already running finishes under the rules it began with rather than changing halfway.

Plan mode and approval modes#

They solve different halves of the same problem and both apply at once.

Approval modes decide what you get asked about. Plan mode decides what is possible at all. Even in full-auto, which asks about nothing, a planning session still writes nothing — the refusal happens before the approval question is ever reached.

See also#

• Approval modes — the other half of the control
• Keyboard — every binding, including Tab

Added in woopcode@0.7.0