title: Plan Mode tags: [plan, roadmap] library: cowboy status: partial

Plan Mode

Plan mode would have the agent maintain an explicit plan and gate its actions against that plan. Today the plan state exists and is tracked, but nothing drives or restricts the agent’s behavior from it. This page describes what is implemented and what is not.

What exists

A PlanState struct (crates/core/src/context/plan.rs) holds:

• objective: String
• open_tasks: Vec<PlanTask> — each task has content and a status of pending, in_progress, or completed
• blockers: Vec<String>
• next_step: String
• updated_at: String

The agent updates this state through the update_plan_state builtin tool (wire name __UPDATE_PLAN_STATE__). The handler (handle_update_plan_state in handlers.rs) replaces the supplied fields, normalizes the task list so at most one task is in_progress, stamps updated_at, and persists the result.

State is persisted per session to plan_state.json in the session directory (load_plan_state / save_plan_state) and reloaded on session resume.

When the plan is non-empty, it is rendered into a transient context packet that is injected into the LLM request (view/context_packet.rs), showing the objective, up to eight open tasks with their statuses, blockers, and the next step. This keeps a compact plan in front of the model without storing it in the conversation transcript.

What does not exist

There is no plan-mode loop and no execution gating. Specifically:

• The agent’s available tools are not restricted based on plan state.
• There is no read-only / planning phase that must complete before a write/execute phase.
• There is no approval workflow, no plan-vs-action diffing, and no automatic enforcement that actions match open_tasks or next_step.

In other words, the plan is recorded and surfaced to the model, but it is advisory: the model may ignore it, and nothing in the harness blocks or sequences actions according to it. update_plan_state is the only mechanism, and it is an ordinary tool the model chooses to call.

Possible direction

A full plan mode would add, on top of the existing state:

• A planning phase restricted to read-only tools, ending in an explicit plan.
• Gating that ties subsequent tool calls to approved tasks.
• An approval step before transitioning from planning to execution.

These require harness changes that have not been started. The persisted PlanState and the update_plan_state tool are the groundwork; the loop and enforcement are not yet built.