ClaudeDo/docs/superpowers/specs/2026-06-26-in-app-interactive-sessions-design.md

In-App Interactive Sessions — Design

Date: 2026-06-26 Status: Proposed (awaiting approval)

Goal

Replace the external Windows-Terminal "Run interactively" session with an in-app streaming chat, rendered in the existing SessionTerminalView in both task detail and Mission Control. Keep everything inside the app — no wt.exe pop-out. Autonomous task execution is untouched (stays one-shot, non-interactive).

Decisions (brainstorm)

1. Engine: persistent streaming session. One claude process kept alive with --input-format stream-json; user messages pushed over stdin.
2. Scope: interactive sessions only. The autonomous TaskRunner/ClaudeProcess run loop, review, queue, and worktree machinery are NOT changed.
3. Placement: shared SessionTerminalView — the in-app session + composer appear in the task-detail session surface and in the Mission Control monitor pane.
4. Full replace. "Run interactively" now opens the in-app session; the WindowsTerminalLauncher.LaunchInteractiveAsync path is removed. Planning sessions keep using wt (untouched).
5. Send semantics: interrupt + redirect mid-turn (control protocol), with automatic queue-for-next-turn fallback if interrupt is unavailable.

What an interactive session is (unchanged semantics, new transport)

Today (PlanningSessionManager.OpenInteractiveAsync + WindowsTerminalLauncher): claude --model <PlanningAlias> --permission-mode auto "<task title+description>" in the list's working dir, env MAX_THINKING_TOKENS=20000, full default toolset, relies on the globally-registered claudedo MCP. Ephemeral — no worktree, no task_run record, no status change, no review.

We keep all of that. Only the transport changes: instead of a wt window, the same claude invocation runs as a persistent stream-json process owned by the worker, its output streamed into the app and its stdin fed from an in-app composer.

Honest tradeoff: the wt terminal gave the full Claude Code TUI (slash-command UX, interactive prompts). An in-app stream-json chat is plainer — type messages, watch streamed output. --permission-mode auto means no blocking permission prompts (so headless works), but it is a simpler surface than the real TUI. Accepted per the "full replace" decision.

The streaming engine

Flags: --model <PlanningAlias> --permission-mode auto --input-format stream-json --output-format stream-json --verbose --replay-user-messages in the list working dir, env MAX_THINKING_TOKENS=20000. No --mcp-config/--allowedTools (interactive uses the global MCP + default tools, exactly as today).

