Skip to content

ADR-409: Esc in the chat never quits, and the compose box is for chatting: names and descriptions are typed in an entry dialog

Summary

  • Decided: in attend-chat, Esc closes what is open and clears, and never quits, with or without the kitty keyboard protocol. Quitting is Ctrl-C, which asks first over a draft, and a new Quit item on the ≡ menu, which does the same. The compose box lent to a new channel's name or a description says so where the text is typed (new channel name >, describe #deploy >) in place of >, and draws no destination flag. Showing a tab, opening a menu, or the column taking the keyboard gives the box back, by key as by click.
  • Trades away: Esc as a one-key quit on an empty line. Leaving the chat takes Ctrl-C or two clicks.
  • One-way? No. This is input handling and drawing in agent-tui and attend-chat; nothing on disk changes.
  • Probes: Confident (esc-never-quits): Esc never quits; Ctrl-C and ≡ → Quit do, and a double Esc is always safe. Not confident (esc-clears): with nothing open, Esc clears the selected message and the status line and leaves the draft as it is. The agent chose to keep the draft, so a stray Esc never loses typing.
  • Inversion: one end is Esc as the universal way out, which quits once nothing is left to close; the other is Esc as a pure close key with quitting elsewhere. This takes the second end, because the chat's tab key Ctrl+3 arrives as Esc in terminals without the kitty protocol, and a habitual double Esc to make sure a menu closed should never cost the session.

Context

