From aea93599ef8c7a6f6119e94b4d573e577c455cfc Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Mon, 12 Oct 2026 15:59:54 -0700
Subject: [PATCH] docs(native-chat): say why /clear is refused while the agent
 works instead of queued

---
 .../agent-session-wire/structured-conversation-command.ts     | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/main/native-chat/agent-session-wire/structured-conversation-command.ts b/src/main/native-chat/agent-session-wire/structured-conversation-command.ts
index ab6df634d13f..33452e2106c1 100644
--- a/src/main/native-chat/agent-session-wire/structured-conversation-command.ts
+++ b/src/main/native-chat/agent-session-wire/structured-conversation-command.ts
@@ -37,7 +37,9 @@ export function conversationCommandFailure(
 export type ConversationCommandParams = {
   envelope: AgentSessionMutationEnvelope
   command: AgentSessionConversationCommand
-  /** /compact only: wait as a card while the agent works, as a queued send does. */
+  /** /compact only: wait as a card while the agent works, as a queued send does. /clear is refused
+   *  instead for now: the queue only hands cards to the agent, and a clear is host work (stop the
+   *  agent, reset its context), so queueing it would need the drain to run host commands. */
   delivery?: 'queue-if-active'
   /** Host-local, set by the client-facing command RPC as for an ordinary send. */
   userSend?: true