DSH plugin plan mode: plan/mode, pending and exit_plan_mode

DSH plugin plan mode is not a permission switch; it is a per-agent collaboration state written to the log. While active it does one thing: adds a deployment-owned plan:policy section to every model request. Real restrictions come from sandbox and approval, neither of which reads plan state. That boundary explains two behaviors that look like bugs: the current turn does not change right after toggling (the selection waits for the next accepted in-turn pre-step), and exit_plan_mode stays in the tool catalog when inactive (so entering and leaving only change the prompt section).

DSH plugin plan state: the plan/mode event and replay

Bottom line: the mode is a whole-value log event, persisted and replayable, and never part of the model transcript.

1. Payload: plan/mode is { active: boolean }, whole-value replaced.
2. Replay: resume, fork and compaction all restore logged state and pending selections from the log.
3. Fold unit: the optional plan unit folds committed mode, command settlements and the last request-header-recorded mode.
4. Read entry: ctx.planMode exposes stateOf(); a missing registry, plan key or turnBoundary key fails on first access.
5. Client view: only { active, pending }, no internal folding details.

DSH plugin pending selections: why toggles are not immediate

Bottom line: every session event lies within a turn, so a selection must wait for an accepted in-turn pre-step before the request is derived.

1. Pending rule: a user selection stays pending until the next accepted in-turn pre-step appends it, regardless of which turn that pre-step belongs to.
2. No forced continuation: a selection does not make the agent continue, so one made after a turn's last accepted pre-step is appended in a later turn.
3. set outcomes: committed (logged now), queued (awaiting append), cancelled (an opposite pending selection was cleared) or noop.
4. get semantics: logged state plus an optional pending state; assembling the current step uses the logged one.
5. Known limitation: a selection made after the turn's last pre-step exists only in-process and is lost if the process exits first.

DSH plugin append point: agent/pre-step and the one-time notice

Bottom line: the only append point is a prepend-registered pre-step listener, and append failure must not block the turn.

1. Observation scope: every candidate request step, including turn 1 step 1 and request resume retries.
2. Decision order: call downstream listeners first, appending only after they accept the step.
3. Prompt-stage limit: prompt admission happens before the turn opens, so a selection there is applied by the first accepted pre-step of the turn it opens.
4. Failure handling: append failures must not block the turn; the selection keeps waiting.
5. Model notification: appending records a plugin-origin user/message only when the last request header described a different state, so the model is notified exactly when context changes and never twice.

DSH plugin config and exit: section and exit_plan_mode

Bottom line: guidance text is deployment-owned and validated at load; the exit tool is always registered but only executes in plan mode.

1. Config shape: PlanModeConfig { section: string }; missing, blank, non-string or unknown keys fail at load.
2. Rendering: while active, the exact section renders as plan:policy at order 50; inactive contributes nothing.
3. Exit tool: exit_plan_mode stays registered outside plan mode and fails there; inside plan mode it requires a complete markdown plan starting with #.
4. Review flow: submitted through the user-questions seam; approval returns { approved: true } and records a silent pending exit.
5. Continue planning: a failed call carrying feedback, so the model revises and resubmits; a missing interaction channel or a service reload also fails the call rather than silently leaving.
6. /plan: bare /plan selects plan mode, /plan off selects inactive and cancels a not-yet-visible pending entry, and /plan <message> selects the mode then submits the text through steer as a normal logged user message.

DSH plugin plan mode versus sandbox and approval

Bottom line: plan mode governs how the agent talks, sandbox and approval govern what it may do — none reads the others' state.

1. Plan mode: soft guidance affecting only the prompt.
2. Sandbox mode: enforces process and file constraints without reading plan state.
3. Approval policy: decides whether an operation needs approval, also without plan state.
4. Configure them separately: to make planning genuinely more conservative, tighten sandbox and approval too.
5. Rule of thumb: if files still change in plan mode, the sandbox or approval is unconfigured — plan mode never enforced that.

DSH plugin plan mode troubleshooting

Bottom line: separate not applied, not exited and lost state.

1. Toggled but unchanged — normal; wait for an accepted in-turn pre-step and check whether set returned queued.
2. Still running after a plan is submitted — approval is a pending exit; the rest of the batch still follows plan guidance.
3. State lost — the selection happened after the last pre-step and the process exited, a known limitation.
4. No plan:policy — check the section config and whether the mode is actually active.
5. Expecting tool restrictions — plan mode does not restrict; check sandbox and approval.
6. Repair status, stated honestly: event shape, pending rules, append point and exit flow follow the official Plan mode page and package README; confirm signatures and command behavior against its Cordis API and your version.

Sources: Plan mode, dsh-plan-mode README, System prompt.