Skip to content

Plan Mode#

What it is#

"Plan mode" denotes a family of mechanisms by which a coding harness lets the model (or the user) separate deciding what to do from doing it: the session is temporarily restricted to read-only exploration and the production of a plan artifact, and mutating operations (file writes, edits, shell execution) are withheld or deferred until an explicit approval step lets the harness proceed. The motivating failure mode is the same across every implementation: an agent that starts editing files before it has correctly understood the task produces a worse diff than one that scopes the change first and gets a human's sign-off on the scope, not just each individual edit.

Plan mode sits upstream of ordinary per-call permission prompting. Where per-call approval asks "may I run this specific mutating call," plan mode asks a coarser-grained question first: "am I even allowed to attempt mutating calls in this turn/session at all." The two compose — a session can exit plan mode into a turn that is then further gated by ordinary per-item policy — but they are conceptually and mechanically distinct systems.

Four incompatible implementation strategies recur: gate-before-write (a mode flag the model can flip, after which write tools are simply absent from its schema), restricted-tools (plan mode is nothing more than a smaller tool subset — no dedicated mode machinery at all), explicit-sign-off (a paired enter/exit tool pattern where exiting requires user approval of a concrete plan artifact, often a file), and staged-apply (every operation, not just writes, is deferred to an explicit later "apply" step — plan mode is really just the default state, and "normal" mode is the exception). No implementation combines more than one of these as its primary mechanism, and there is no standard for what a "plan" even is as a data structure — a markdown file, an in-context tool-call, or an accumulated diff, depending on implementation.

Common implementation patterns#

Naming and pairing conventions. The enter/exit pair is the dominant shape where a dedicated mode exists — some implementations expose both halves as distinct tools with parallel names; some implement only the exit/response half as a callable tool and treat entry as session/agent-level configuration rather than a model-invocable action.

What "the plan" restricts writes to. Some implementations narrow writes to markdown files only rather than disallowing them outright — the model can still produce the plan artifact itself while remaining unable to touch source files. A stricter variant fixes the writable target to a single named file rather than any markdown file. A coarser variant defines the mode purely as tool-set membership with no plan-artifact concept at all — no file the model is expected to produce, just a temporarily smaller toolbox.

What "exit" requires. Some exit tools require a named plan file and trigger a user-approval request before switching back to full tool access — approval tied to a concrete artifact. Others gate on user approval without requiring a named file. Some simply "end the planning turn and hand control back to the user" without a mandated parameter shape, making the hand-off closer to a signal than a review gate.

"Plan" as progress display vs. write gate — a real terminology collision. Some tools named around "plan" or "update_plan" are not write-gating mechanisms at all: they're checklist/progress-display tools (task tracking), used to show step-by-step progress to the user during ordinary execution, sometimes explicitly forbidden during a harness's separate planning/collaboration mode. This is worth distinguishing carefully — a keyword match on "plan" easily conflates the two.

Staged-apply as an alternative to a mode toggle. One design inverts the premise entirely: there is no "plan mode" to enter because every session is effectively in it. All file writes, moves, removals, and resets accumulate against a plan; nothing reaches disk until the user explicitly applies it. Shell commands are similarly staged rather than executed immediately. This achieves the same practical safety property as an explicit plan/apply boundary without any dedicated enter/exit tool call — the "gate" is the apply command itself, run entirely outside the model's control.

Permission, sandbox & safety#

Plan mode is best understood as a scope-level control layered above ordinary per-call approval, not a competitor to it. It answers a different question than per-call approval: rather than "should this specific mutating call run," it asks "should the model be able to attempt mutating calls in this turn at all."

The strongest safety property is schema-level removal, not runtime interception: marking write/edit tools as excluded means the tools are absent from what the model is even told it can call — there is no attempted call to deny, no wasted turn, no risk of a race between "model attempts write" and "harness blocks it." Narrowing writes to markdown-only, or to a single named file, are weaker variants of the same idea: the tool exists but its allowed target set is constrained, so enforcement still happens before invocation rather than after.