ADR-504's note on panes says Esc and Ctrl-C quit beside a pane that owns text, asking first over unsaved work. In attend-chat that met two problems.

  • Where the terminal does not speak the kitty keyboard protocol, Ctrl+3 arrives as the same byte as Esc. The chat answered by asking quit the chat? on Esc with an empty line (ADR-404's implementation notes, then ADR-408 (a) as a shell question). With the protocol, an Esc on an empty line quit at once with no question. A double Esc, a common habit to make sure a menu has closed, closed the menu and then quit or asked to quit.
  • The compose box could be lent to a new channel's name or a description, and only the bottom bar said so. The box kept its > and its destination flag. The audit's finding 3: with the box lent, a menu opened and closed, abc and Enter created a channel #abc while the flag still read #infra. ADR-408 (b) made Esc and a click outside give the box back, but a tab key or the column's keyboard focus left it lent and out of sight.

The audit put the Esc question to the operator: Esc on an empty compose box with nothing open could always ask, or never quit. The operator chose the option labelled "Never quits (Recommended)", whose description read: "Esc only closes overlays and clears things. Quit stays on Ctrl-C (asks) and the ≡ menu. A double Esc is always safe." What "clears things" covers, the selection and the status line but not the draft, is the agent's reading.

Decision

(a) Esc never quits the chat. Esc closes the topmost overlay as ADR-408 (b) says: a menu, a picker, a question, the key help, the response modal, or the compose box lent to a name. With nothing open it clears the selected message and what the status line says. The draft stays. Where Ctrl+3 arrives as Esc it is the same key, so a tab key can never close the chat.

  • The pane says so to the shell through Pane::esc_quits, false for the chat. An Esc the pane passes on then quits nothing, and the key help lists ^C as the quit key in place of Esc ^C. Panes that keep the default, ways introspect and ways projects, still quit on Esc.
  • ADR-408 (a)'s Quit question and its stayed answer are removed. No key asks to quit.

(b) Quitting. Ctrl-C quits at once with nothing unsaved and opens the exit guard over a draft, as before. The ≡ menu ends with Quit, which asks the shell to quit through Open::Quit: the same path as Ctrl-C, guard included.

(c) The lent box says what it is lent to. While the compose box is lent, its first row starts with the label in bold accent, new channel name > or describe #channel >, in place of >. The label is cut to half the box so the text keeps room. The destination flag is not drawn, since Enter sends no message. Continuation rows indent by the label's width.

(d) What gives the box back. Besides Esc and a click outside it (ADR-408 (b)), showing a tab (Ctrl+digit, Alt+digit, Left or Right on the focused tab bar), opening any tab's or ≡'s menu, and the column taking the keyboard (F2, then Down) give the box back with the draft it held. The + slot and Ctrl+N lend it. A click on a tab already gave it back, so a key and a click on a tab now land in the same state.

Consequences

Positive

  • A double Esc is always safe, with or without the kitty protocol.
  • Quitting has one path for keys and clicks, and the mouse can quit.
  • The box shows what Enter will do: a message has a destination flag, and a name or description has its label.
  • Finding 3 cannot recur: a tab key or the column ends the lent box before Enter reaches it.

Negative

  • Esc no longer quits an empty chat; muscle memory from other TUIs reaches for it.
  • Showing a tab while typing a new channel's name drops the name typed so far. The draft from before the box was lent comes back.

Neutral

  • agent-tui gains Pane::esc_quits, default true.
  • The --help text and docs/attend-and-monitor/tui.md describe Esc and quitting as above.
  • ADR-405 and ADR-407 say nothing about Esc quitting and are unchanged. ADR-404's implementation notes describe the Esc question this record removes.

Alternatives Considered

  • Esc on an empty line always asks. It keeps a one-key route to quitting, but a double Esc still lands on a question and the question needs an answer before anything else works.
  • Esc clears the draft. It would make Esc a full reset, but a stray or doubled Esc would lose typing, which is the cost this record removes.
  • Keep the lent box until Enter or Esc, and only draw the label. It would make the state visible but let a tab change carry a half-typed name onto another channel's view, and a key would still differ from a click on the tab.

Correction (2026-10-11): the ≡ menu, the action slots, and the shown tab

Review of the change refined (d) so that (b) and (d) hold together. The decision text above stands as accepted.

  • The ≡ menu opens over a lent box. Its items give the box back when picked, except Quit, which leaves it lent. The shell's quit then counts a name typed there as unsaved and opens the exit guard, as Ctrl-C does, and Back returns to the lent box. Opening ≡ no longer gives the box back on its own.
  • A click on an action slot does not dismiss. A click on ≡ or + acts as the slot's key does: ≡ opens its menu over the lent box, and + lends the box or keeps it lent, as Ctrl+N does.
  • Ctrl+digit on the shown tab with attend.chat.tabs.menu_on_repeat off shows the tab again, so it gives the box back as a click on that tab does.

Amendment (2026-10-12): the chat box is for chatting; names and descriptions are typed in an entry dialog

The operator said: "we should have the new channel name entry be consistent with the other context entry dialogs, not appearing in the chat box", and stated the principle: "the chat box is reserved for chatting, not a general entry interface".

  • The compose box is never lent. The lend mechanism (decision (b)'s new channel name > and describe #deploy > leads) is removed.
  • A line that is not a chat message is typed in one shared entry dialog, agent_tui::Open::Entry, docked where a menu docks: the new channel's name (from + or Ctrl+N) under the + slot, a channel's description (Describe…) beside its menu item, opened on the line the channel has now. Enter gives the text to the chat; a name it refuses opens the dialog again with the name and the reason inside it. Esc or a click outside closes it with nothing, and Esc never quits. While it is open it holds the keyboard; the compose box and its draft are untouched throughout.
  • A name typed in the dialog is unsaved work: Ctrl-C's exit guard names it ("new channel name being typed"), and going back opens the dialog again with the name.
  • Entry points moved: the new channel's name (+, Ctrl+N), and a channel's description (Describe…). Slash commands typed as chat stay in the compose box, since the operator typed them there. Confirmations were already the shell's question on the bottom bar (ADR-408).

Amendment (2026-10-12): arrows never turn typing into commands

A review of the nav polish found that ↑ or ↓ on an empty compose box left it at once, after which 1 switched the channel and q quit: a reflexive arrow turned the next keys into commands. The question put to the operator: should ↑ and ↓ leave an empty box, and what may single keys do outside it? The operator chose "Guarded (Recommended)", which read: "↑/↓ leave only a box that has text, at its first or last line; an empty box is left with Shift+Tab or Esc. Outside the box, q asks before quitting, and digits switch channels only when the tab bar has focus. Help keys still work outside the box."

  • ↑ at the start of the first line and ↓ at the end of the last line leave only a box that holds text. In an empty box they do nothing.
  • Esc in the box goes to the feed, with or without a draft, and clears the selection and the status line; the draft stays. It is the first stop of ADR-407's Esc cycle. Esc still never quits.
  • Outside the box, q asks quit? on the bar, whatever is unsaved; yes goes on through the exit guard over a draft. Ctrl-C quits as before.
  • A plain digit picks a channel by the column's number only while the focus is on a channel's row (ADR-407's amendment C). Elsewhere, an agent's row and the tab bar included, a digit is typed into the box, like any other character.
  • At the exit guard over the entry dialog, typing reaches neither the dialog nor the compose draft, and Esc goes back to the dialog as it was (ADR-504, note of 2026-10-13: a modal's own buttons answer it).

Amendment (2026-10-13): a send refused because its agent is quiet can be sent now

A send to an agent the chat reads as quiet was refused with no way past it, though a quiet agent can still read what is sent: one whose heartbeat lapsed through a long turn, one on another host, one that has not listened yet. The operator asked for Claude Code's own convention for sending at once, with a fallback where the key does not arrive.

  • A send refused because its agent is quiet offers the send-now key, key first so an 80-column status line keeps it: press Enter again to send: @Name is quiet (no heartbeat), or Ctrl+Enter or Enter again to send now: @Name is quiet (no heartbeat) where the terminal reports Ctrl+Enter (the kitty keyboard protocol). The status line names only a key that arrives.
  • Enter pressed again on the unchanged draft sends it, and so does Ctrl+Enter, which mirrors Claude Code's chat:sendNow. Ctrl+Enter sends at once with no refusal first. Any edit to the draft, a completion and Esc withdraw the offer, and the next Enter refuses afresh.
  • An agent whose Claude Code process has exited on this host is refused whatever the key: @Name has exited and would not read this. attend-presence tells the two apart (ADR-129, addendum of 2026-10-13).
  • The same holds for an @Name send and for a send from an agent's DM view. Claude Code's chord fallback, Ctrl+X Ctrl+S, is not bound: Enter again is the fallback the operator named. (Bound since the amendment of 2026-10-14.)

Amendment (2026-10-14): Ctrl+X Ctrl+S sends now

The operator asked for Claude Code's chord in the compose box.

  • Ctrl+X Ctrl+S in the compose box sends now, as Ctrl+Enter does: to a quiet agent too, with no refusal first. Both keys arrive in every terminal, so the chord works where Ctrl+Enter arrives as Enter.
  • Ctrl+X edits nothing and holds for the next key only. Any key but Ctrl+S after it, or a paste or a click, drops the chord, and that key does what it does. Ctrl+S alone sends nothing.
  • Enter and Ctrl+Enter work as before, and the refusal's status line is unchanged. The F1 view names the chord on Enter's line (send; C-x C-s sends now), which keeps every key on one screen at 80x25; the footer keeps Enter send where it is short of room. attend-chat --help lists the chord beside the other send keys.

Note (2026-11-01): a message waits before it is sent, Esc recalls it, and the keys that aliased to Esc moved

The operator asked for "a small delay after pressing enter to send the message, allowing the operator to rescend their message. this means that any message sent has a countdown (cooldown?) before the message is actually dispatched. this can be an option that is configurable in 'ways settings'. the reason is that often one doesn't catch up to thinking until it's sent, and then one might want to recall the message to edit. recalling the message repopulates the chat entry window." They then said: "I think using esc and re-routing esc's current use for toggling feed focus is probably a better use of esc"; "if you send multiple messages within the delay, they all send as one message"; and "I think recall needs to universally be esc, and we can find other keys for other actions that are compatible with other terminals". Later they added: "I realized in claude code, after pressing enter on a message, one can press the up arrow key to reacall it too".

  • The delay. attend.chat.send_delay, in seconds, 5 by default, 0 to 60, user-scoped beside the other attend.chat.* keys; ways settings, the chat's Settings menu and /config set it. Enter on a message holds it in the feed, after the messages, with a countdown on its header (sending in 5s, on the warning ground), where it goes and how to recall it. When the countdown ends its route is resolved again, and it is sent through the path Enter sends by, from the view it was written in. A message whose route has changed meanwhile, such as one held for a channel dissolved during the countdown, is never sent elsewhere, #open included. It stays in the feed marked not sent (not sent: #deploy is gone), as does one the send refuses then, with the reason on the status line, and nothing sends it by itself. The draft typed meanwhile is left as it is, caret and route alike. Slash commands, a bare / among them, run at once. With 0 there is no waiting entry and Enter sends at once, as before this note.
  • One message for a burst. Enter on another message while one counts down on the same route joins it on a new line and starts the countdown again. The route is the one the send resolves, not the tab: its kind of send and the names it goes to. The operator view and #open share #open's post; @Name in a channel is a post there addressed to them, apart from the channel's own posts; #deploy @Name is a post and a direct message, apart from @Name in #deploy; and an agent's DM view sends to that agent. Another route waits on its own entry, and a message marked not sent takes nothing.
  • Esc recalls. Esc in the compose box takes the newest waiting message, joined text and all, back into the box and cancels its send. A box that holds a draft gets the recalled text first, then a line, then the draft, so nothing typed is lost. A click on a waiting message recalls that one, and Enter on it selected in the feed does the same. A recalled message, waiting or refused, comes back in the view it was written in whenever that view still exists, as the operator confirmed: the message keeps its own destination, so Enter sends it where it was held for and never where the operator happened to be when recalling it; one a quiet agent refused, recalled unchanged, Enter sends anyway. With nothing waiting, Esc in the box does what (a) and the amendment of 2026-10-12 say a close key does there: it clears the selected message and the status line, and keeps the draft. It no longer moves the focus.
  • ↑ in an empty box recalls too. Claude Code queues each message sent while it is busy, and Up in its input pulls the queued messages back for editing. ↑ in an empty compose box recalls the newest waiting message as Esc does; the amendment of 2026-10-12 left ↑ free there, since it leaves only a box that holds text. With text in the box ↑ keeps its place: the caret up a row, and at the start of the first line out of the box. Esc stays the recall key that works whatever the box holds.
  • Shift+Tab is the Esc cycle's first step. The step Esc took from the box to the feed is Shift+Tab's, which already left the box backward to the feed, an empty box included (the amendment of 2026-10-12). From the feed, a tab or a column row Esc goes on along the cycle as ADR-407 and ADR-408 describe: the ≡ menu, back to the tab or row last focused, the ≡ menu again. An overlay still takes the first Esc. The footer names Esc in the box only while a message waits (Esc recall).
  • Alt+digit shows a channel in every terminal. The column's channel jump is Alt+1..9, and Alt+0 the operator view, everywhere. Ctrl+digit stays as a second binding only where the kitty keyboard protocol is in effect, which the chat already learns from the shell at start (set_keyboard_enhanced). Without the protocol Ctrl+3 is the Esc byte, Ctrl+2 is NUL, Ctrl+4..7 are FS, GS, RS and US and Ctrl+8 is DEL, so no Ctrl+digit is bound there and Ctrl+3 is the same Esc as above. attend.chat.tabs.jump keeps its values: auto and both are Alt everywhere and Ctrl under the protocol, alt is Alt alone, ctrl is Ctrl under the protocol only, none is neither.
  • Quitting asks about what waits. Ctrl-C and ≡ → Quit with a message waiting open the exit guard, which names it and offers Send and quit (s) beside Back and Quit and discard all (D); nothing waiting is dropped unasked. Send and quit sends each message now, to a quiet agent too, as send-now does; one that still cannot go stays in the feed, not sent, and the chat stays open. With a draft in the compose box the button reads Send and quit, keep the draft, and the draft opens the next chat's compose box. A pane's key the guard already binds (b, r, D) is dropped, and its button is reached by the arrows and a click. agent-tui gains Pane::quit_keeping and Pane::keep_on_quit for the guard's third button (ADR-504, note of 2026-10-02: the exit guard is the shell's).
  • A signal or a closed terminal sends what waits. The operator said: "I don't want to drop messages". SIGHUP, SIGTERM, SIGINT or the terminal hanging up ends the chat without the guard. Enter meant send, and closing the terminal is no recall, so each message waiting is sent then, once, as Send and quit sends it, with no retry. agent-tui gains Pane::ending, which the shell calls on those two exits only, and attend-chat makes the choice in one function, send_waiting_at_unasked_exit, so a change of choice is a one-function change.
  • No second signal cuts the ending short. A SIGHUP never forces an exit: a closing terminal sends more than one, the kernel's to the foreground group, the shell's to its jobs and tmux's to the pane's group. A second SIGTERM or SIGINT forces an exit only while the loop has not yet taken the first signal up, where the loop may be wedged. Once it has, no signal forces, so Pane::ending runs, and agent-tui's watch thread ends an exit that hangs after three seconds. The exit reports the first signal. agent-tui polls the terminal itself before it asks crossterm for input, because crossterm 0.29's poll never returns on a terminal that hung up; a hangup then ends the session as a SIGHUP does. A hangup that lands between that poll and crossterm's read still spins inside the read, and the watch thread ends it at half a second without Pane::ending.
  • A forced exit runs the application's hook first (#1240). Every exit without Pane::ending goes through one path in agent-tui: the watch thread's limit before the loop takes a signal up, its limit after, and a second SIGTERM or SIGINT, which the handler hands to the watch thread. That path runs the hook the application set with agent_tui::on_forced_exit, then ends the command's process group, restores the terminal with no lock the loop could hold, and exits. A signal that comes while the hook runs ends the process from the handler. The hook runs on the watch thread while the loop may be wedged, so it writes files from state the application noted and waits on no lock without a bound. attend-chat's hook keeps what it noted, as its panic hook does.
  • A recall that shows another view parks the draft. The operator approved the switch of view for the recalled message only. A draft in the box of the view being left becomes a draft entry of that view, and it comes back into the box when that view is shown with the box empty. The exit guard names a parked draft, and every exit but D keeps it.
  • Nothing typed is lost unsaid. On every exit the chat either sends what was typed, keeps it, or names it on the button that drops it. A message that cannot go at a hangup or a signal, each parked draft and the draft in the compose box are each written to a file of their own in $XDG_STATE_HOME/attend-chat/unsent/, by a temporary file and a rename. The file names the view the text was written in, its route, its label, and whether Enter held it. Send and quit keeps the drafts the same way. A panic and a forced exit keep what the chat noted, which follows every change: it is noted after each key, paste, frame and tick, around each send and as each text is kept, and cleared once the ending or Send and quit has kept what it keeps, so neither keeps a text that was sent or kept already. A text being sent when the chat ends is kept marked sending: the forced exit puts the terminal back first, waits up to a second for a send to finish so it can tell, and exits once the keeping has had 3 seconds, so a write that blocks never holds the exit, and a text it still cannot tell about, or one a panic inside the send leaves, is restored marked may have been sent, which nothing sends by itself. The next chat claims each file by taking an flock on it and renaming it to .claim.<pid>.<name>, and holds the lock while it runs, so two chats starting together never restore one file twice. A claim is live only while its lock is held, whatever pid its name holds, so a pid reused by another process never hides a file. A claim whose lock cannot be tried is named on the status line and left in place. Each file names the chat that wrote it and the kept files whose text it carries on. A file whose text another holds whole, for the same view and route, is removed as a copy only when one chat wrote both or one carries the other on; two chats that each kept the same words keep a file each, and both come back. A copy cut short of a text still kept whole is removed, and when that copy was being sent the whole text is kept again marked sending. The newest draft whose view is still there opens in that view's compose box. Every other text is an entry in the feed, marked not sent or draft, that Esc or a click recalls into its own view, and a draft whose view is gone says so on the status line. Nothing sends a restored entry until the operator recalls it and presses Enter. A claimed file is removed only once its text has been sent, held again or kept again by an exit; a chat that ends any other way leaves it claimed by a process that has gone, and the next chat claims it again. A file that cannot be read stays where it is and is named on the status line. A temporary file left by a crashed write is restored when it holds a whole text, and as a draft marked draft, cut short when it is cut short, since it is the only copy; only one with no text in it is removed. An earlier build's single file put aside while it is moved into the directory goes back when the directory cannot be made, and one a crash left aside is moved in by the next chat. Status lines put the reason before the path, and the restore line puts may have been sent first, so an 80-column line keeps them, and the exit guard wraps a long note instead of cutting it. With drafts and no message waiting, such as after a Send and quit whose message went and whose draft could not be kept, the guard offers Quit, keep the drafts (k), so a draft can always be kept rather than dropped. Only Quit and discard all (D) drops typed text, and its label says so; a restored entry the operator never recalled stays in its file.
  • A countdown off screen is on the status line (2026-11-01). The operator approved it after a held message's header scrolled out of the three feed rows an 80x11 pane has. Whenever a countdown's header is outside the feed's visible rows, for a short pane, a feed scrolled back or a view whose feed shows nothing waiting, the status line counts down after any fresh result: sending in 4s → #open, or with several waiting the soonest and the count, 2 waiting, next in 3s → #open. While the box has the keyboard it adds · Esc recall, and the footer leaves its Esc recall out. It counts only the countdowns whose headers are out of view and names the soonest of those: with one header in the feed and another out of view it reads 1 more waiting, next in 4s → #deploy, so no countdown is on screen twice. Nothing more is drawn while every countdown header is in view. The countdown's own tick redraws it.
  • Send now takes the queue. Ctrl+Enter and Ctrl+X Ctrl+S send the draft at once after the message waiting for its destination, joined, as Claude Code's chat:sendNow sends the queued messages and the draft; with an empty box they send every message waiting.