Typing Into a Busy Agent: Prompt Readiness, Type-Ahead and Idle-Gated Commands
Executive Summary
Zylos runs AI coding agents — Claude Code, Codex CLI — inside terminal multiplexer sessions, and a dispatcher process delivers both ordinary chat messages and control commands by typing them into the pane, the same way a human would. This works well for ordinary prompts meant for the task in progress: an agent mid-task can read a new line of input and fold it into what it's doing. It works badly for commands like /clear or /exit, which are only interpreted as commands when they land on an idle prompt. Typed while the agent is mid-turn, that same text is either queued for later or — worse — swallowed as an ordinary chat message, so /clear becomes a request to clear something rather than an instruction to reset the session.
The fix is not "always wait for idle." That would needlessly delay steering prompts the agent could have folded into the current turn, and for an agent, delay has a real cost: the context keeps growing until it hits auto-compaction, discarding detail the task needed. The fix is to recognize that every signal has an effect condition — the receiver state required for that signal to do what the sender intended — and to gate delivery on that specific condition, not on one global rule.
This article surveys how interactive CLIs, terminal emulators, and concurrent systems already solve pieces of this problem — type-ahead buffering, OSC 133 semantic prompt marks, tmux's monitoring hooks, Erlang's selective receive — and distills design guidance: classify each signal by its effect condition, let the process that knows a step finished enqueue the follow-up itself (while the receiver side still dispatches it only at a ready prompt), prefer structured readiness signals over screen-scraping, and prefer a cooldown/re-check loop over ack-deadline-retry machinery, with an operation/generation guard so a late retry cannot clear work that started after it was issued.
The Core Problem: Two Kinds of Signal, One Delivery Pipe
When a dispatcher injects keystrokes into a pane (via tmux send-keys or a paste buffer), it is really sending two different kinds of signal through the same pipe. Content signals — ordinary user messages — split by which turn they are meant for. Content that steers the current turn (a correction, an extra constraint, a missing fact for the work in progress) doesn't depend on the receiver's execution phase; an LLM agent can read a new line of context whether it's mid-reasoning or waiting at a prompt, so delivering it immediately is better than holding it. Content meant for the next turn, or for after a reset, is different: its effect condition is that boundary. Codex CLI's docs draw exactly this line — "Press Tab while Codex is working to queue a follow-up prompt, slash command, or shell command for the next turn. Press Enter while Codex is working to inject new instructions into the current turn" (Codex CLI developer commands docs) — and the reporter of openai/codex issue #26574 queues /clear, A, /clear, B expecting "A in one fresh chat and B in a second fresh chat". A and B are plain text, but each depends on the preceding /clear having taken effect; injected into the running turn, they would bind to the wrong turn and context. That bytes are "content" does not establish their effect condition. Control signals — commands like /clear, /exit, or /compact — only mean what the sender intends when the receiver is in a specific state: idle, at a prompt, between turns. Sent mid-turn, the same bytes get reinterpreted by the receiving program as something else entirely — ordinary text to reason about, not an instruction to execute. "Control" does not by itself mean "idle-only", though, and Ctrl-C is the counterexample. Claude Code documents it as "Interrupts a running operation. If nothing is running, the first press clears the prompt input and a second press exits Claude Code" (Claude Code docs — Interactive mode), and at the tty layer it is the interrupt character — "Send a SIGINT signal. Recognized when ISIG is set, and then not passed as input" (termios(3)). Its intended effect, stopping work in progress, requires the receiver to be busy; held until idle, it would arrive exactly when there is nothing left to interrupt and would clear a draft or start an exit instead. Each control signal has its own state condition, which is why the classification below is per signal rather than per category.
This is the hazard Zylos ran into while redesigning how a long-running session rotates its context: a design that had a supervisor deliver every rotation signal only at idle looked safe, until the baseline's reasoning was traced. The prompt asking the session to write a handoff never needed idle and only lost time waiting for it; /clear needs idle because typed into a busy Claude Code pane it does not fail loudly. It gets queued or absorbed as conversational input, and the operator who sent it has no idea the command never "happened" until much later. The bug is not in the agent; it's in treating a control signal as if it had the same effect condition as a content signal.
How Interactive CLIs Already Handle "Busy" Input
Type-ahead: the oldest version of this problem
Terminal input handling has dealt with "input arrives while the receiver is busy" since before CLIs ran anything resembling an agent. The Linux kernel's tty layer buffers raw input into a flip buffer, and in canonical mode the line discipline holds a full line until Enter before handing it to the reading process — this is what lets you type ahead of a command that's still finishing, without losing keystrokes. That buffering is naive, though: it has no idea what the buffered text means, and a large enough paste can even overrun the line discipline buffer under certain kernel versions, a long-documented class of bug in n_tty (Linux kernel TTY buffer docs; LKML thread on paste overruns into readline). Line editors like GNU Readline and zsh's zle add their own edit buffer and key bindings on top, but still don't know whether the shell is ready to treat the next Enter as "run a command" versus "continue a multi-line construct" — that distinction is downstream, in the shell's own parser.
The lesson for an agent dispatcher is the same one the tty layer teaches: buffering keystrokes so nothing is lost is a different problem from knowing what the text will mean once delivered — which is the guarantee a dispatcher actually needs.
Claude Code: queued messages are not all queued the same way
Claude Code's own interactive mode formalizes almost exactly the asymmetry this article is about. Per the official docs, typing a message and pressing Enter while Claude is working queues it instead of interrupting the turn, but what happens next depends on what was queued:
"Messages: if you queue a message while Claude is running tool calls, Claude Code passes it to Claude as soon as those tool calls finish, within the same turn. … Commands and shell commands: Claude Code holds them until the turn ends, then runs them one at a time, keeping the order you queued them in." (Claude Code docs — Interactive mode)
A plain prompt is folded into the live turn at the next tool-call boundary — delivered as soon as there's a safe point, before the agent is even fully idle. A slash command or ! shell command waits for the turn to actually end. A small set of commands (/model, /effort, /fast, /status, among others) run immediately regardless, because their effect doesn't depend on turn boundaries at all.
A detailed community-filed documentation issue spells out the resulting hazard: because plain prompts are absorbed mid-turn while commands wait for the turn to end, "a message typed later can run earlier" — if you queue a ! command and then a plain prompt, the prompt runs first, "[and] nothing in the UI or the transcript indicates that the order changed" (anthropics/claude-code issue #87037). Claude Code's own queueing already produces this silent reordering inside a single interface; a dispatcher typing into the pane from outside inherits the same hazard, minus even the gray "queued" annotation a human would see.
A second, related bug shows what happens when the receiving program has no "pending command" concept at all: queuing !echo "test" or /commit while Claude was mid-task sent the literal command text to the model as a chat message instead of executing it and injecting the result — Claude had to interpret !`ls -la` as English rather than receive a directory listing (anthropics/claude-code issue #18399). This is the clearest illustration of the Zylos lesson: identical bytes mean "run this" at one receiver state and "here is a string to reason about" at another.
Claude Code also ships an escape hatch for this exact tension: a send-now key, Ctrl+Enter (or Ctrl+X Ctrl+S), added in v2.1.275, interrupts the current turn and sends all queued messages at once (later releases move running tools to the background instead of cancelling them) (Claude Code docs — Interactive mode). Forcing early delivery this way is a deliberate, visible trade of a little lost work for making the signal effective right away, the inverse of Zylos's problem, where the signal was sent but silently had no effect.
Codex CLI: an explicit key-binding for "now" vs "next turn"
OpenAI's Codex CLI exposes the same distinction through keybindings rather than queue semantics: while Codex is working, pressing Tab queues a follow-up prompt, slash command, or shell command for the next turn, while Enter injects new instructions into the current turn (Codex CLI developer commands docs). The choice is the sender's, and it is per message: the same plain text can be a steer for this turn or a prompt for the next one. A filed bug shows the queueing path isn't fully baked: queuing /clear followed by further prompts silently drops those later prompts, because dequeuing /clear tears down the chat widget the rest of the queue was attached to (openai/codex issue #26574). The reporter's use case is a reset used as a queue boundary — /clear, A, /clear, B should run A and B in separate fresh chats — while noting that pending steers "only apply to the turn that just ended" and need not survive the clear. The details differ from Claude Code's, but the shape is identical: the control signal (reset the session) needs the turn to end, the ordinary prompts queued after it need the reset to have happened, and the implementation didn't fully honor that ordering. (The issue was closed as a duplicate; it points to #19151 for the same class of behavior with queued /new. The expected behavior is the reporter's, not a documented guarantee.)
Detecting "Ready" Without Guessing
If a dispatcher is going to gate a control signal on receiver state, it needs a reliable way to know that state. There is a spectrum of techniques, from fragile to structured.
Screen-scraping and expect/pexpect
The classic approach, going back to Don Libes's original expect, is to pattern-match on the text a program prints and infer "it's at a prompt" from seeing the prompt string. pexpect's documentation and issue tracker catalog why this is fragile: the end-of-line anchor $ is nearly useless, since pexpect reads character-by-character and must instead match \r\n explicitly; a MOTD or other incidental text containing the prompt substring can trigger a false match before real output arrives; and matching too eagerly after a send() can catch the command's own echo rather than the actual response (Pexpect documentation; pexpect issue #552; pexpect issue #675). This isn't specific to pexpect — any readiness inference from raw output inherits the same ambiguity, because the "ready" signal and the ordinary output stream aren't separated.
OSC 133: a structured readiness signal
Terminal emulators converged on a better answer: have the shell emit an out-of-band marker, distinct from its regular output, at each phase transition. This is the OSC 133 "semantic prompt" protocol, originated by the now-defunct FinalTerm terminal and adopted and extended by iTerm2, then standardized in practice across VS Code's integrated terminal, Windows Terminal, WezTerm, kitty, Zellij, and Ghostty: OSC 133;A marks prompt start, OSC 133;B marks the end of the prompt and start of command input, OSC 133;C marks the start of execution, and OSC 133;D[;exit-code] marks completion, optionally with exit status (iTerm2 shell integration protocol spec; VS Code terminal shell integration docs; Windows Terminal shell integration tutorial).
This matters for the exact reason screen-scraping is fragile: the marker is unambiguous and separate from the data stream it brackets, so "the shell is ready for a command" is a discrete event, not an inference. The catch, as of this research, is that neither Claude Code nor Codex CLI emits OSC 133 sequences for its own prompt/turn transitions — a request to add them to Claude Code exists on the tracker but is closed as a duplicate with no visible maintainer commitment (anthropics/claude-code issue #22528). So today, a dispatcher driving these specific agents cannot rely on OSC 133 for agent-level readiness — only for shell-level readiness inside the pane.
tmux's own signals
tmux offers several primitives relevant to readiness detection, each with a different limitation. pane_current_command reports the foreground process name — coarse, and useless for telling an idle agent prompt from a busy one, since the name doesn't change. monitor-silence <interval> highlights a window once it has produced no output for interval seconds (tmux man page, Debian build) — a reasonable heuristic, but silence isn't idle: a long-running, quiet tool call looks identical to an idle prompt. wait-for (alias wait) is a synchronization primitive — -L/-U lock/unlock a named channel, -S signals it — letting one tmux client block until another signals readiness (tmux wait reference). It's a coordination tool, not a detector: useful once something else has already decided the moment of readiness and needs to notify a waiter, close to the "doer enqueues its own follow-up" pattern recommended below.
None of these tmux primitives gives a dispatcher a first-class "agent is at an idle prompt" signal. The agents themselves do offer one, though not on the terminal stream: Claude Code runs user-configured hooks on lifecycle events such as UserPromptSubmit and Stop (turn finished), plus a Notification hook whose idle_prompt type fires when the prompt has sat idle; Codex CLI can run a configured notify program on agent-turn-complete. A dispatcher that records these events gets turn boundaries as discrete events rather than inferences — this is how Zylos tracks busy/idle. What remains is the gap between "the turn ended" and "my keystrokes land": the state can change between the check and the send, which is why the effect condition should still be enforced as close to the receiver as possible.
Bracketed paste mode
Separately from readiness, how text is injected matters once you've decided to send it. Bracketed paste mode (\e[200~ … \e[201~) tells the receiving program a block of text arrived as a paste rather than as individually typed keystrokes — without it, embedded newlines in a multi-line payload can be read as individual Enter presses, triggering premature submission or accidental execution of a partial command (bracketed paste overview; Bracketed-paste, Wikipedia). A dispatcher injecting multi-line prompts via tmux send-keys/paste-buffer should bracket the payload the same way, so the receiving line editor treats it as one block rather than a sequence of Enters that could trigger a command mid-paste.
Analogies From Concurrent Systems
The same problem — a message is only safe to act on in certain receiver states — shows up, solved, in classic concurrency design. Erlang's selective receive lets a process scan its mailbox for a message matching the pattern it's currently willing to act on, leaving non-matching messages in the mailbox rather than acting on them out of context (Learn You Some Erlang, "More On Multiprocessing"); the process decides what's actionable right now, so the sender doesn't need to know the receiver's state. EEP-76, Priority Messages, extends this: an ordinary selective receive scans the whole mailbox to find a match, which is expensive with a long queue, so Erlang added a true priority class that jumps the queue instead of waiting to be found by pattern matching (EEP-76 — Priority Messages) — the actor-systems version of "most signals wait their turn; a few skip the line," directly analogous to Claude Code's small set of immediate commands. IRQ masking is the hardware-level version: interrupts are deferred until the CPU reaches a safe point, except for classes (non-maskable interrupts) that can't wait for one. The same pattern recurs at every layer, from silicon to chat UI.
Failure Modes
| Failure mode | What happens | Observed in |
|---|---|---|
| Control signal misread as content | /clear or !cmd typed mid-turn is absorbed as a literal chat message | Claude Code issue #18399 |
| Silent reordering | A command queued before a prompt executes after it, with no visible marker | Claude Code issue #87037 |
| Queue corruption on reset | A queued reset tears down the structure the rest of the queue depended on, dropping it | Codex CLI issue #26574 |
| TOCTOU between check and send | Dispatcher checks "idle," but the agent starts a new turn before the keystrokes land | Inherent to any poll-then-act readiness check |
| Stale duplicate control command | A retried /clear lands after new work has started and clears fresh context | Any retry loop without a no-intervening-work rule or generation guard |
| Lost/merged keystrokes | Oversized or rapid input overruns a line-discipline buffer, or lands mid-line of other in-flight input | Linux kernel n_tty paste-overrun patches |
| Starvation | A control signal waits for "idle," but the agent never becomes idle (long tool loop, retry storm) | Any idle-gated design with no escape hatch |
| Premature delivery of boundary-dependent content | A plain prompt meant for the next turn or for after a /clear is injected into the running turn and binds to the wrong turn/context | The /clear, A, /clear, B use case in Codex CLI issue #26574 (why Tab-queued prompts wait for the boundary) |
| Over-cautious idle gate | Waiting for idle delays a prompt the agent could have used immediately; the wasted time is context that keeps accumulating toward auto-compaction | General pattern in long-running agent sessions |
Design Guidance
- Classify every signal by its effect condition, not a blanket policy. A prompt that steers the current turn has the effect condition "any time the agent can read input"; a prompt meant for the next turn, or queued behind a
/clear, needs that turn end or reset to have happened first;/clear's or/exit's is "idle, at the top-level prompt"; an interrupt likeCtrl-Cneeds the opposite, "something is running", because at an idle prompt it clears input or exits instead. Gate delivery on that condition per signal type — the split Claude Code's queueing already encodes between messages and commands — not on whether the signal is "content" or "control". - Let the party that knows a step finished enqueue the follow-up. An external watcher polling the pane can only guess when a step ended. The step itself — in Zylos's case, the session writing its handoff — knows the exact moment its output is complete and should enqueue the next command itself. That removes the guesswork about handoff completion; it does not remove the TOCTOU gap at the receiver. A complete handoff file does not show that the agent's TUI is back at its top-level prompt when another process injects
/clear(the session that enqueued it is typically still finishing that turn), and another prompt can start between observing readiness and the keystrokes landing. The follow-up therefore still needs a receiver-side dispatch guarantee: a queue that holds the command until a turn-boundary event (such as Claude Code'sStophook) reports the agent idle, a dispatcher that serializes the pane so nothing else is injected between that observation and the command, and a readiness check made as late and as close to the receiver as possible. - Prefer a cooldown / re-trigger loop over ack-deadline-retry machinery. Guessing a retry deadline risks duplicate delivery; idempotent commands plus a short cooldown-then-recheck are simpler and safer — provided the recheck confirms the original command still has not taken effect and no new work has started since it was issued. A
/clearre-sent after the agent has begun a new task clears that fresh context, so each retry should carry the operation or context generation it targets and be dropped once that generation has moved on. - Prefer structured signals over screen-scraping. Use OSC 133 for shell-level readiness where available; for agent-level readiness, use the agent's own lifecycle hooks (Claude Code's
Stop/UserPromptSubmit/idle_promptnotification, Codex CLI'sagent-turn-completenotify) rather than scraping the pane, and fall back to output matching — withpexpect's documented caveats in mind — only where no such signal exists. - Make control commands idempotent, and scope what that buys. An immediate duplicate —
/cleardelivered twice back to back because the first send's effect was uncertain — is harmless only if no work intervenes between the two deliveries. A delayed duplicate that lands after a new prompt has started clears fresh context. Either guarantee that no new work can be dispatched while a control command is unconfirmed, or bind each command to an operation/generation ID (e.g. a context generation bumped on every clear and checked before dispatch) so a stale duplicate is discarded rather than executed. - Don't gate what doesn't need gating — and don't un-gate what does. A uniform idle gate reintroduces the latency cost gating was meant to avoid for content that steers the current turn — and for a context-bounded agent, that latency is context accumulating toward auto-compaction while the message waits. Content intended for the next turn or for after a reset is not in that class: hold it behind the turn or session boundary the sender asked for, as Codex CLI's Tab queue does.
Comparison Table: How Different Systems Gate Delivery
| System | Content-like signal | Control-like signal | Readiness mechanism |
|---|---|---|---|
| Claude Code | Folded into turn at next tool-call boundary | Held until turn ends; a small immediate set bypasses the queue | Internal turn-state tracking; no OSC signal exposed |
| Codex CLI | Enter injects into the current turn; Tab queues a follow-up prompt for the next turn | Tab queues a slash command for the next turn, parsed when it runs | Internal; /clear bug shows queue isn't fully isolated from UI state |
| Terminal emulators (iTerm2, VS Code, Windows Terminal, WezTerm) | N/A | N/A | OSC 133 prompt/command/output/exit markers |
expect/pexpect automation | Any send is "immediate" | Same | Regex match against raw output — a scraping heuristic |
| Erlang processes | Selective receive matches an accepted pattern | Priority messages (EEP-76) jump the scan | Receiver-side pattern match against its own mailbox |
| tmux | N/A | N/A | pane_current_command (coarse), monitor-silence (heuristic), wait-for (coordination only) |
Practical Checklist
- Ask whether a signal's effect depends on receiver state; if not, send it immediately rather than idle-gating it by default. A plain prompt meant for the next task, or for after a
/clear, does depend on it: deliver it only after that boundary. - If it does, identify the exact state required (idle at the top-level prompt for
/clear, a running operation for an interrupt likeCtrl-C— not just "quiet for N seconds") and check for that specifically. - Have the completing step enqueue its own follow-up rather than having an external poller guess when it finished — and still dispatch it only once the receiver is at its top-level prompt, with no other input injected in between. Knowing the step finished is not knowing the receiver is ready.
- Bracket multi-line payloads before injecting them, so embedded newlines can't be misread as premature submissions.
- Make every control command idempotent, and guard retries with an operation/generation ID (or block new work until the command is confirmed) so a delayed duplicate cannot land after new work has started.
- Use a short cooldown-then-recheck loop instead of ack-deadline-retry for commands whose delivery you can't directly confirm; the recheck must confirm both that the command has not taken effect and that nothing new has started.
- Prefer a structured readiness signal (OSC 133, an explicit API state field) over pattern-matching output; where none exists, anchor on exact, stable strings including line terminators and distrust the first match.
- Re-verify an agent's queueing behavior against its current docs before relying on it — this has changed across recent versions of both Claude Code and Codex CLI.
- Watch for starvation: if "idle" can be deferred indefinitely, give control commands an explicit escape hatch.
Sources
- Claude Code docs — Interactive mode (queueing semantics, send-now key, immediate commands,
Ctrl+Cinterrupt vs. clear/exit behavior) - Claude Code changelog (versioned history of queueing and send-now key changes)
- anthropics/claude-code issue #87037 — queued input ordering is undocumented
- anthropics/claude-code issue #18399 — queued messages with command syntax sent as raw text
- anthropics/claude-code issue #22528 — OSC 133 shell integration feature request
- openai/codex issue #26574 — queued /clear drops later queued prompts
- Codex CLI developer commands documentation
- iTerm2 shell integration protocol specification
- VS Code terminal shell integration docs
- Windows Terminal shell integration tutorial
- termios(3) — Linux manual page (
VINTR/Ctrl-C interrupt character) - Linux kernel TTY buffer documentation
- LKML — readline/n_tty paste buffer overrun discussion
- Pexpect documentation (pxssh)
- pexpect issue #552 — additional prompt causes incorrect matching
- pexpect issue #675 — expect not properly matching patterns
- Bracketed paste mode overview
- Bracketed-paste — Wikipedia
- tmux man page (Debian buster build)
- tmux
waitcommand reference - Learn You Some Erlang — More On Multiprocessing (selective receive)
- EEP-76 — Priority Messages

