deepseek-harness/packages/plan/plan-mode

@deepseek-ai/dsh-plan-mode

Logged, per-agent plan collaboration state with deployment-owned guidance, a direct /plan [message] entry command, and the reviewed exit_plan_mode exit. Plan mode is soft guidance; sandbox mode and approval policy remain independent enforcement axes.

Durable state

plan/mode ({ active: boolean }) is a log-only, whole-value-replace SessionEventMap member. foldPlanMode(events) returns the last logged value or false, so resume, fork, and compaction recover plan state directly from the session log. UIs observe committed flips through session/event.

ctx.planMode.set(agent, active) records a pending selection and flushes it inside the next turn boundary. get(agent) returns { active, pending? }, separating the logged state shaping the current step from a user's optimistic selection. Prompt submission, ordinary continuation, and request-recovery retry are all covered; a changed user selection contributes one context/message notice when the last logged request header described the other state.

Model and human surfaces

While active, plan:policy renders the configured section. The plugin always registers exit_plan_mode, keeping tool schemas stable across the transition; its execute path accepts only active plan mode and leaves it only after an exact user approval through ctx.userInteraction.

When ctx.commands is composed, the package registers /plan [message]. The command selects plan mode first. A non-empty argument is then submitted through agent.steer(), so it becomes the next step's ordinary logged user message under plan guidance; bare /plan only changes state.

ACP is an adapter, not the owner of this vocabulary: it advertises the fixed wire ids default and plan, maps session/set_mode to the boolean service, and translates committed plan/mode events back to current_mode_update.

Configuration

- id: plan-mode
  name: '@deepseek-ai/dsh-plan-mode'
  config:
    section: |
      You are in plan mode. Explore and design before presenting the complete
      plan through exit_plan_mode.

section is required and non-empty. Unknown keys fail at load. The package does not accept arbitrary named modes, tool filters, sandbox settings, or approval policy.

Design: plan-mode Agent Note and plan-specific state simplification.

Model Experience

Plan policy system prompt

What the model sees

While plan mode is active, the model sees the deployment's exact section text at prompt order 50; inactive mode contributes no text.

Configuration example

You are in plan mode. Explore and design before presenting the complete plan through exit_plan_mode.

Token effect

Inactive mode adds no tokens; active mode adds the configured section to every request.

KV Cache effect

The section is stable within plan mode, but entering or leaving changes the system prompt from order 50 onward.

Optional command message

What the model sees

/plan and its terminal result stay outside model history; a non-empty suffix becomes one trimmed user text block through agent.steer() after plan mode is selected.

Token effect

The suffix costs the same history tokens as submitting that text separately; a bare command adds none.

KV Cache effect

The user block is append-only conversation growth, while entering plan mode also changes the earlier policy section.

Exit tool schema and review exchange

What the model sees

The exit_plan_mode schema remains available in both states; execution outside plan mode fails, while an approved in-mode review returns the canonical { approved: true } value and renders the existing confirmation text. Rejection remains a failed call carrying review feedback.

Token effect

The stable schema is paid according to ToolRegistry mode, and each plan argument and review result remains in conversation history.

KV Cache effect

Mode transitions do not change the tool catalog; plan arguments and review results extend the conversation normally.

Known Limitations and Deferred Work

• Plan mode guides rather than enforces; deployments needing a hard boundary must combine independent sandbox and approval controls.
• A pending selection made while idle is lost if the process exits before the next boundary, so the UI must reapply it.
• Forked agents inherit logged plan state, while newly spawned agents begin inactive; there is no creation-time plan option.