Plan Turns

Sometimes you want the model to think, not act: investigate a bug, propose an approach, explain a module. A plan turn gives the model a catalog with no write tools and no execution tools, so the answer is words, and nothing needs review.

heph --plan
heph exec --plan 'how would you add rate limiting to the API?'

Every turn of a --plan session starts as a plan turn. In the plan turn the model is told:

This is a plan turn. Your tool catalog has no write tools and no execution tools: read and reason, then answer the question, offer a plan concrete enough to approve, or ask a clarifying question. Do not attempt or announce an edit you cannot make.

Plan and design turns also receive shared scope instructions: general questions and examples do not request implementation or live inspection. A real session ID is context unless you explicitly ask to inspect that session. The model should answer from source and available read tools, not open live databases, run programs, or probe blocked tools.

When it would materially change the work, the model can use ask_user to clarify whether you want a general answer or a specific investigation using code-mode tools. That scope question is not a mode switch. Only an explicit request for work needing code-mode tools or writes outside the current mode should trigger request_code; heph still owns the confirmation.

Plan turns run on the design tier, the one whose role includes design, which by default is the same frontier model that codes. Give design a tier of its own to plan on another model. There is no rush and the answer is meant to be read.

Switching mode mid-session

Plan mode is a mode, not a fixed property of the session: in an interactive session you turn it on and off between turns.

/plan          enter plan mode (read-only turns), sticky until you leave
/plan local    enter plan mode with a named tool set
/plan how would you split auth?
               enter plan mode and send the prompt as its first turn
/plan --tools local where is Session built?
               the same, with a named tool set
/code          leave plan mode; turns run as they did before
/code --clear  leave it and start the model fresh, as /clear does

The status bar shows plan while the mode is on, and the switch is noted in the conversation. It is sticky until /code or an accepted mode-switch question. If you explicitly ask for work requiring code-mode tools, such as building or inspecting a live database, it calls request_code to pause for heph's own confirmation dialog. A call blocked by the mode also opens that dialog before it runs. No further model rounds or tool calls run while the question is open. Press y to switch to code mode and continue the same turn with its context, code tools, and routed model; the pending call still goes through normal permissions, including allowlists. Press n or Esc to keep the mode and stop the turn. Mode confirmation cannot be skipped by --yes or remembered tool approvals. This does not clear context or perform an --implement handoff. Non-interactive heph exec stops instead of switching.

The usual flow is to /plan, talk through an approach, then /code and say "do it" — the model keeps the whole conversation, now with the full catalog. /code returns to the class the session was started with (coding, or --review).

Switching also swaps the tier, so the model shown in the status bar can change: plan turns run on the design tier, coding turns on the coding tier.

Tool sets

A plan turn's catalog is a tool set: a named list of tools that only read. The default is research; --tools NAME picks another. Every plan catalog also includes request_code, the mode-switch signal:

heph --plan --tools local

You can define your own in [toolsets]; a set may name only tools that read, and heph refuses one that names edit or shell (Tool Sets).

What a plan turn is for

• Before a large change: "read the auth module and tell me how you would add refresh tokens; do not change anything yet." The next turn, without --plan, can say "do it".

• Understanding: "explain how requests flow from main to the handler."

• Deciding: "we could store this in SQLite or in a flat file; which, and why?" The model can read the codebase to answer and can ask_user if the answer turns on something only you know.

--review is a related flag: it keeps the full catalog but runs the turn on the review tier, for a turn that may edit but is mostly reading, such as a code review with fixes.

What it cannot do

A plan turn cannot leave you a file. If you want the plan written down as a design document, switch to a design turn: /design keeps the conversation and lets the model write under your [design] paths, and the document goes through review like any other change.