📋 Umbrella tracker: #70101 — master tracker for the 9-PR plan-mode rollout. See it for status of all parts + suggested merge order + carry-forward backlog.

📋 Stack position: This is [Plan Mode 4/6], the fourth part of a 6-PR per-part decomposition of the original umbrella #68939 (closed).

• Previous in stack: [Plan Mode 3/6] Advanced plan interactions
• Next in stack: [Plan Mode 5/6] Text channels + Telegram
• Integration bundle: [Plan Mode FULL] — green-CI bundle of all parts + automation + executing-state lifecycle

⚠️ CI on this PR will be RED: this part adds UI components that reference plan-mode types (PlanModeSessionState, PlanStep) from [Plan Mode 1/6] + [Plan Mode 2/6]. CI will pass once earlier parts merge in order, OR review the green-CI integrated state in [Plan Mode FULL].

Ways to land this feature (maintainer choice):

• Per-part review + sequential merge of 1/6 → 6/6
• Single bundle merge via [Plan Mode FULL]

Executive summary

This PR ships the web UI surface of plan mode: the visual layer a webchat user actually touches when a session enters plan mode. It adds (a) plan cards that render the agent's proposed checklist inline in the message thread with per-step status, (b) a mode-switcher chip in the chat input toolbar that lets users toggle plan-vs-normal (and the PR-10 "Plan ⚡" auto-approve variant) with both pointer and keyboard, (c) an inline plan-approval card above the chat input — Accept / Accept-allow-edits / Revise — that doubles as the surface for AskUserQuestion interactions, and (d) plan-resume wiring that sends a hidden chat.send after a web-side approval/answer lands so the agent run continues without echoing a synthetic "continue" into the visible transcript.

Integration with the rest of the stack is intentionally narrow. The UI is a pure consumer of state shapes from 2/6 (planMode, planApproval, pendingAgentInjections) and tool contracts from 3/6 (AskUserQuestion, exit_plan_mode). The chip writes via sessions.patch; the approval card writes via sessions.patch { planApproval: { action } }; resume sends chat.send { deliver: false } so the runtime can pick up the persisted decision/answer without the user seeing an extra message bubble. Nothing in this PR adds new RPCs or new state — it surfaces what 2/6 + 3/6 already manage.

The four core component files (plan-cards.ts, mode-switcher.ts, plan-resume.ts, plan-approval-inline.ts) total 873 LoC, with 1067 LoC of tests against them. The remaining ~4.7k lines of the diff is integration glue in views/chat.ts (host wiring), app-tool-stream.ts (event-stream side detection of plan-related tool events), app.ts / app-chat.ts / app-render.ts / app-view-state.ts (top-level app state machine extensions for the approval-card local state), CSS (plan-card visuals + chat-shell layout adjustments), the slash-command executor for /plan, and the i18n cleanup deletions described below. The components themselves are small, pure, and testable in isolation — by design.

TL;DR

