Plan mode
Research first, write second — with mutating tools hard-blocked by the runtime rather than discouraged by the prompt.
Why it exists
Asking a model not to edit files works most of the time, which is precisely the problem — “most of the time” is not a guarantee you can build a workflow on. Plan mode removes the option: while the agent is researching, every mutating tool returns a hard deny from the permission layer, regardless of your permission mode or allow rules.
The result is a research phase you can actually trust. The agent reads, greps, and explores, then hands you a plan — and cannot have quietly changed anything along the way.
The lifecycle
idle → researching → drafted → approved → executing → idle| Phase | What the agent can do |
|---|---|
researching | Read-only tools only — read, grep, glob, web_fetch, web_search, todo. Every mutating tool is denied. |
drafted | The plan is stored on the session, waiting on your approval or rejection. |
executing | Mutating tools are re-enabled, and the approved plan is added to the system prompt as a reference the agent works against. |
Because the plan stays in context during execution, the agent is measurably less likely to drift into unrelated work — it has a written commitment to check itself against.
Using it
Start a session in plan mode:
tachyon --planYou can also enter it mid-session when a request turns out bigger than expected. The agent researches, then presents numbered steps; approve to execute, or reject and redirect. A rejected plan costs you nothing but tokens — no files were touched.
When it pays off
Plan mode is worth the extra round trip when:
- The change spans several files and you want to see the shape before it lands.
- You are in an unfamiliar codebase and want the agent's map before its edits.
- The task is ambiguous enough that there are two reasonable approaches — reviewing a plan is much cheaper than reviewing a diff and discovering it took the wrong one.
It is overkill for a one-line fix. For anything you would ask a colleague to sketch before starting, it is the right default.