By contrast, the enter/exit-tool pattern still depends on the harness's ordinary approval layer to make plan mode's restriction meaningful — the mode flag is what determines which tools are offered to the model in the first place, and the exit tool is itself gated by user approval, echoing the "ask" tier of ordinary per-call approval rather than replacing it. A staged-apply model delivers the strongest end-to-end guarantee of the four patterns, because nothing at all executes — not reads, not shell, not writes — until the explicit apply step.

Plan mode is not typically described as interacting with OS-level sandboxing — sandboxing and plan mode are orthogonal layers in any implementation that has both (a shell tool stays sandboxed regardless of mode; plan mode's restriction is at the tool-schema level, upstream of whatever the shell tool's sandbox does once invoked). The risk plan mode mitigates is specifically "irreversible action taken on a misunderstood task," not "malicious or runaway command" — the latter is sandboxing's and per-call approval's job, and the two failure modes are independent enough that a harness needs both, not either.

Design considerations#

Every implementation with a dedicated plan-mode mechanism agrees on the shape of the underlying problem — restrict the model to read/explore-only operations for some phase of the session, and require an explicit hand-off (whether a user click, a tool call, or a shell command) to leave that phase. All four patterns also agree that the restriction should happen at the point tools are offered to the model rather than caught after the fact when the model tries to misuse them — even the "just a smaller tool list" and "just don't execute yet" variants share this property, differing only in how coarse or fine the restriction is.

There is no standard for the mechanism itself — each implementation invents its own primitive, and the four approaches (gate-before-write, restricted-tools, explicit-sign-off, staged-apply) are genuinely incompatible: a restricted-tools design has no analog for file-scoped write narrowing, and a staged-apply design has no analog for an explicit enter/exit tool pair at all, because in that model there was never a "normal" mode to leave. The field also splits on whether a plan is a concept at all — some produce no artifact, while others center on one. Plan mode remains a differentiator many implementations have independently reinvented, not a consolidating standard.

Implications for PluggableHarness Agent#

Plan mode is not a tool-provider operation in PluggableHarness Agent's architecture — it does not appear in, and should not be forced into, the tool reference catalog. It is a kernel turn-loop mechanism, specified in agent-loop/plan-apply-gate.md, which already resolves the central cross-implementation divergence in this design's favor of one specific pattern: plan mode MUST be implemented by removing resource tool specs from the request sent to the model at the pre-model-call step, not by intercepting calls at runtime after the model has already attempted one. This is precisely the "schema-level removal" pattern above, for the identical reason — no attempted call, no wasted turn, no denial round-trip. PluggableHarness Agent's design has effectively already picked a side in the field's four-way split, landing closest to the restricted-tools approach mechanically (tool removal from the request), while still supporting an enter/exit experience at the frontend layer — a session or turn can flip into "data_source-only" scope on plan-ready/policy grounds, functionally reproducing an explicit mode toggle without needing a bespoke enter/exit tool provider to do it.

Two points of evidence bear on PluggableHarness Agent's design as currently specified, both confirming rather than complicating it:

  • The kind = interactive precheck generalizes past what any single implementation above does — none distinguish an ask_user-shaped call from other read-only operations when restricting to plan mode. PluggableHarness Agent's data_source-only framing already covers this correctly since interactive and data_source share the same "no apply step to gate" property, so a plan-mode turn that excludes resource specs naturally still permits ask_user — matching the spirit of every enter/exit-pattern implementation, which all retain some form of user-facing question capability inside plan mode even where their own tool taxonomy doesn't call it out separately.
  • Progress-checklist tools named around "plan" are a genuine naming collision worth flagging: those tools are progress-tracking mechanisms (task tracking, not gating) and have no bearing on PluggableHarness Agent's plan/apply gate design at all — they map instead to the task provider category (task_create/task_update/task_list), not to plan mode. This distinction is worth preserving in any future design work that touches plan mode specifically, since a keyword match on "plan" easily conflates the two.

No open question in the agent-loop conformance notes concerns plan mode directly — the mechanism question (schema-removal over runtime interception) reads as already resolved, not as a live design gap.