platform/docs/chat-plan-mode.md

Plan mode in Officer's chat — plan of record

Agreed with the owner on 2026-08-17, immediately before a context compaction. Written so the build can start from here with nothing re-derived.

Status: not started. Nothing in this document has been implemented.

---

Why

claude-code/opusplan is in the model picker as of 57bbcca9, and on this install it almost certainly does nothing — it silently runs Sonnet.

opusplan is not orchestration. The CLI's own strings say what it is:

Plan mode: the opusplan upgrade model is not permitted by the org model restrictions
           (availableModels allowlist or model_access entitlement);
           planning uses the newest permitted Opus instead
Plan mode: … planning uses the resting model instead
opusplan-mode-reminder

An upgrade model (Opus) used while in plan mode, and a resting model (Sonnet) the rest of the time. One session, one context, one agent — the model changes with the MODE. That is a different mechanism from subagent delegation (the Task tool), which is what people usually assume opusplan means.

Plan mode is a permissionMode, and Officer hardcodes a different one:

• node_modules/@anthropic-ai/claude-agent-sdk/sdk.d.ts:963 — PermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan' | 'dontAsk'
• src/servers/sidecar/claude/claude-manager.ts:505 — permissionMode: 'bypassPermissions'

So Officer's chat never enters plan mode, and opusplan therefore rests forever. Making the mode reachable is what makes that picker entry honest — and it is the owner's main lever for spending fewer tokens on long tasks, which is why it is worth building rather than deleting the entry.

---

What already exists to build on

The control channel is proven. Query.setPermissionMode(mode) (sdk.d.ts:1103) is a control request on the live query, exactly like Query.setModel() — which Officer already calls in applyModelChange (claude-manager.ts, landed 4c24df93). Same constraint: streaming input mode only, which is the only mode this file uses. So switching mode mid-conversation needs no teardown, no resume, and the pattern to copy is twenty lines away.

The durable-event pattern is proven too. model:switched (4c24df93) is the worked example of a sidecar-originated event that reaches the client, is persisted, and renders as a marker in the transcript — ChatEvent → turn-stream.ts → TurnMessage → useChat → MessageBubble. A plan:* event follows the same five files.

---

The hard part: approving the plan

In plan mode the agent researches, then calls ExitPlanMode with its plan and waits for a decision. That decision is a PERMISSION decision, and bypassPermissions auto-approves everything — so naively setting the mode gives a planner that instantly approves its own plan and starts editing, which is worse than no plan mode at all.

The SDK's hook for this is canUseTool (sdk.d.ts:95, and an option at :590):

type CanUseTool = (toolName: string, input: Record<string, unknown>, options: {
  signal: AbortSignal;
  suggestions?: …;   // "always allow" style permission updates
}) => Promise<…>;

So the shape is: intercept ExitPlanMode, surface the plan to the user, and resolve the promise with allow or deny. That makes the plan a first-class thing in the transcript rather than a message that scrolls past.

Open question to settle first: does canUseTool fire at all under permissionMode: 'plan' when the session was created with bypassPermissions, and can the mode be changed by control request after createSession has already passed canUseTool (or not passed it)? canUseTool is a query() OPTION, read once at session creation — so it may have to be supplied unconditionally from the start, refusing nothing until plan mode is entered. Verify this before designing the UI, because it decides whether plan mode can be toggled on a live session or only chosen when a conversation starts.

---

Landmines

bypassPermissions is deliberate and must remain the default. CLAUDE.md: "Agents run unsandboxed as the server owner, with --dangerously-skip-permissions. This is deliberate — it is the owner's own machine. Do not add a jail without being asked." Plan mode is opt-in and temporary; on exit the session must return to bypassPermissions or every subsequent tool call starts prompting and the chat appears to hang.

Do not let a canUseTool promise hang forever. It gates the turn. A plan awaiting approval while the socket is closed must resolve (deny, or on a timeout) or the session wedges with isGenerating true — the same failure the stall timer exists to catch (claude-manager.ts, stallTimer).

Mode is per-session state and belongs with the model. session.model on PersistentSession was added for exactly this class of thing; a session.permissionMode beside it keeps applyModelChange's shape.

---

Sequence

1. Verify the canUseTool question above with a scratch script against a real claude — do not design the UI first. (Note: a scratch query() failed to reach supportedModels() from a nested Claude Code session earlier today; the sidecar itself is the reliable place to test.)
2. session.permissionMode on PersistentSession, plus applyPermissionModeChange mirroring applyModelChange — control request, effective-not-requested, durable event on success and on refusal.
3. plan:entered / plan:proposed / plan:exited durable events through the five files model:switched already travels.
4. Composer toggle, and a plan card in the transcript with Approve / Reject.
5. Return to bypassPermissions on approval, rejection, and turn end.

---

Also open, unrelated to this doc

• pm2 restart officer is outstanding: the tier-less-model fix (773f0e1c) and the sessions-list server changes are on disk but not running.
• Spend visibility vs enforcement — the owner is on a Max OAuth subscription, so the binding limit is Claude Code's usage window, not dollars; totalUSD on each result is a notional API-equivalent price. Officer accumulates cost per session in websocket.ts:302-304 in memory only, so it dies on restart and nothing aggregates it. Unanswered: is the goal visibility or enforcement, and do members share the owner's subscription?
• Listener agents — future work. They will be real chat sessions but on a separate route, with a marker in the database so they do not pollute the sessions list. chat_session_models is the precedent for a narrow table keyed by transcript uuid; a kind marker would follow it. No design yet.
• docs/chat-sessions-list.md — the sessions-list work, now largely built (d59bc0d1, 640a74bc, 773f0e1c, 5565867b). Its "Status: not started" header is stale.