feat: a structured claude agent opens in claude code's own terminal and comes back

[sean-brydon]

Phase 4a of design/structured-agents/plan.md (Labs, structured Claude agents only).

What it does

POST /v1/sessions/{name}/switch with {"to": "terminal" | "chat"} (capability driver.switch) moves an idle structured session between its chat and Claude Code's own screen. It keeps the same conversation and runs one process at a time:

• To the terminal:
  • note where Claude's transcript stands
  • agenthost.Stop (Claude ends at its stdin's end)
  • respawn-pane -k as claude --resume <id>, with BERTH_DRIVER cleared so berthd's hooks drive the turn ledger again
  • bypass carries over as --permission-mode bypassPermissions unless running as root
  • beginStartup watches for Claude's startup questions
• Back to the chat:
  • /exit is typed as keys, then wait for the pane to end
  • copy what the TUI added to the transcript into berthd's log as out entries, so the chat reads on in order
  • respawn the host with --resume on the same log and socket, and wait for it to listen
  • also works from a TUI that was already left (/exit, or "No, exit" at the trust question)
• The session keeps @berth_conv/@berth_sock throughout. Session.switch says where it can go: terminal while structured, chat while in its terminal.
• App: for these sessions, the pane's existing Terminal | Conversation toggle performs the switch (tips: "Open in Claude Code's terminal" and "Back to the chat") and shows a toast on refusal.

Fixes in the Claude driver found while testing

• Events went out from a goroutine each, so finished could overtake started. They now go through one ordered queue per session.
• A prompt's started could reach the ledger before session.sent opened its turn, leaving the turn stuck running. The driver now waits briefly (Turns.AwaitSent).
• A write to a host that is still starting (just launched, or just back from the terminal) now waits up to 10s instead of reporting the session as exited.
• A host starting again clears the follower's "exited" mark.

Tests

• TestAStructuredSessionGoesToItsTerminalAndBack, with a stand-in that also plays Claude's TUI when run without -p:
  • structured → terminal (driver terminal, switch chat, its screen shows the resumed session)
  • a second switch to the terminal is a 409
  • → chat: the turn typed in the terminal is read in its place, and a new prompt is answered
  • the conversation reads echo: hello | answered in the terminal | echo: back again
  • it passed 5/5 under -race, together with the structured-session test
• TestALiveClaudeSessionWorks (opt-in BERTH_LIVE_CLAUDE=1) now also switches real Claude Code to its terminal (answering its trust question for the temporary folder) and back, and Claude still remembers the first reply. It passed locally in 16s.
• Full go test -race ./..., go vet ./..., app checks and build, tsc -p e2e and the docs build all pass.

Next (4b)

Resuming a structured conversation after its session is gone, and the SQLite conversation index that lists them.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
berth	Ready	Preview	Oct 13, 2026 12:42pm UTC
berth-docs	Ready	Preview	Oct 13, 2026 12:42pm UTC

[linear-code]

ENG-6004