Queued-message ordering is undocumented and appears LIFO in practice

Summary

When a user sends multiple messages while the agent is mid-turn (e.g. while a tool call is running), Claude Code queues them and surfaces them to the agent. In practice the agent processes the most recent prompt as the active turn-driver and treats the prior queued message(s) as a "user sent a new message while you were working" system-reminder. This produces LIFO-flavored behavior from the user's perspective: the newer message gets primary attention, the older one gets folded in as side-channel context.

Repro

1. Send a substantive prompt that triggers a long-running tool call (e.g. an Agent subagent dispatch or a long Bash command).
2. While the tool call is running, send a second message (message A).
3. Before the agent responds, send a third message (message B, e.g. a /slash-command).
4. Observe how the agent orders its response: in my session it addressed message B first as the active turn, with message A absorbed into the same response via the new-message system-reminder.

Expected

Either:

• Documented ordering (FIFO would be the principle of least surprise — typed first = answered first), OR
• A configurable knob (settings.json, env var, or /config) to choose ordering, OR
• Per-turn UI affordance to confirm/reorder before the agent processes them.

Actual

No documented ordering. No configuration option. The agent decides.

Why this matters

When users queue messages in dependency order ("do X" → then "actually also do Y first"), LIFO matches intent. When they queue in priority order ("urgent: do A" → then "also when you have time: B"), FIFO matches intent. Without documentation or configuration, behavior is unpredictable across turns and across model versions, and users can't develop reliable habits for queueing work.

Docs reviewed (no ordering spec found)

• CLI Reference
• Settings
• Hooks Reference

Asks

1. Document the intended ordering (FIFO/LIFO/agent-discretion) in the CLI reference.
2. Consider exposing a messageQueueOrder: "fifo" | "lifo" setting in settings.json.

Environment

• Claude Code CLI on macOS (Darwin 25.4.0)
• Model: Claude Opus 4.7