docs: reflect Phase 3 agent SDK integration progress

Update phases.md with Phase 3 checklist (in_progress), add session
progress log entry, record claude CLI architecture decision in
task_plan.md, update README/TODO/CHANGELOG with Phase 3 additions,
and sync .claude/CLAUDE.md with current constraints.

docs/phases.md

@@ -107,22 +107,35 @@ bterminal-v2/
 
 ---
 
-## Phase 3: Agent SDK Integration [status: not_started] — MVP
+## Phase 3: Agent SDK Integration [status: in_progress] — MVP
 
-- [ ] Node.js sidecar: thin wrapper around Agent SDK `query()`
-- [ ] Sidecar communication: Rust spawns Node.js, stdio NDJSON
-- [ ] Sidecar lifecycle: spawn on demand, detect crash, restart
-- [ ] SDK message adapter (abstraction layer)
-- [ ] Agent pane: renders structured messages
-  - Text -> markdown rendered
-  - Tool calls -> collapsible cards (tool name + input + output)
-  - Subagent spawn -> tree node + optional new pane
-  - Errors -> highlighted error card
-  - Cost/tokens -> pane header metrics
+### Backend
+- [x] Node.js sidecar: spawns `claude` CLI with `--output-format stream-json` (not Agent SDK query() — avoids npm dep + version churn)
+- [x] Sidecar communication: Rust spawns Node.js, stdio NDJSON
+- [x] Sidecar lifecycle: auto-start on app launch, shutdown on exit
+- [ ] Sidecar lifecycle: detect crash, offer restart in UI
+- [x] Tauri commands: agent_query, agent_stop, agent_ready
+
+### Frontend
+- [x] SDK message adapter: parses stream-json into 9 typed AgentMessage types (abstraction layer)
+- [x] Agent bridge: Tauri IPC adapter (invoke + event listeners)
+- [x] Agent dispatcher: singleton routing sidecar events to store
+- [x] Agent store: session state, message history, cost tracking (Svelte 5 $state)
+- [x] Agent pane: renders structured messages
+  - [x] Text -> plain text (markdown rendering deferred)
+  - [x] Tool calls -> collapsible cards (tool name + input)
+  - [x] Tool results -> collapsible cards
+  - [x] Thinking -> collapsible details
+  - [x] Init -> model badge
+  - [x] Cost -> USD/tokens/turns/duration summary
+  - [x] Errors -> highlighted error card
+  - [ ] Subagent spawn -> tree node + optional new pane (Phase 5)
+- [x] Agent status indicator (starting/running/done/error)
+- [x] Start/stop agent from UI (prompt form + stop button)
 - [ ] Auto-scroll with scroll-lock on user scroll-up
-- [ ] Agent status indicator (running/thinking/waiting/done/error)
-- [ ] Start/stop/cancel agent from UI
 - [ ] Session resume (SDK `resume: sessionId`)
+- [x] Keyboard: Ctrl+Shift+N new agent
+- [x] Sidebar: agent session button
 
 **Milestone: After Phase 3, we have the core differentiator.** SDK agents run in structured panes alongside raw terminals.
 

docs/progress.md

@@ -60,5 +60,23 @@
 - [x] npm dependencies: @xterm/xterm, @xterm/addon-canvas, @xterm/addon-fit
 - [x] Cargo dependencies: portable-pty, uuid
 
+### Phase 3: Agent SDK Integration (in progress)
+- [x] Rust SidecarManager: spawn Node.js, stdio NDJSON, query/stop/shutdown (sidecar.rs, 218 lines)
+- [x] Node.js agent-runner: spawns `claude -p --output-format stream-json`, manages sessions (agent-runner.ts, 176 lines)
+- [x] Tauri commands: agent_query, agent_stop, agent_ready in lib.rs
+- [x] Sidecar auto-start on app launch
+- [x] SDK message adapter: full stream-json parser with 9 typed message types (sdk-messages.ts, 234 lines)
+- [x] Agent bridge: Tauri IPC adapter for sidecar communication (agent-bridge.ts, 53 lines)
+- [x] Agent dispatcher: routes sidecar events to agent store (agent-dispatcher.ts, 87 lines)
+- [x] Agent store: session state with messages, cost tracking (agents.ts, 91 lines)
+- [x] AgentPane component: prompt input, message rendering, stop button, cost display (AgentPane.svelte, 420 lines)
+- [x] UI integration: Ctrl+Shift+N for new agent, sidebar agent button, TilingGrid routing
+
+Architecture decision: Uses `claude` CLI with `--output-format stream-json` instead of Agent SDK `query()` API. Avoids SDK npm dependency and version churn while getting identical structured output.
+
 ### Next Steps
-- [ ] Begin Phase 3: Agent SDK Integration (Node.js sidecar, SDK message adapter)
+- [ ] Markdown rendering in agent text messages
+- [ ] Sidecar crash detection and restart UI
+- [ ] Auto-scroll lock on user scroll-up
+- [ ] Testing: vitest for sdk-messages adapter, cargo test for sidecar
+- [ ] Begin Phase 4: Session Management + Markdown Viewer

docs/task_plan.md

@@ -3,7 +3,7 @@
 ## Goal
 Redesign BTerminal from a GTK3 terminal emulator into a **multi-session Claude agent dashboard** optimized for 32:9 ultrawide (5120x1440). Simultaneous visibility of all active sessions, agent tree visualization, inline markdown rendering, maximum information density.
 
-## Status: BUILDING (Phase 2 complete — Rev 2)
+## Status: BUILDING (Phase 3 in progress — Rev 2)
 
 ---
 
@@ -74,9 +74,9 @@ The Agent SDK cannot run in Rust or the webview. Solution:
 └─────────────────────────────────────────────────────┘
 ```
 
-- Rust spawns Node.js child process on demand (when user starts an SDK agent session)
+- Rust spawns Node.js child process on app launch (auto-start in setup)
 - Communication: stdio with newline-delimited JSON (simple, no socket server)
-- Node.js process runs a thin wrapper that calls `query()` and forwards messages
+- Node.js process runs a thin wrapper that spawns `claude -p --output-format stream-json` and forwards NDJSON events
 - If sidecar crashes: detect via process exit, show error in UI, offer restart
 - **Packaging:** Bundle the sidecar JS as a single file (esbuild bundle). Require Node.js 20+ as system dependency. Document in install.sh.
 - **Future:** Could replace Node.js with Deno (single binary, no npm) for better packaging.
@@ -123,6 +123,7 @@ See [phases.md](phases.md) for the full phased implementation plan (Phases 1-6).
 | SDK abstraction layer | SDK is 0.2.x, 127 versions in 5 months. Must insulate UI from wire format changes | 2026-03-05 |
 | MVP = Phases 1-4 | Ship usable tool before tackling tree viz, packaging, polish | 2026-03-05 |
 | Canvas addon (not WebGL) | WebKit2GTK has no WebGL. Explicit Canvas addon avoids silent fallback | 2026-03-05 |
+| claude CLI over Agent SDK query() | Use `claude -p --output-format stream-json` instead of SDK npm package. Avoids dependency + version churn, identical structured output | 2026-03-06 |
 
 ## Open Questions