docs(native-chat): say why /clear is refused while the agent works instead of queued

[brennanb2025]

	Files	Added	Deleted	Net
Test	0	0	0	0
Prod	1	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​3	$\color{#cf222e}{\Huge{\mathbf{−}}}$​1	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​2

Problem

In native chat, typing /clear while the agent is working is refused ("The agent is still working. Run /clear when it's done."). /compact in the same situation can wait in the queue as a card. Nothing in the code says why /clear doesn't do the same, so it reads like an oversight, and someone may build it again.

That already happened twice: #26730 and its smaller rebuild #27928 both made /clear wait in line. Both are closed. The feature needed the queue to run Orca's own work, not only hand messages to the agent, and that cost more structure than the convenience was worth for now.

What changes for users

Nothing. This is a code comment only.

Mechanism

A comment on the delivery field of the conversation-command parameters. That's where /compact opts into waiting as a card. The comment records the structural reason /clear doesn't:

• the queue only hands cards to the agent;
• a clear is host work: it stops the agent and resets its context;
• so queueing it would need the queue's drain to run host commands.

Why

It keeps the decision next to the code a future change would touch, so the next person sees the trade-off before rebuilding the feature.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: ccdd423b-4df0-4a2b-ad70-fe9f541314e0

📥 Commits

Reviewing files that changed from the base of the PR and between a1f8e64 and aea9359.

📒 Files selected for processing (1)

• src/main/native-chat/agent-session-wire/structured-conversation-command.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 7 remain after this review.

📝 Walkthrough

Walkthrough

The /compact comment now states that /clear is refused while the agent is active because queue draining does not perform the required host-side work. The parameter type and runtime behavior are unchanged.

Priority: ⬇️ Low

Merge Risk: ⚪ Minimal · up to aea93

This change documents existing behavior: /clear is refused during a live turn while /compact may be queued. No merge-blocking behavior change is identified.

Pre-merge checks · 4 · 1

Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check		The description explains the problem, user impact, mechanism, and rationale. It does not follow the repository template because it omits the required section headings and supporting details for Linked…	Complete the repository template. Add the required sections and provide the applicable issue reference, state N/A for Visual Proof with a reason, document testing or why it was not needed, complete applicable checkboxes, and address AI Disc…

Passed checks (4 passed)

Check name	Status	Explanation
Title check		The title clearly and concisely describes the main change: documenting why /clear is refused while the agent is working instead of queued.
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 1…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Description check

Explanation

The description explains the problem, user impact, mechanism, and rationale. It does not follow the repository template because it omits the required section headings and supporting details for Linked Issue, Visual Proof, Testing, AI Disclosure, Review, boundary, Notes, and Checklist.

Resolution

Complete the repository template. Add the required sections and provide the applicable issue reference, state N/A for Visual Proof with a reason, document testing or why it was not needed, complete applicable checkboxes, and address AI Disclosure and review notes.

• Fix all pre-merge checks with AI

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}