[DOCS] Queued input ordering is undocumented — plain prompts fold into the running turn while `!` and slash commands wait for it to end

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/interactive-mode

Section/Topic

Queued messages — execution order and which queued inputs run mid-turn vs. at turn end

Current Documentation

The interactive-mode page documents that messages can be queued, and documents one command as an explicit exception:

Available while Claude is working: you can run /btw even while Claude is processing a response. The side question runs independently and doesn't interrupt the main turn.

Nothing on that page — or elsewhere in the docs — states what happens to anything else that is queued, or in what order queued items run.

The CHANGELOG has repeatedly described this behaviour while changing it for individual commands, which is currently the only public source for it:

• 2.1.83 — "/status now works while Claude is responding, instead of being queued until the turn finishes"
• 2.1.70 — "Improved /rename to work while Claude is processing, instead of being silently queued"
• 2.1.30 — "Changed /model to execute immediately instead of being queued"
• 0.2.108 — "You can now send messages to Claude while it works to steer Claude in real-time"

Each of those presupposes a default that is documented nowhere.

What's Wrong or Missing?

Queued input does not all take one path, and the difference is not documented anywhere. The result is that queued items can execute in a different order than they were typed, silently.

Concretely, on 2.1.233:

Plain prompts queued mid-turn are absorbed into the running turn. They are converted into queued_command attachments and injected at a tool-call boundary, so the model sees them during the current turn. This is the "steer Claude in real-time" behaviour from 0.2.108.

Queued ! shell commands and queued slash commands are not. Both stay in the queue until the turn ends and control returns to the prompt, then run through the normal input path. They are excluded by two different mechanisms — a slash command is filtered out of the mid-turn drain explicitly, while a bash-mode entry simply is not a member of the allowlist of modes that become attachments (prompt and task-notification only). Same outcome, different route.

So a message typed later can run earlier. If a user queues a ! command and then queues a plain prompt, the plain prompt is folded into the running turn while the ! command waits for the turn to end. Nothing in the UI or the transcript indicates that the order changed.

This behaviour is already acknowledged by maintainers in passing. On #86816, a collaborator described the ! case directly:

Bash entries are only pulled when they would be the whole input buffer; if there is other text or other queued prompts, the shell entry stays queued (still shown as ! in the preview and still executed as shell when the turn ends)

That is an accurate description of real behaviour that appears in an issue comment rather than in the docs.

This has been reported before and never landed. Each of these is closed, and none was closed because the behaviour got documented:

• #54031 — "Queued-message ordering is undocumented and appears LIFO in practice" (closed not planned by the stale bot after inactivity, then locked; its closing comment invites a new issue, which is why this is filed fresh rather than as a comment)
• #39627 — "[DOCS] Interactive mode docs missing queued-prompt editing and slash-command interaction" (closed, stale)
• #47632 — "[DOCS] Queued-message docs omit attachment handling and focus-view visibility" (closed, stale)
• #38571 — "[DOCS] Document that /status is available immediately while Claude is responding (not queued until turn ends)" (closed)

Worth noting that #54031 guessed the mechanism and guessed wrong — it described the behaviour as "LIFO" and "the agent decides." It is neither. Ordering is decided by the harness, structurally, based on the input's mode. That misdiagnosis is itself an argument for documenting the real rule: users are reverse-engineering it and arriving at wrong models.

Suggested Improvement

Add a short subsection to Interactive mode, near the existing queued-message material, stating the rule plainly. Something along these lines:

What happens to queued input While Claude is working, you can queue additional input. Not all queued input is handled the same way: | Queued input | When it runs | |---|---| | A plain prompt | Injected into the current turn at the next tool-call boundary, so Claude can respond to it without waiting ("steering") | | A ! shell command | Runs after the current turn finishes | | Most slash commands | Run after the current turn finishes | | Slash commands marked as immediate (for example /status, /model, /rename, /btw, /goal) | Run right away, without waiting for the turn | Because plain prompts are folded into the running turn and the others are not, queued items may not run in the order you typed them. If you queue a ! command and then a prompt, the prompt is handled first and the ! command runs when the turn ends.

Two things would help beyond the table itself:

1. Name the immediate commands, or make the set discoverable. Right now the only way to know whether a given command waits is to try it. If the list is expected to keep growing, a note in /help or in each command's own docs entry would age better than a hardcoded list in prose.
2. Say it in the queue UI, not only in the docs. The preview under the prompt already distinguishes these entries visually (a ! entry renders with its !). A one-line hint such as "runs when the current turn finishes" would put the information where the decision is actually made.

Impact

Medium - Makes feature difficult to understand

Additional Context

Verified on 2.1.233 (macOS, Terminal.app) by reading the shipped binary, not inferred from behaviour alone:

• The mid-turn drain filters slash commands with typeof e.value==="string" && e.value.trim().startsWith("/") && !e.skipSlashCommands, returning early so they are never folded in.
• The attachment builder filters queued items through an allowlist new Set(["prompt","task-notification"]), which is why bash-mode entries never become attachments.
• The between-turns processor's effect returns immediately while a query is active, so nothing in the queue drains until the turn ends.
• Commands carrying an immediate flag take a separate dispatch path and bypass the queue entirely.

The same structure is present in older published builds, so this is longstanding behaviour rather than a recent change — it is a documentation gap, not a regression, and I am not asking for the behaviour itself to change.

Related: #86816 (queued ! command losing its shell mode when pulled back for editing — different code path, fixed in 2.1.234).