clearQueue() silently destroys extension-delivered custom messages without returning them。

[l547319765]

What happened?

AgentSession.clearQueue() destroys messages queued by extensions via
sendCustomMessage() but does not return them, so any host that implements
"edit queued messages" as clear + replay silently loses them.

Code paths (0.85.1, same code present in 0.87.0):

• steer()/followUp() write BOTH the _steeringMessages/_followUpMessages
  string lists AND agent.steer()/followUp() — so user-queued text is
  returned by clearQueue().
• sendCustomMessage(..., { deliverAs: "followUp" | "steer" }) during an
  active run calls this.agent.followUp(appMessage) directly and bypasses
  those lists.
• clearQueue() builds its return value from the string lists only, then
  calls agent.clearAllQueues() (void) — custom-role AgentMessages are
  destroyed with no snapshot, no return, no event.

Note the split is entry-path based, not role based: pi.sendUserMessage()
(extension origin, user role) routes through prompt({ streamingBehavior })
and IS returned, while pi.sendMessage() (custom role) is not.

Steps to reproduce

Verified by source inspection; concrete sequences:

1. SDK: start a streaming run; while streaming, call
   sendCustomMessage({ customType: "x", content: "y" }, { deliverAs: "followUp", triggerTurn: true });
   then call clearQueue() → the custom message is destroyed, the return
   value does not contain it, and nothing is emitted.
2. TUI: install an extension that delivers background notifications via
   sendMessage({ deliverAs: "followUp" }) mid-run (e.g. a subagent
   orchestrator); when a notification is queued, use the dequeue key to
   edit queued messages → the notification is silently dropped and the
   parent model is never woken.

Affected surfaces: TUI restoreQueuedMessagesToEditor, RPC clear_queue
(#8432), and SDK embedders that clear + requeue to implement queue editing.

Expected behavior

clearQueue() should not silently destroy messages it doesn't report. Any
one of these would unblock hosts (not asking for the full queue API from
#9174):

1. return everything destroyed, including custom-role entries (structured:
   customType/content/details), so hosts can requeue via sendCustomMessage; or
2. clearQueue({ userMessagesOnly: true }) leaves extension messages in the
   agent queues; or
3. minimally, emit an event/diagnostic when non-user messages are dropped.

Version

0.85.1 (verified by source inspection; same code on main / 0.87.0).

[github-actions]

This issue was auto-closed. All issues from new contributors are auto-closed by default.

Maintainers review auto-closed issues daily and reopen worthwhile ones. Issues that do not meet the quality bar in CONTRIBUTING.md will not be reopened or receive a reply.

If a maintainer replies lgtmi on one of your issues, your future issues will stay open. If a maintainer replies lgtm, your future issues and PRs will stay open. The command must be at the start of the reply (optionally after one or more @username mentions) or at the end.

See CONTRIBUTING.md.

[l547319765]

Note per the contribution guide: this report was drafted with AI assistance, then verified by me line-by-line against the installed 0.85.1 source. I've worked around it host-side, so no PR planned from me unless you'd rather have one.

[sakurahello1]

I’ve prepared a small fix for this issue. To keep the behavior change limited, I chose option 2 proposed above: clearQueue({ userMessagesOnly: true }) takes queued user messages back for editing while leaving custom messages in their original steering or follow-up queues.
The TUI uses this mode when restoring queued text to the editor. The existing no-argument clearQueue() still clears everything, and RPC callers can opt in to the new behavior.
Would this approach be acceptable? If so, I’d be happy to submit a PR.

[l547319765]

Agreed — option 2 looks like the right scope. Keeping the no-argument
clearQueue() behavior unchanged makes it a safe, opt-in change.