#12818: docs(messages): clarify message tool ordering vs inline replies

## Summary Clarifies current behavior when a turn mixes inline assistant text with a `message` tool send: channel delivery can show the `message` send before inline text from the same run. ## What changed - Added a new section to `docs/concepts/messages.md`: - `message` tool sends vs inline reply ordering - documented as **current observed behavior** (without asserting design intent) - added recommended patterns to avoid confusing ordering - Added a note to `docs/tools/index.md` under the `message` tool: - mixed-mode turns can show `message` output first - use `message` + `NO_REPLY` when a single canonical outbound message is desired ## Why Issue #11841 asks whether this ordering is intentional. Regardless of intent, users are seeing it in production and need practical guidance now. This PR documents behavior and safe usage patterns without claiming architecture intent. Closes #11841 ## Contributing checklist - [x] AI-assisted: yes (prepared with OpenClaw assistant, model: `openai-codex/gpt-5.3-codex`) - [x] Testing level: lightly tested (docs-only change; link/build/test not run for this docs PR) - [x] Confirmed understanding of change and impact <!-- greptile_comment --> <h2>Greptile Overview</h2> <h3>Greptile Summary</h3> This PR updates documentation to clarify **current observed behavior** when a single agent turn includes both inline assistant text and a `message` tool send: channel delivery can surface the `message` send before the inline text from the same run. It also recommends patterns (single output mode per turn, or `message` + `NO_REPLY`) to avoid confusing ordering, and adds a corresponding note under the `message` tool docs. These changes fit with the existing messaging/tooling model described in the docs: the `message` tool uses channel delivery paths during tool execution, while inline assistant output follows the normal reply/stream pipeline. Documenting this as “observed behavior” and offering usage guidance helps users avoid confusing UI ordering without asserting design intent. <h3>Confidence Score: 5/5</h3> - This PR is safe to merge with minimal risk. - Docs-only change; statements about mixed inline output vs `message` tool ordering match the current implementation patterns (message sends during tool execution, inline text emitted via the reply/stream pipeline). No broken links or style violations were found in the modified sections. - No files require special attention <!-- greptile_other_comments_section --> _{(3/5) Reply to the agent's comments like "Can you suggest a fix for this @greptileai?" or ask follow-up questions!} **Context used:** - Context from `dashboard` - CLAUDE.md ([source](https://app.greptile.com/review/custom-context?memory=fd949e91-5c3a-4ab5-90a1-cbe184fd6ce8)) - Context from `dashboard` - AGENTS.md ([source](https://app.greptile.com/review/custom-context?memory=0d0c8278-ef8e-4d6c-ab21-f5527e322f13)) <!-- /greptile_comment -->