Spec: one embedding architecture for live Claude sessions (covers #18 Stage 2, F-1 embedded terminal, live-run attach)

[jordanrburger]

One architectural decision, currently tracked as three separate items

Three roadmap/backlog items are framings of the same underlying question — how does a live Claude session run inside, or attach to, Scout.app?

1. Feature: in-app conversational assistant scoped to all of Scout (not just per-item Launch Claude) #18 Stage 2 — embedded in-app assistant (Claude Agent SDK or claude CLI subprocess, vault + scoutctl as tools, approval-gated writes).
2. F-1 in docs/feature-roadmap.md — embedded terminal (SwiftTerm) hosting interactive claude sessions per task.
3. BACKLOG.md "View / interact with a running SCOUT session" (research-gated) — attach to / observe scheduled -p runs, possibly via an Agent SDK migration.

Building any one of these without deciding the shared substrate risks shipping two parallel embedding mechanisms (a PTY/terminal path and an SDK/tool-call path) that don't compose.

What the spec should decide

• Runtime: Agent SDK in-process vs. claude CLI subprocess vs. PTY-embedded interactive session — which single substrate can serve all three use cases?
• Auth implications of each (SDK needs key material; CLI/PTY reuse the existing login).
• Whether scheduled runs migrate off claude -p (this is what unlocks attach/interact, per the BACKLOG research questions).
• Tool surface + approval gating (per Feature: in-app conversational assistant scoped to all of Scout (not just per-item Launch Claude) #18's guardrails), and how a terminal-style surface and a chat-style surface share it.
• Sequencing with F-4 (session↔task linkage) and F-2 (Sessions page), which both consume whatever session-identity model this picks.

Suggested outcome

A short design doc in docs/ choosing the substrate + a build order; #18 Stage 2, F-1, and the live-attach research item then become milestones against it rather than independent builds.

From the 2026-06-10 audit (docs/audit-2026-06-10.md §5, "Strategic flag").