DSH plugin plan mode: pending choices and exits
"I turned plan mode on and nothing changed" usually means the choice is still waiting for the next pre-step, not that it failed. DSH plugin's plan mode stores state as a whole-value log event, but events can only land inside a turn. Understand that constraint and both pending and lost choices become explainable.
Plan mode is soft guidance, not enforcement
It affects prompts and restricts no tool.(source)
Plan mode is per-agent collaboration state owned by dsh-plan-mode and recorded in the log (ctx.planMode). While active, every model request includes a deployment-owned guidance section.
The framing matters: plan mode is soft guidance. Sandbox mode and approval policy enforce restrictions separately, and neither reads or writes plan state, so deployments must configure them independently.
The package is optional and the agent loop does not depend on it. It contributes the plan:policy prompt section and registers the exit_plan_mode tool plus the /plan command.
plan/mode is a log event, not transcript
It is durable and replayable, but the model never sees the event itself.(source)
plan/mode ({ active: boolean }) is a log-only, whole-value session event: durable and replayable, never in the model transcript.
The plan unit folds three things: the committed mode, command settlement results, and the mode recorded by the latest request header. ctx.planMode requires the registry to exist, awaits plan and turnBoundary registration during activation, and then reads state through the retained handle.
Clients receive only a trimmed { active, pending }, and restore, fork, and compaction all recover those two from the log. So restarts never lose state — only a not-yet-appended pending selection can be lost.
Pending selections and the pre-step append
Every session event sits inside a turn, so a choice must queue first.(source)
Because every session event lives inside a turn, a user choice stays pending until the next accepted in-turn pre-step appends it before deriving the request, whichever turn that pre-step belongs to.
A choice never forces continuation, so one made after a turn's last accepted pre-step is appended in a later turn.
set(agent, active) records the pending selection and does nothing when the target matches the recorded or already-waiting state. get(agent) returns { active, pending? }: the recorded state used to assemble the current step, and the selected state awaiting append.
The single append point is a prepended pre-step
Let downstream accept the step, then append — the order cannot reverse.(source)
At agent runtime the only append point is the prepended agent/pre-step listener. It observes every candidate request step, including turn 1 step 1 and request-recovery retries; it calls downstream listeners first and appends only after downstream accepts the step.
Prompt admission happens before a turn opens and cannot append plan/mode, so a choice made at the prompt is appended by the first accepted pre-step inside the turn it opens.
Two fault-tolerance rules: an append failure must not block the turn, and the choice keeps waiting for a later accepted in-turn pre-step.
Appending a user choice also records a plugin-sourced user/message notice, but only when the last recorded request header described a different state. The model is therefore notified exactly when context changes, and never twice.
Finally, the documented limit: a choice made after a turn's last accepted pre-step exists only in the process; if the process exits before another accepted in-turn pre-step, the choice is lost.
Config: section validated at load
Missing fields and unknown keys fail before runtime.(source)
PlanModeConfig has exactly one field, section. A missing, blank, or non-string section, plus any unknown key, fails at plugin load rather than being ignored.
While plan mode is active, the exact section text renders as the plan:policy system prompt section at order 50; inactive plan mode contributes no text.
That strict validation pays off directly: a bad config stops the plugin from starting instead of silently disabling plan mode in production.
The exit tool and the /plan command
Two exit paths differ in timing: one goes through review, the other through arguments.(source)
exit_plan_mode uses progressive disclosure: it is admitted from the step where the selected plan state first becomes active and stays admitted for the rest of the session. So the first entry puts it into the tool declarations, and later switches only change plan guidance. Native and PTC execution use the same admitted set; calling it before that first entry returns UNKNOWN_TOOL, and calling it before the plan state is committed fails.
Inside plan mode it requires a complete markdown plan beginning with a # heading and presents it for review through the user interaction seam:
- approval returns
{ approved: true }and records a silent pending exit, appended by the next accepted in-turn pre-step. Plan guidance therefore stays in effect for the rest of the assistant's current tool batch, while the tool result itself reports the transition. - "keep planning" is a failed call carrying user feedback, which the model uses to revise and resubmit.
- abandoning review returns
{ approved: false }and ends the current turn, leaving plan mode active until the user's next message. - a missing interaction channel or a service reload during review also fails the call instead of silently leaving plan mode.
/plan [off|message] is the command path: bare /plan selects plan mode; any other non-empty message first selects plan mode, then submits that text through agent.steer(), making it an ordinary recorded user message under plan guidance; the exact argument off selects inactive, which also cancels a pending entry before it is appended and becomes visible to the request.
Verification: enter, restart, exit
Cover pending state, recovery, and cancellation together.(source)
- Call
set(agent, true)between turns and assertcommittedwithplan/modeappended. - Call
set(agent, true)inside a turn and assertqueuedwith no new event yet. - Let the next pre-step be accepted and assert the event was appended and a non-duplicated notice appears in model context.
- Restart the process, call
get(agent), and assertactivematches the pre-restart value. - Call
exit_plan_modebefore the first entry into plan mode and assertUNKNOWN_TOOL. - Run
/plan offwhile a selection is pending and assert the pending entry is cancelled rather than appended and reverted.
If no event appears in step 3, check whether that pre-step was rejected downstream — rejected steps never trigger the append.
For the overall mechanism, see the plan mode subsystem; for exit ordering ahead of subagents, see plan mode exit timing.
One line to close: plan mode only changes prompts, state recovers from the log, a choice waits for an accepted pre-step, appending happens at one in-turn place, and exit goes through review or an argument.
FAQ
No. DSH plugin plan mode is soft guidance only. DSH plugin's sandbox mode and approval policy enforce restrictions separately, and neither reads or writes plan state.
No. DSH plugin's plan/mode is a log-only session event. DSH plugin keeps it durable and replayable but never puts it in the model transcript.
Yes. DSH plugin appends between turns immediately, because no in-turn pre-step would run until another prompt opens a new turn.
Yes, in one documented case. DSH plugin records that a choice made after a turn's last accepted pre-step lives only in the process and is lost if the process exits.
Related Terms
- plan/mode
- plan/mode is a log-only, whole-value session event carrying only an active boolean, durable and replayable.— packages/plan/plan-mode/src/index.ts
- PlanModeConfig
- PlanModeConfig is deployment-owned plan guidance config with a single section field, rendered as the plan:policy prompt section.— packages/plan/plan-mode/src/index.ts
- exit_plan_mode
- exit_plan_mode is the progressively disclosed exit tool, admitted from the step where plan state first becomes active and admitted thereafter.— packages/plan/plan-mode/src/index.ts
- pending selection
- A pending selection is a recorded but not yet appended plan mode choice waiting for the next accepted in-turn pre-step.— DeepSeek Harness reference - Plan mode
Sources
- DeepSeek Harness reference - Plan mode· deepseek-ai
- packages/plan/plan-mode/src/index.ts· deepseek-ai