What does this PR do?

Adds thread-aware Mattermost routing with a configurable sticky-thread mode.

This change targets the case where an agent is explicitly @mentioned inside a Mattermost thread. After that first explicit mention, the thread can stay bound to the active agent so later replies in the same thread do not need another @mention.

It also fixes the thread reply payload to prefer metadata.thread_id as the authoritative Mattermost thread root when MATTERMOST_REPLY_MODE=thread, while keeping MATTERMOST_REPLY_MODE=off as flat-channel behavior.

This PR overlaps with existing Mattermost thread work in #4230 and #6617, but adds two things that are not covered there:

• a configurable MATTERMOST_THREAD_STICKY mode
• persistent active-thread ownership shared across gateway processes via a small SQLite state store

It does not try to solve the separate scenario where a user opens a brand-new child thread under an agent-authored mainline post and expects that new thread to auto-inherit the agent without a fresh @mention.

Related Issue

Related to #4221
Related to #6617

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• 🔒 Security fix
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• add gateway/platforms/mattermost_thread_state.py with a shared SQLite-backed thread ownership store
• update gateway/platforms/mattermost.py to:
  • support MATTERMOST_THREAD_STICKY
  • allow already-claimed Mattermost threads to bypass repeated mention gating
  • switch thread ownership when another agent is explicitly mentioned
  • load visible Mattermost thread transcript when a different agent first enters the thread
  • prefer metadata.thread_id over reply_to when sending threaded replies
• add Mattermost gateway tests covering sticky routing, thread ownership persistence, transcript loading, and root_id selection
• document MATTERMOST_THREAD_STICKY and clarify MATTERMOST_REPLY_MODE in:
  • website/docs/reference/environment-variables.md
  • website/docs/user-guide/messaging/mattermost.md

How to Test

1. Create a Mattermost thread and @mention an agent inside it.
2. Reply again in the same thread without another @mention and confirm the same agent continues the conversation.
3. In the same thread, @mention a different agent and confirm the new agent replies in the thread and becomes the active agent for later unmentioned replies.
4. Set MATTERMOST_THREAD_STICKY=false and confirm unmentioned follow-ups in a thread are ignored.
5. Set MATTERMOST_REPLY_MODE=thread and confirm replies in an existing thread use the correct Mattermost root_id.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: Ubuntu 24.04 (via uv run --extra dev pytest tests/gateway/test_mattermost.py -q)

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Screenshots / Logs

Targeted test run:

uv run --extra dev pytest tests/gateway/test_mattermost.py -q
56 passed in 1.76s