feat: support explicit reply IDs in message sending tool

[PeiPei233]

The agent can send messages but cannot explicitly quote an earlier message, even though message chains already support Reply. Add an optional reply_to_message_id argument to send_message_to_user so callers can quote a known platform message ID in the target session.

Modifications

• Expose the optional string argument and document when to use the tool for an explicit reply. The description requires a real target-session platform message ID, not a history database row ID.
• Validate non-empty string IDs and prepend a Reply component to the outgoing chain. Omitted arguments retain existing behavior and cross-session permission checks remain in place.
• Reuse platform adapters' existing reply support; this does not add support to adapters that do not handle replies, or verify that a message exists on the platform.
• This is NOT a breaking change.

Example tool arguments:

{"messages":[{"type":"plain","text":"About your earlier message..."}],"reply_to_message_id":"123456789"}

Test Results

• python -m pytest tests/unit/test_message_tools.py tests/unit/test_aiocqhttp_reply.py -q: 32 passed.
• Covers explicit reply ordering and OneBot serialization, current and explicit target sessions, invalid IDs, omitted IDs, and cross-session authorization.
• ruff format . and ruff check .: passed.
• git diff --check: passed.

Checklist

• New feature discussed with maintainers in advance.
• Changes tested with verification steps and results above.
• No new dependencies introduced.
• No malicious code introduced.

Summary by Sourcery

Enable callers to quote a known earlier platform message when sending messages without changing existing sending behavior.

New Features:

• Add optional explicit reply targeting to the message-sending tool using platform message IDs.

Enhancements:

• Preserve existing message behavior and cross-session authorization while supporting reply component ordering and platform serialization.

Documentation:

• Document when to use explicit reply targeting and distinguish platform message IDs from history database row IDs.

Tests:

• Add coverage for explicit replies, target sessions, invalid and omitted IDs, serialization, and permission enforcement.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

Sourcery assessment

Approved.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

[Copilot]

🟢 Approval recommended

No unresolved review issues were identified, and focused validation and regression coverage are included.

Pull request overview

Adds optional explicit platform message-ID reply targeting to send_message_to_user.

Changes:

• Adds and documents reply_to_message_id.
• Validates IDs and prepends Reply components.
• Adds coverage for replies, validation, sessions, and permissions.

File summaries

File	Description
tests/unit/test_message_tools.py	Tests explicit replies and regression behavior.
astrbot/core/tools/message_tools.py	Implements reply ID validation and message-chain construction.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[kilisamemarisaaa]

Reviewed head 37c9796. The optional reply_to_message_id is validated as a non-empty string before constructing the outgoing chain, the Reply component is placed before user content, and the existing target-session authorization path remains unchanged. The tests cover current and explicit sessions, OneBot serialization, invalid values, omitted values, and member cross-session denial. All required Linux/Windows/macOS pytest lanes, CodeQL, Ruff/format, build, and smoke checks are green. I found no correctness blocker.