• Scope: 4 new UI components (plan-cards.ts, mode-switcher.ts, plan-resume.ts, plan-approval-inline.ts) + their CSS + their tests; integration into views/chat.ts, app-chat.ts, app-render.ts, app-tool-stream.ts; plan-mode entries in tool-display.json; one new i18n key (planViewToggle) across 13 locales.
• i18n languages covered (13): en, de, es, fr, id, ja-JP, ko, pl, pt-BR, tr, uk, zh-CN, zh-TW. Plus the i18n cleanup deletions described below.
• Accessibility: :focus-visible outline on plan-card <summary> (Copilot review fix from feat(plan-mode): full rollout + iter-1/2/3 hardening (consolidates PRs A/B/C/D/E/F/7/8/10/11) #68939, plan-cards.css:46-50), aria-haspopup="menu" + aria-expanded on the mode chip, role="region" + aria-label on the approval card, deliberate non-claim of role="menu" on the dropdown so the WAI-ARIA menu keyboard contract isn't falsely advertised (mode-switcher.ts:328-339).
• Keyboard: Ctrl+1..6 mode shortcuts with a Shadow-DOM-aware focus guard that walks .shadowRoot.activeElement so Lit composers' inner inputs don't have their keystrokes stolen (mode-switcher.ts:384-402).
• Offline-resilient: approval card disables every action button + surfaces a "Reconnect to resolve this plan. The approval stays pending while offline." banner when connected === false (plan-approval-inline.ts:98-102; test plan-approval-inline.test.ts:133-150).
• Tests: 4 component test files (1067 LoC of tests for ~873 LoC of components — ~1.2× coverage by line count); all jsdom-rendered and assert real DOM state, not snapshot strings.

Web UI component tree

How the new pieces slot into the existing webchat layout. Bold = added by this PR; everything else is the existing chat shell from views/chat.ts.

graph TD
  Root["chat view (views/chat.ts)"]
  Root --> Header["chat header"]
  Root --> Thread["message thread"]
  Root --> Composer["composer area"]
  Root --> Sidebar["right sidebar"]

  Header --> ModeChip["<b>mode-switcher chip</b><br/>(mode-switcher.ts)"]
  ModeChip --> ModeMenu["<b>mode menu popover</b><br/>Default / Ask / Accept /<br/>Plan / Plan ⚡ / Bypass"]

  Thread --> ToolCards["tool-cards (existing)"]
  Thread --> PlanCard["<b>plan-cards.ts</b><br/>&lt;details&gt;/&lt;summary&gt; with<br/>per-step status markers"]

  Composer --> ApprovalCard["<b>plan-approval-inline.ts</b><br/>shown ABOVE composer when<br/>planApprovalRequest != null"]
  ApprovalCard --> PlanVariant["plan variant:<br/>Accept / Accept-allow-edits / Revise"]
  ApprovalCard --> QuestionVariant["question variant (PR-10):<br/>1 button per option + Other…"]
  Composer --> Input["chat input (hidden when card open)"]

  Sidebar --> PlanPane["plan pane (formatted via<br/>formatPlanAsMarkdown())"]

  classDef new fill:#1e293b,stroke:#6366f1,stroke-width:2px,color:#e2e8f0
  class ModeChip,ModeMenu,PlanCard,ApprovalCard,PlanVariant,QuestionVariant new

Plan-resume on web reconnect

Why the resume primitive exists: when a web client approves a plan or answers a question, the authoritative decision lands in session state via sessions.patch (handled by 2/6). But the agent run that produced the approval request is paused. Something has to kick the run back into life without echoing a synthetic "continue" into the visible transcript or duplicating the decision the user already made.

sequenceDiagram
  participant U as User (web)
  participant W as Webchat client
  participant G as Gateway
  participant R as Runtime
  participant S as Session state

  U->>W: clicks "Accept" on approval card
  W->>G: sessions.patch { planApproval: { action: "approve" } }
  G->>S: persist decision in pendingAgentInjections
  G-->>W: 200 OK
  Note over W: card vanishes; composer<br/>re-enables
  W->>G: chat.send { message: "continue", deliver: false,<br/>idempotencyKey: "plan-resume-<uuid>" }
  Note right of W: hidden — does NOT post a<br/>visible "continue" bubble<br/>(plan-resume.ts:11-21)
  G->>R: dispatch run with persisted decision context
  R->>S: read pendingAgentInjections, drain
  R-->>W: streams agent output (now executing the approved plan)

The resume primitive is one function: resumePendingPlanInteraction(client, sessionKey) at ui/src/ui/chat/plan-resume.ts:11-21. Three things matter about its shape:

1. deliver: false — the gateway records the message in the session log but does NOT broadcast it to the channel as a user-visible bubble. Without this, every plan approval would inject a stray "continue" into the transcript.
2. idempotencyKey: "plan-resume-<uuid>" — the plan-resume- prefix is the load-bearing piece. Server-side correlation (in 2/6) treats any send carrying this prefix as a resume signal rather than a normal user message, which short-circuits the pendingAgentInjections drain logic.
3. Pure UI primitive — no decision logic lives here. The function is dumb: it fires the resume RPC. The decision-making (when to call it) belongs to the host views/chat.ts, which fires it after the sessions.patch for an approval/answer resolves.

The single test (plan-resume.node.test.ts:9-26) pins the contract: the call shape is chat.send { sessionKey, message: "continue", deliver: false, idempotencyKey: "plan-resume-uuid-fixed" }. If a future refactor changes the prefix, the runtime correlation breaks silently — this test is the canary.

Mode-switcher state

The chip has a small derived-state machine driven by three independent session fields: (execSecurity, execAsk, planMode, planAutoApprove). The derivation is centralised in resolveCurrentMode() at mode-switcher.ts:237-278.

stateDiagram-v2
  [*] --> Default: execSec=undef<br/>execAsk=undef<br/>planMode=undef
  Default --> Ask: pick "Ask" / Ctrl+2
  Default --> Accept: pick "Accept" / Ctrl+3
  Default --> Plan: pick "Plan" / Ctrl+4
  Default --> PlanAuto: pick "Plan ⚡" / Ctrl+5
  Default --> Bypass: pick "Bypass" / Ctrl+6

  Ask --> Plan: planMode→"plan"<br/>(perm-mode preserved)
  Accept --> Plan: planMode→"plan"
  Bypass --> Plan: planMode→"plan"

  Plan --> PlanAuto: pick "Plan ⚡"<br/>(planAutoApprove=true)
  PlanAuto --> Plan: pick plain "Plan"<br/>(autoApprove cleared)

  Plan --> Default: pick "Default" → planMode→"normal"<br/>+ clear execSec/execAsk overrides
  PlanAuto --> Default: pick "Default"

  Default --> Custom: server returns<br/>(execSec="deny", …) or other<br/>non-preset combo

  note right of Plan
    Plan WINS over permission mode
    in chip display — chip shows
    "Plan" regardless of underlying
    (execSec, execAsk).
  end note

  note right of Custom
    Synthetic mode for non-preset
    (execSec, execAsk) combos.
    Was: silently mislabeled as Ask
    (PR #67721 fix).
  end note

The state machine has three load-bearing rules:

• Plan wins over permission mode in display — when planMode === "plan", the chip shows "Plan" (or "Plan ⚡") regardless of the underlying (execSecurity, execAsk). Test: mode-switcher.test.ts:26-29.
• planAutoApprove is meaningful only when planMode === "plan" — pre-arming auto-approve while still in normal mode does NOT make the chip lie about being in plan mode. Test: mode-switcher.test.ts:49-55.
• Non-preset combos are synthesized as "Custom", not silently coerced to "Ask" (the prior bug from PR feat(ui): mode switcher + clickable plan cards + channel-aware plan delivery #67721). Sandbox-backed sessions commonly yield (execSecurity="deny", execAsk="off") which is a valid non-preset state, and showing "Ask" there would let the user accidentally loosen permissions. Test: mode-switcher.test.ts:77-86.

Note on i18n surface area (Codex P2 review)

In addition to the plan-mode UI work, this PR's diff includes mechanical cleanup of 12 locale files (ui/src/i18n/locales/*.ts + corresponding .i18n/*.meta.json) that delete unused auth/pairing/login/docs strings unrelated to plan mode. The pattern per locale file is:

• +1 line: the new planViewToggle: "Toggle plan view sidebar" plan-mode key (this is the actual plan-mode work)
• -30 lines: deletions of unused keys like passwordPlaceholder, showToken/hideToken/toggleTokenVisibility, scopeUpgradeTitle/scopeUpgradeSummary/roleUpgradeTitle, authDocsTitle/tailscaleDocsTitle/etc.

Codex review flagged the deletions as stylistically misplaced (they belong in a separate housekeeping PR). We considered surgically removing them but the i18n CI check (pnpm ui:i18n:check) requires the .meta.json totals/hashes to match the .ts content; mechanically reverting the deletions risks breaking the check without a regen step.

Maintainer call: the deletions are valid (those keys are genuinely unused — verified by absence of references in the UI source) but they're stylistically separate from plan-mode UI work. Two acceptable resolutions:

1. Accept as-is — net effect on main is identical to landing the plan-mode key separately. ~518 LoC of cleanup is a bonus side effect.
2. Pre-merge: revert the deletions on this branch (keep just the planViewToggle addition) and ship the deletions in a follow-up housekeeping PR after this rolls out. We'd need a pnpm ui:i18n:regen step (or its equivalent) to keep .meta.json consistent.

Tracking either decision in umbrella #70101.

How it wires into views/chat.ts

The four UI primitives are pure functions; the integration glue lives in ui/src/ui/views/chat.ts (already large; +371 net lines in this PR). The relevant block at chat.ts:1382-1456 is the contract worth eyeballing:

${props.planApprovalRequest &&
props.planApprovalRequest.sessionKey === activeSession?.key &&
props.onPlanApprovalDecision
  ? renderInlinePlanApproval({
      request: props.planApprovalRequest,
      connected: props.connected,
      busy: props.planApprovalBusy ?? false,
      // … 17 props total covering:
      //   - plan-variant: onApprove / onAcceptWithEdits / onReviseOpen / …
      //   - question-variant (PR-10): onAnswerOption
      //   - "Other…" textarea (PR-13 Bug 2): questionOtherOpen / Draft / handlers
      //   - sidebar handoff: onOpenPlan
      onReviseSubmit: () => {
        const draft = (props.planApprovalReviseDraft ?? "").trim();
        // Codex P2 review #68939 (2026-04-19): block empty client-side
        // submits — the wire schema's reject variant requires
        // feedback: minLength: 1, so empty would produce a confusing
        // server-side validation error. The textarea stays visible.
        if (!draft) return;
        void props.onPlanApprovalDecision!("reject", draft);
      },
      // …
    })
  : nothing}

<!-- PR-7 review fix (Copilot #3105170553 / #3105219639):
     hide the input only when BOTH planApprovalRequest AND
     onPlanApprovalDecision are present. Otherwise the user would see
     neither the card (which requires the handler) nor the input. -->
${props.planApprovalRequest && /* … */ props.onPlanApprovalDecision
  ? nothing
  : html`<div class="agent-chat__input">…composer…</div>`}

Three things to notice in that block, all of which are review-debt receipts rather than fresh design choices:

1. sessionKey === activeSession?.key gate — the same planApprovalRequest could (in theory) belong to a session the user has navigated away from. The card only renders for the active session; this prevents an approval from leaking across session contexts.
2. Empty-revise client-side block — the wire schema's reject variant requires feedback: minLength: 1 (closes the "reject with no guidance" loophole from earlier iters of plan mode). The host short-circuits the submit so the user sees the textarea remain in place to type into, instead of a confusing server-side validation error toast.
3. Both-or-neither input visibility — the original implementation hid the input whenever a planApprovalRequest was present. Copilot review #3105170553 / #3105219639 flagged that if the host forgets to wire onPlanApprovalDecision, the user gets neither the card (which checks the handler) nor the input. The fixed predicate gates on BOTH being present.

The mode-switcher integration is similarly defensive at chat.ts:1503:

return renderModeSwitcher({
  currentMode: resolveCurrentMode(
    activeSession?.execSecurity,
    activeSession?.execAsk,
    activeSession?.planMode,
    activeSession?.planAutoApprove,
  ),
  menuOpen: props.modeMenuOpen,
  onToggleMenu: props.onToggleModeMenu,
  onSelectMode: props.onSelectMode,
});

— derivation runs every render, so the chip stays in sync with whatever sessions.patch events the gateway streams down.

Per-file deep dive

ui/src/ui/chat/plan-cards.ts (122 LoC)

Inline plan rendering for the message thread. Two exports: renderPlanCard(plan) and formatPlanAsMarkdown(plan).

Shape — PlanCardData = { title, explanation?, steps: PlanCardStep[], source? }; PlanCardStep = { text, status: "pending"|"in_progress"|"completed"|"cancelled", activeForm? }. Status-marker glyphs at plan-cards.ts:23-28 are deliberately monospaced-friendly (⬚ ⏳ ✅ ❌) so terminal-style operators reading raw markdown via the sidebar's "Copy as markdown" still get a parseable checklist.

Markdown formatter — formatPlanAsMarkdown() at plan-cards.ts:101-122 renders for the right-sidebar pane and clipboard export. Cancelled steps render ~~strikethrough~~ (cancelled); in-progress steps render **bold** (in progress) and use activeForm (the ongoing-tense label, e.g. "Building artifacts") instead of text ("Build artifacts"). All step text passes through a single newline-stripping clean() so multi-line text from the agent doesn't break the bullet structure.

<details>/<summary> rendering — the summary shows <plan-icon> <title> <N/M done | N steps> <chevron>. Native ::-webkit-details-marker and Firefox's ::marker are both suppressed (plan-cards.css:25-33) so the custom chevron isn't doubled. Focus-visible outline on the summary at plan-cards.css:46-50 (Copilot review fix from umbrella #68939).

Test coverage — plan-cards.test.ts (159 LoC). Splits into a formatPlanAsMarkdown group (markdown-shape assertions including the activeForm-shadowing edge case at line 47-51) and a renderPlanCard (jsdom render) group that asserts real DOM structure: <details> exists, summary text contains "1/2 done" or "2 steps" depending on completion state, one <li> per step with the right status class, activeForm shadows text in in-progress rows.

ui/src/ui/chat/mode-switcher.ts (424 LoC)

The chip + dropdown menu in the chat input toolbar. Three exports drive the host: MODE_DEFINITIONS (the catalog), resolveCurrentMode(execSecurity, execAsk, planMode, planAutoApprove) (state derivation), renderModeSwitcher(...) (Lit template), handleModeShortcut(e) (Ctrl+1..6 dispatcher).

Mode catalog — MODE_DEFINITIONS at mode-switcher.ts:121-192 carries six entries: Default (Ctrl+1), Ask (Ctrl+2), Accept (Ctrl+3), Plan (Ctrl+4), Plan ⚡ (Ctrl+5), Bypass (Ctrl+6). The Default entry has both execSecurity and execAsk undefined — the host treats undefined as "DELETE the per-session overrides via patch", so picking Default returns the session to whatever the operator configured at agents.defaults. Without this, the post-plan-mode fallback would lock back to Ask, which most operator configs don't want.

Plan as a dimension, not a permutation — the file-level header comment (mode-switcher.ts:1-16) explains why planMode is NOT mapped onto execSecurity: plan mode needs read-only exec for research, so blocking exec via execSecurity=allowlist would defeat its purpose. Plan mode + permission mode coexist, and resolveCurrentMode lets plan WIN for display purposes only.

Shadow-DOM-aware focus guard — getDeepActiveElement() at mode-switcher.ts:384-402 walks document.activeElement.shadowRoot.activeElement recursively (capped at depth 32) until it bottoms out at the real focus target. Without this, focus inside a <openclaw-chat-composer> Web Component's internal <input> returns the host element, the focus guard fails to bail, and Ctrl+1..6 steal keystrokes the user meant for typing. Two regression tests cover depth-1 (mode-switcher.test.ts:249-270) and depth-2 (mode-switcher.test.ts:272-290) Shadow DOM nesting.

Deliberate non-claim of role="menu" — mode-switcher.ts:328-339 explains why the dropdown does NOT declare role="menu": claiming the menu role without implementing arrow-nav, Home/End, roving tabindex, and focus trap would mislead assistive tech (per WAI-ARIA spec). Plain <button>s give native focus + Escape-on-chip, which is a real usable interaction with no false ARIA promise. Test asserting the role is absent: mode-switcher.test.ts:331-334.

Test coverage — mode-switcher.test.ts (388 LoC). Four describe blocks: resolveCurrentMode (10 cases including the PR-10 plan-auto interaction, the PR-8 Default/undefined handling, the sandbox deny regression), handleModeShortcut (8 cases for the modifier-exclusion matrix — Ctrl alone OK, Cmd/Shift/Alt all bail), focus guard (5 cases with the Shadow-DOM regression coverage), renderModeSwitcher (jsdom render) (5 DOM-shape cases).

ui/src/ui/chat/plan-resume.ts (21 LoC)

Single function, single test. Covered above in the "Plan-resume on web reconnect" section. The 21 LoC is the entire UI side of plan resume — everything else (decision persistence, runtime drain, idempotency-key correlation) lives in 2/6.

ui/src/ui/views/plan-approval-inline.ts (306 LoC)

The card that appears ABOVE the chat input bar when planApprovalRequest != null. Two visual variants share the same shell: the plan variant (3-button triad: Accept / Accept-allow-edits / Revise + an "Open plan" link) and the question variant (PR-10, AskUserQuestion: 1 button per option + optional "Other…" textarea).

Plan variant — renderInlinePlanApproval() at plan-approval-inline.ts:53-175. Buttons map to sessions.patch { planApproval: { action: "approve" | "approve-with-edits" | "revise" } }, fired by the host. The "Revise" button opens an inline textarea (matching Claude Code's web revision UX) with Ctrl/Cmd+Enter to submit and Escape to cancel; the chat input is hidden by the caller while the card is showing so users don't accidentally type into the wrong surface.

Title fallback — plan-approval-inline.ts:73-77: when the agent's exit_plan_mode call carries an explicit title (PR-9 Tier 1 contract), use it; when it's the generic "Plan approval requested" boilerplate or the legacy "Plan approval — …" prefix, fall back to "Agent proposed a plan". This means agents that don't yet emit Tier-1 titles still get a sensible headline. Test at plan-approval-inline.test.ts:47-68.

Question variant — renderInlineQuestion() at plan-approval-inline.ts:183-306. Same shell, different actions row. Carries a defensive guard: if the host forgets to wire onAnswerOption, the buttons render as disabled and a visible warning appears (⚠️ Question handler not wired (host did not pass onPlanApprovalAnswer). Buttons disabled.) — instead of mute no-op buttons that look interactive (plan-approval-inline.ts:196-222). This was a Copilot review fix (#3104741709) on the umbrella.

Offline behavior — when connected === false, every button across both variants is disabled and a banner appears ("Reconnect to resolve this plan. The approval stays pending while offline." for plans; analogous for questions). Tests assert disabled state at plan-approval-inline.test.ts:133-150 (plan) and plan-approval-inline.test.ts:181-210 (question).

"Other…" textarea state — PR-13 Bug 2 fix: caller owns questionOtherOpen / questionOtherDraft so the textarea state survives across re-renders, and Escape returns to the option list (instead of dismissing the entire card, which a window.prompt-based implementation would have done). Test at plan-approval-inline.test.ts:248-294.

Test coverage — plan-approval-inline.test.ts (295 LoC). 10 cases: nothing-when-no-request, generic-title fallback, button wiring, revise-editor draft+keyboard, offline plan, missing-handler warning, offline question, option click + Other handoff, free-text submit + cancel.

Supporting files (the rest of the diff)

• apps/shared/OpenClawKit/Sources/OpenClawKit/Resources/tool-display.json (+29 lines) — adds 5 plan-mode tool entries the native apps render: update_plan (🗺️), enter_plan_mode (🧭), exit_plan_mode (✅), plan_mode_status (🔍), ask_user_question (❓). Each carries detailKeys so the native side knows which payload fields to render in the tool card. The web UI doesn't read this file directly — it has its own tool-display-config.ts mirror — but native apps depend on this catalog being in sync.
• ui/src/styles/chat/plan-cards.css (+134 lines) — accent-bordered card with status-marker glyphs. Both ::-webkit-details-marker (Chromium/Safari) and ::marker (Firefox) suppressed so the custom chevron isn't doubled. :focus-visible outline added on <summary> (Copilot review fix from umbrella).
• ui/src/styles/chat/layout.css (+228 lines) — chat shell layout adjustments to make room for the inline approval card (it sits between the message thread bottom and the composer top, with deliberate top/bottom margins so the card visually associates with the composer it replaces, not the most-recent message).
• ui/src/styles/chat.css (+1) — single @import line wiring plan-cards.css into the chat bundle.
• ui/src/ui/chat/slash-command-executor.ts (+374) + .node.test.ts (+160) — /plan on|off|status slash-command handlers; pre-existing executor stub gets the plan-mode action arms. Tests pin the patch shape ({ planMode: "plan" | "normal" }) and the chip-state side effects.
• ui/src/ui/chat/slash-commands.ts (+12) — registers /plan in the slash-command catalog so it autocompletes from the / menu.
• ui/src/ui/chat/grouped-render.test.ts (+309 / -79) — extends the grouped-render fixture set with plan-card cases so the message-thread renderer's grouping logic correctly de-dupes consecutive plan events into a single rendered card.
• ui/src/ui/views/chat.ts (+477 / -106) — the integration host detailed above.
• ui/src/ui/app-render.ts + app-tool-stream.ts + app-chat.ts + app-view-state.ts + app.ts (~1300 lines net additions) — wires plan-approval-request lifecycle into the top-level chat app: stream-side detection of exit_plan_mode / ask_user_question events, view-state shape extensions for the approval-card local state (revise textarea, "Other…" textarea), patch-and-resume sequencing on approve/answer/reject.

Accessibility + i18n

Accessibility — six concrete things, all asserted by tests:

i18n — exactly one new key carries the plan-mode UI work: planViewToggle: "Toggle plan view sidebar", present in all 13 locale files (en, de, es, fr, id, ja-JP, ko, pl, pt-BR, tr, uk, zh-CN, zh-TW). The plan card / approval card / mode menu surface strings are not yet i18n'd in this PR — they're rendered from English literals in the Lit templates. This is intentional: extracting the approval/menu strings is a follow-up that depends on settling the user-facing copy after iter-3 of the umbrella. Tracking in #70101 carry-forward.

Edge cases + review-debt receipts

These are the non-obvious behaviors hardened by previous review cycles on the umbrella that survive into this PR. Calling them out so a reviewer doesn't unwittingly "simplify" them away:

Test coverage matrix

All tests use vitest with jsdom (@vitest-environment jsdom) and assert against real rendered DOM rather than snapshot strings, so a CSS-class rename or template restructuring doesn't accidentally pass. The test-LoC ratio (1067 / 873 ≈ 1.22×) is in line with the umbrella's UI test density.

Styling + CSS tokens

The new components use existing design tokens rather than introducing new color variables — every var() call falls back to a sensible literal so the components render correctly on a fresh checkout before theme tokens are loaded:

The accent-bordered-left treatment on plan cards (3px left border, 1px elsewhere) deliberately mirrors tool-cards.css so plan cards visually associate with tool output rather than reading as a separate UI surface. The approval card uses a warmer surface (caller-supplied) with a danger-button variant for Revise — --danger for the destructive action remains the standard system token.

The new layout adjustments in layout.css (+228 lines) carve out vertical space for the inline approval card by:

• Reserving a min-height region above the composer that grows when .plan-inline-card is present.
• Setting the composer's bottom-anchor offset to account for the card's measured height (CSS-only, no JS measurement).
• Ensuring the card doesn't overlap the message thread's scroll-bottom indicator (the "↓ New messages" jump button) by giving it a stacking-context that sits beneath that floating affordance.

Parity benchmark callout

Earlier prompt-parity benchmarking (same prompts hit OpenClaw + Codex + Claude Code) measured ~90% parity on response quality and ~95% parity on session lengths across the corpus, on top of plan mode landing. For UI specifically, two patterns in this PR are deliberate convergences:

• Inline plan-approval card — the "card above the composer with Accept / Accept-allow-edits / Revise" shape mirrors Claude Code's web UX. The Revise → inline textarea (rather than popup) is also lifted from there. Header comment at plan-approval-inline.ts:1-14 documents the parity intent.
• Mode-switcher chip — the chip-with-dropdown in the chat header matches Codex's run-mode toggle pattern (single chip showing current mode, dropdown to change, kbd shortcuts displayed in the menu). The 6-mode catalog (Default/Ask/Accept/Plan/Plan ⚡/Bypass) is OpenClaw-specific — the Plan ⚡ entry is the PR-10 auto-approve variant which is novel to this stack.

The convergences are about UX expectations (users coming from those tools find familiar surfaces) rather than implementation lifting — the underlying state model (plan as its own dimension coexisting with permission mode, the synthesized "Custom" mode for non-preset combos) is OpenClaw-specific and has no analogue in either source.

What a reviewer can verify in <30 min

Concrete checklist that exercises every load-bearing surface in this PR. Assumes the merge order is 1/6 → 2/6 → 3/6 → 4/6 (or that you're reviewing on the FULL bundle):

1. Spin up the gateway + open webchat (~3 min) — pnpm dev or equivalent; navigate to /chat.
2. Mode chip renders (~2 min) — chip should show "Default" with the shield icon. Click it; menu should show all 6 modes with Ctrl+1..6 hints. Press Escape; menu closes. Ctrl+4 (with focus NOT in the composer); chip switches to "Plan" with the checkmark-checkbox icon.
3. Focus guard works (~2 min) — click into the composer; type "ctrl+4" (literally). Should type the characters, NOT switch modes. (Exercises the Shadow-DOM-aware guard.)
4. Plan card renders inline (~5 min) — with a plan-mode-capable agent, send "make a 3-step plan to refactor the login component". The agent's update_plan event should render an expandable <details> card in the thread; click the summary to expand; verify 1/3 done style meta updates as the agent runs.
5. Approval card flow (~5 min) — when the agent calls exit_plan_mode, the inline approval card appears ABOVE the composer. Composer input hides. Click "Open plan" — the right sidebar opens with the formatted markdown. Click "Revise" — inline textarea opens; type feedback; Cmd+Enter submits; card vanishes; agent receives the revision via pendingAgentInjections and continues in plan mode.
6. Plan resume on reconnect (~5 min) — with a plan approval pending, kill the gateway. Card buttons disable; banner shows "Reconnect to resolve this plan…". Restart the gateway. Buttons re-enable. Click Accept; verify in network tab that chat.send fires with deliver: false + idempotencyKey: "plan-resume-<uuid>" (this is the plan-resume.ts primitive). Agent run resumes; no synthetic "continue" bubble appears in the transcript.
7. Question variant (~3 min) — with an AskUserQuestion-capable agent, ask something that triggers the tool. The same approval-card shell renders with one button per option (and Other… if allowFreetext: true). Click an option; verify the sessions.patch { planApproval: { action: "answer", answer: <text> } } fires.
8. i18n spot-check (~2 min) — switch the UI locale to (say) ja-JP or zh-CN; verify the plan-view toggle tooltip uses the localized string from planViewToggle.

Total: ~25 min for a full happy-path + offline + question + i18n sweep.

Suggested commands for reviewers

# Run the four new component test files in isolation:
pnpm --filter ui test -- ui/src/ui/chat/plan-cards.test.ts \
                        ui/src/ui/chat/mode-switcher.test.ts \
                        ui/src/ui/chat/plan-resume.node.test.ts \
                        ui/src/ui/views/plan-approval-inline.test.ts

# Sanity-check the i18n cleanup (verify deleted keys are genuinely unreferenced):
pnpm ui:i18n:check

# Spin up the gateway + open webchat for the manual smoke pass:
pnpm dev   # then open http://localhost:<gateway-port>/chat

The four-file test command above runs in <2s on a warm vitest cache and is the tightest smoke check that exercises every component-level invariant in this PR.

What This PR Does NOT Include

• Channel integration (/plan slash commands across text channels, Telegram attachment delivery) → [Plan Mode 5/6] Text channels + Telegram
• Automation + subagent follow-ups → [Plan Mode AUTOMATION] ([Plan Mode AUTOMATION] Cron nudges + auto-enable + subagent follow-ups #70089) + bundled in [Plan Mode FULL] ([Plan Mode FULL] Integrated bundle for testing (Parts 1\u20136 + automation + executing-state lifecycle) #70071)
• Docs (architecture, operator runbook) + QA scenarios → [Plan Mode 6/6] Docs, QA, and help
• Mobile (iOS/macOS/Android) plan UI — the UI here is web-only. Native apps consume the same tool-display.json plan-mode entries added in this PR but render their own approval cards.
• Accessibility audit for the approval card — basic role="region" + aria-label ship here; full audit (screen-reader walkthrough, contrast verification on the danger button, focus-ring on the textarea) is a follow-up cycle in [Plan Mode] Master tracker for the 9-PR upstream rollout #70101.
• i18n extraction of approval-card / menu strings — only the planViewToggle key is i18n'd here; copy for the approval card buttons and the mode menu labels is still English literals, pending iter-3 copy-finalization.

Carry-forward / deferred (tracked in #70101)

• Mobile (iOS/macOS/Android) plan UI — native apps consume the plan-mode entries added to tool-display.json here, but render their own approval cards. The native counterpart of plan-approval-inline.ts is a follow-up; the contract (Accept / Accept-allow-edits / Revise + Open plan, plus the question variant with N options + Other) is settled by this PR and can be ported as-is.
• Accessibility audit — basic landmarks (role="region" + aria-label) and keyboard contracts (focus-visible on the disclosure summary, Ctrl/Cmd+Enter to submit, Escape to cancel) ship here. A full screen-reader pass — including SR announcement of "approval pending" when the card appears, the contrast ratio of the danger-button variant on the dark card surface, and the focus-ring on the textarea — is a follow-up cycle.
• i18n extraction of approval-card / mode-menu strings — only the planViewToggle key is i18n'd in this PR. The approval card buttons ("Accept", "Accept, allow edits", "Revise", "Send revision", "Send answer", "Back to options") and the mode-menu labels ("Default permissions", "Ask each mutation", etc.) are still English literals. Extraction is queued behind iter-3 copy-finalization so we don't churn translators with copy that may still change.
• Tool-display strings i18n — the 5 plan-mode entries in tool-display.json carry English titles; localized variants will land with the broader tool-display i18n pass tracked separately.

Issue references

• Refs feat(plan-mode): full rollout + iter-1/2/3 hardening (consolidates PRs A/B/C/D/E/F/7/8/10/11) #68939 plan UI surface area
• Master tracker [Plan Mode] Master tracker for the 9-PR upstream rollout #70101
• Depends on [Plan Mode 1/6] Plan-state foundation #70031 (1/6), [Plan Mode 2/6] Core backend MVP #70066 (2/6), [Plan Mode 3/6] Advanced plan interactions #70067 (3/6)
• Surfaces consumed: PlanModeSessionState + planApproval (2/6), AskUserQuestion + exit_plan_mode Tier-1 contract (3/6)
• Native-app counterpart (mobile UI): tracked in [Plan Mode] Master tracker for the 9-PR upstream rollout #70101 carry-forward