• First stdin message = the seeded interactive prompt: {"type":"user","message":{"role":"user","content":[{"type":"text","text":"…"}]},"parent_tool_use_id":null}\n (stdin stays open).
• A stdout read task forwards each NDJSON line to a callback (→ broadcast + the session's log) and detects result events (turn boundary; the process then idles for the next message).
• SendUserMessageAsync(text) writes a user-message JSON line; if a turn is in flight, also InterruptAsync() (control-protocol interrupt) so Claude pivots immediately. If interrupt is unavailable, the message lands when the current turn ends → automatic queue fallback.
• Interrupt is verified working (spike, 2026-06-26, CLI 2.1.191). Exact shape: {"type":"control_request","request_id":"<id>","request":{"subtype":"interrupt"}} — no initialize handshake needed; control_response {"subtype":"success"} confirms synchronously; the same process then accepts the redirect and runs a fresh turn with context intact.
• Interrupt artifact: the aborted turn emits a result with is_error=true, subtype="error_during_execution". The session must treat an interrupt-induced result as "turn aborted, continue" (drain the queued redirect), not as a session failure. Tolerate the incidental system:init/system:status/rate_limit_event/hook events that also appear in the stream.
• --replay-user-messages echoes each sent message back on stdout as a user event, so it rides the existing stream pipeline into the timeline (ordered + confirmed) with no extra broadcast surface.
• The session ends only when the user stops it (kill the process tree) — an interactive session has no auto-finalize and never enters review. No queue slot is involved (it is launched directly, not via the autonomous picker).

Surface changes

Worker

• Runner/StreamingClaudeSession.cs (new) — persistent process + send/interrupt/stop; reuse the ProcessStartInfo shape + MCP_TOOL_TIMEOUT from ClaudeProcess; streams via a line callback; IsTurnInFlight. Cancellation kills the tree.
• Runner/LiveSessionRegistry.cs (new, singleton) — taskId → StreamingClaudeSession (Register/TryGet/Unregister/Stop), mirrors PendingQuestionRegistry.
• Planning/InteractiveSessionService.cs (new) — owns interactive lifecycle: StartAsync( taskId) resolves the list working dir + seeded prompt (reuse OpenInteractiveAsync's body), spawns the session, registers it, wires output to HubBroadcaster.TaskMessage, broadcasts InteractiveSessionStarted; SendAsync(taskId, text); StopAsync(taskId) → InteractiveSessionEnded.
• Planning/WindowsTerminalLauncher.cs + Planning/Interfaces/ITerminalLauncher.cs — remove LaunchInteractiveAsync (+ InteractiveLaunchContext). Planning start/resume stay.
• Hub/WorkerHub.cs — OpenInteractiveTerminalAsync re-pointed to InteractiveSessionService.StartAsync (no terminal); add SendInteractiveMessage(taskId, text), StopInteractiveSession(taskId) (+ optional InterruptInteractiveSession).
• Hub/HubBroadcaster.cs — InteractiveSessionStarted(taskId), InteractiveSessionEnded(taskId). Log lines reuse the existing TaskMessage(taskId, line).
• Program.cs — register LiveSessionRegistry + InteractiveSessionService.

UI

• Views/Islands/SessionTerminalView.axaml(.cs) — add an optional composer (styled properties: IsComposerVisible, ComposerText, SubmitCommand, ComposerPlaceholder). Both hosts (task detail + Mission Control) get it by binding their VM's composer state.
• StreamLineFormatter — render type:"user" NDJSON events as a LogKind.User bubble.
• A small shared composer concept on TaskMonitorViewModel and DetailsIslandViewModel (factor a helper to avoid duplication): ComposerDraft, SubmitComposerCommand, IsInteractiveLive (set by InteractiveSessionStarted/Ended). Submit → SendInteractiveMessageAsync; clear draft. (If a pending AskUser question exists, the same composer answers it — keep the existing answer route.)
• MissionControlViewModel — EnsureMonitor(taskId) on InteractiveSessionStarted so the session appears as a monitor; mark it interactive.
• Services/Interfaces/IWorkerClient.cs + WorkerClient.cs — SendInteractiveMessageAsync, StopInteractiveSessionAsync (+ optional interrupt); events InteractiveSessionStartedEvent/InteractiveSessionEndedEvent. OpenInteractiveTerminalAsync keeps its name/signature (now starts the in-app session). Update hand-rolled fakes in both test projects (iworkerclient_fakes_sync).
• TasksIslandViewModel.RunInteractivelyAsync — unchanged call site; now opens/focuses the in-app session surface instead of a terminal.
• Localization interactive.* / missionControl.chat.* (en/de, parity enforced).

Tests

• StreamingClaudeSessionTests (fake process stream, no real Claude): first message streams; result idles; a sent message starts another turn; mid-turn send calls InterruptAsync then delivers; interrupt-failure degrades to queue; stop kills.
• LiveSessionRegistryTests — register/get/unregister/stop.
• InteractiveSessionServiceTests — start resolves working dir + seeds prompt + registers + broadcasts started; send routes to the session; stop broadcasts ended (fake session + broadcaster).
• TaskMonitorViewModelTests / DetailsIslandViewModelTests — composer enabled while interactive-live; submit invokes client + clears; user line renders; question route still answers.

Risks / open questions

• Interrupt protocol shape — RESOLVED (spike 2026-06-26, see "The streaming engine"). Mid-turn interrupt works on CLI 2.1.191 with the documented shape; the queue fallback is a genuine fallback now, not the expected path. Re-verify if the CLI version changes.
• Plainer than the TUI — slash-command/interactive-prompt UX differs (accepted).
• Auto-mode editing the list working dir directly (no worktree) — this is the existing interactive behavior, unchanged here.
• No real-Claude tests (project rule) — the live loop is covered only by the fake stream; real interrupt/redirect is a manual verification gap to flag.

Non-goals

• Changing autonomous task execution / review / queue / worktrees.
• Interactive sessions producing run records, worktrees, or review (stays ephemeral).
• Worktree isolation for interactive edits; image/attachment messages in the composer.
• Removing planning's wt terminal launch.