ADR 0008 — Host mode per profile: print mode by default, a tmux TUI when the chat must live in the Claude app

Status: accepted 2026-09-19. Amends ADR 0001, which rejected A3 (tmux TUI) on the grounds that "its only unique value (Claude-app mirror) is not a v1 requirement". It is a requirement now: every routed chat should be visible and continuable from the Claude app, the way the gateway Angelia replaces did it.

The measurement that forced the choice

--remote-control only registers an interactive session. Measured on claude 2.1.278: under -p the flag is accepted and then ignored — the session record in ~/.claude/sessions/<pid>.json shows entrypoint: sdk-cli, a derived name rather than the one passed, and no bridge id, while a session started as a terminal cli in the same directory has a bridge id and appears in the app. No flag, setting or environment variable changes that. A print-mode session cannot reach the app.

Decision

Keep both, chosen per profile with tui: true (Claude Code only; print mode stays the default).

• Print mode (ADR 0001). claude -p over stream-json. Permission prompts arrive as JSON and are relayed to the chat; nothing is read off a screen.
• TUI mode. The same CLI as a real interactive session in a tmux pane on Angelia's own socket (tmux -L angelia). Angelia types the turn into the pane; a Stop hook writes the turn's answer to a file; the daemon polls that file and delivers it. Progress lines come from the session transcript, not from the screen.

What TUI mode buys

Remote Control, so the chat is in the Claude app and can be continued from the phone. Sessions on a separate tmux server outlive the daemon: a restart (or a crash before the launchd unit exists) reattaches instead of resuming, so nothing is lost and the app entry never blinks. MCP servers stay warm between turns, background tasks outlive a turn, and slash commands behave as in a terminal.

What it costs, and what is done about each

• The pane is a screen, not a protocol. Markers are version-coupled. Mitigation: every pane rule is a pure function tested against real captured frames (tests/fixtures/pane-*.txt), so a CLI redraw breaks a test rather than a group.
• Pasting into the wrong thing. Mitigation: paste only at an idle prompt (no spinner, no dialog), then confirm the text is in the box before pressing Enter, and clear the box rather than submit blind.
• Permission prompts. At first the dialog was parsed from the rule above it and a chat "yes" pressed 1. A review found both weak: a command can draw a rule of its own, so the chat saw a harmless tail of it, and a key answers whichever dialog is open when it lands. Since 0.3.1 a PermissionRequest hook carries each request to the chat as the tool and its exact input, as print mode relays it, waits, and hands the owner's answer back to Claude as its decision, keyed to that request; no key is pressed. It relays only while a turn from the chat is being read, and steps aside otherwise, so the Claude app and the pane ask as they always did. A dialog the hook did not relay (one left open while nobody read the chat) is announced, and never answered from the chat.
• No Stop event for a CLI-handled message. /compact ends without one. Mitigation: an idle pane with nothing new in the transcript for 12 s ends the turn with whatever text the transcript holds (empty for /compact, which the router confirms itself).
• The trust dialog. A directory Claude Code has not seen opens "Is this a project you trust?" with "No, exit" preselected; print mode never shows it. Angelia moves the cursor, checks it is on the yes row, and presses Enter — routing.yaml already declared that directory and its permission mode, so this is not a new decision being made on the user's behalf.
• tmux becomes a dependency for profiles that opt in. Print mode still needs nothing.

Open

Turns typed by the user in the Claude app are not delivered to the chat (the gateway did deliver them). Nothing forwards them today, and a private message typed in the app should probably not land in a group by surprise; decide deliberately rather than inherit it.