What does this PR do?

Fixes #12063.

MattermostAdapter.send() accepted a metadata parameter but never read it — root_id was only set when callers passed the explicit reply_to argument. The gateway delivery path at gateway/delivery.py:249-252 injects thread context via metadata["thread_id"] instead:

send_metadata = dict(metadata or {})
if target.thread_id and "thread_id" not in send_metadata:
    send_metadata["thread_id"] = target.thread_id
return await adapter.send(target.chat_id, content, metadata=send_metadata or None)

So with reply_mode='thread' and a valid target.thread_id, Mattermost silently posted top-level to the channel root. The reporter's minimal repro:

await adapter.send('chan', 'hello', metadata={'thread_id': 'root123'})
# Observed payload on main:
# {'channel_id': 'chan', 'message': 'hello'}    ← root_id missing

Fix

Resolve the Mattermost root_id once per call from both sources:

if self._reply_mode == "thread":
    if reply_to:
        root_post_id = reply_to
    elif metadata and isinstance(metadata, dict):
        md_thread = metadata.get("thread_id")
        if isinstance(md_thread, str) and md_thread:
            root_post_id = md_thread

• Precedence: explicit reply_to wins when both are present — preserves the pre-fix contract for any caller that already uses reply_to.
• Type safety: non-string / empty metadata["thread_id"] is rejected defensively (Mattermost's POST /posts would otherwise 400 on a non-string root_id).
• Multi-chunk: the resolver is hoisted out of the chunk loop so long messages carry the same root_id on every chunk.

Precedence / compat truth table

Narrow scope — explicitly not changed

send_image, send_image_file, and send_document all accept metadata but route thread context through _send_remote_file (mattermost.py:471) / _send_local_file (:509) using the same reply_to-only pattern. Those helpers have the analogous gap, but the reporter specifically scoped #12063 to send() and text-message replies are the dominant gateway delivery path. I deliberately did not sweep — extending to the file-upload path is a clean follow-up if reviewers want it bundled here. Happy to do it in this PR if that's preferred, or to open a tracking issue.

Pre-empt reviewer Q&A

Q: Why not normalize at the delivery layer so Mattermost always gets reply_to?
That would push Mattermost-specific routing knowledge into gateway/delivery.py, which is intentionally platform-agnostic. The platform adapter is the right place to reconcile its own threading semantics. Other adapters (Slack, Matrix, etc.) may handle this differently and shouldn't be forced through a shared normalizer.

Q: Is metadata["thread_id"] a stable key?
Yes — it's pinned by gateway/delivery.py:251 (send_metadata["thread_id"] = target.thread_id) and by SessionSource.thread_id across the delivery-target abstraction. Grep-verified: no other writer in the codebase.

Q: Could a malformed metadata dict crash send()?
No — metadata and isinstance(metadata, dict) guards against None and non-dict values, and isinstance(md_thread, str) and md_thread rejects None, empty strings, ints, lists, and nested dicts. Covered by test_send_metadata_thread_id_non_string_is_ignored.

Q: Multi-chunk handling?
Resolved once before the chunk loop, applied to every chunk. Covered by test_send_all_chunks_carry_root_id_from_metadata.

Regression coverage

tests/gateway/test_mattermost.py::TestMattermostSend gains 6 new tests covering the full precedence table:

• test_send_metadata_thread_id_sets_root_id — the core regression; fails on origin/main with KeyError: 'root_id'.
• test_send_reply_to_takes_precedence_over_metadata_thread_id — pins the explicit-argument-wins rule.
• test_send_metadata_thread_id_ignored_when_reply_mode_off — off-mode canary.
• test_send_without_thread_metadata_no_root_id — no-override default canary.
• test_send_metadata_thread_id_non_string_is_ignored — type safety against None / "" / int / list / dict.
• test_send_all_chunks_carry_root_id_from_metadata — multi-chunk fidelity; also fails on origin/main.

How to test

1. Focused suite:

   source venv/bin/activate
   python -m pytest tests/gateway/test_mattermost.py -q
   

   → 49 passed (43 existing + 6 new).

2. Verify tests catch the bug on origin/main:

   git stash push gateway/platforms/mattermost.py
   python -m pytest tests/gateway/test_mattermost.py::TestMattermostSend -v
   

   → 2 fail with KeyError: 'root_id'. Restore with git stash pop.

3. CI-aligned broad suite — baseline failure set intact, none in gateway/platforms/mattermost.py or tests/gateway/test_mattermost.py.

Tested on: macOS 15 (Darwin 25.5.0), Python 3.11.15.

Related Issue

Fixes #12063

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)

Changes Made

• gateway/platforms/mattermost.py: send() now resolves root_id from both reply_to (existing) and metadata["thread_id"] (new), with explicit-argument precedence, defensive type checking, and multi-chunk fidelity.
• tests/gateway/test_mattermost.py: 6 new regression tests covering the precedence truth table.

Adjacent surfaces checked

• gateway/delivery.py:249-252 — confirmed send_metadata["thread_id"] injection contract. Unchanged.
• _send_remote_file / _send_local_file — noted in "Narrow scope" above.
• Other adapters (Slack, Matrix, Telegram, Discord) — out of scope; each has its own threading semantics.

Checklist

Code

• I've read the Contributing Guide
• Commit messages follow Conventional Commits
• Searched for existing PRs — none on Mattermost adapter ignores metadata.thread_id, so gateway thread replies post to channel root #12063
• Only changes related to this fix
• Ran the CI-aligned test command and classified failures baseline-vs-change
• Added tests (6 new; 2 fail on origin/main without the fix)
• Tested on macOS 15 (Darwin 25.5.0), Python 3.11.15

Documentation & Housekeeping

• No docs changes needed — internal adapter behavior, no config-key or public API changes
• No cross-platform impact — Mattermost adapter only
• No tool descriptions/schemas touched

Notes for reviewers

• No standalone lint command is defined; CI runs python -m pytest tests/ -q --ignore=tests/integration --ignore=tests/e2e --tb=short -n auto.
• No hermes_cli/** changes — the Nix workflow should not trigger.