PR #25313: feat(discord): add thread_require_mention for multi-bot threads

• Repository: NousResearch/hermes-agent
• Author: simpolism
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/25313

Description (problem / solution / changelog)

What does this PR do?

Adds opt-in discord.thread_require_mention config (env: DISCORD_THREAD_REQUIRE_MENTION), default false so existing behavior is unchanged. When set to true, threads are gated the same way channels are — the bot no longer auto-responds to non-mentioned messages in a thread just because it has previously participated. Explicit @mention is the only trigger when enabled.

This fixes an active footgun in multi-bot threads. By default, once Hermes joins a thread, it auto-responds to every message in that thread without needing further @mention — fine for one-on-one conversations, but in shared multi-bot threads (e.g. a research Discord with several agents), every other bot also fires on every message you send to any one bot, burning credits and spamming the channel. Author has hit this personally; not hypothetical.

The change is deliberately conservative — add the knob, keep the default — so existing 1:1 Discord deployments behave exactly as they do today.

Related Issue

Fixes #25312

Type of Change

• ✨ New feature (non-breaking change that adds functionality)

Changes Made

• gateway/platforms/discord.py: new _discord_thread_require_mention() helper (config.extra → env → default false), mirroring the existing _discord_require_mention() shape. The in_bot_thread shortcut in _handle_message now ANDs with not _discord_thread_require_mention() so the shortcut is suppressed when the new knob is enabled.
• gateway/config.py: yaml→env bridge for discord.thread_require_mention, mirroring the existing require_mention bridge two lines above. Without this, config.yaml settings wouldn't reach the helper at runtime — same pattern, same precedence (env wins over yaml).
• hermes_cli/config.py: add thread_require_mention: False to DEFAULT_CONFIG['discord'].
• tests/gateway/test_discord_free_response.py:
  • 4 new tests covering: default behavior (in-thread shortcut still works), enabled behavior (mention required in threads), enabled+mentioned (mention still passes through), and yaml-via-config.extra path.
  • Fixture cleanup for the adapter fixture — clears DISCORD_* env vars at fixture entry. Found in development: existing tests in this file are environment-fragile (a contributor with DISCORD_THREAD_REQUIRE_MENTION=true set in their shell sees test_discord_bot_thread_skips_mention_requirement fail). Adding the existing test's needed env vars to the fixture's cleanup list makes the whole file robust to shell environment state.
• tests/gateway/test_config.py: 2 new tests for the yaml→env bridge — one covering apply-from-yaml, one covering env-precedence-over-yaml (matching how the existing require_mention bridge works).
• website/docs/user-guide/messaging/discord.md:
  • New DISCORD_THREAD_REQUIRE_MENTION row in the env-var table
  • New thread_require_mention entry in the YAML example
  • New #### discord.thread_require_mention prose section with the multi-bot rationale and a code example
  • Cross-link from the auto_thread section pointing at the new knob

How to Test

Unit tests (6 new, all impacted files green):

pytest tests/gateway/test_discord_free_response.py tests/gateway/test_config.py -q

(70 passed locally.)

Manual — multi-bot thread reproduction:

1. Configure two Hermes-style bots in the same Discord server, both with discord.require_mention: true.
2. Open a thread, @mention Bot A. Bot A responds in the thread.
3. @mention Bot B in the same thread. Both bots respond — A because it's "already in the thread," B because it was mentioned. ← the footgun.
4. Set discord.thread_require_mention: true on both bots (or via DISCORD_THREAD_REQUIRE_MENTION=true). Restart gateway.
5. @mention Bot B again. Only Bot B responds.

Or for a quick env-only check on one bot:

export DISCORD_THREAD_REQUIRE_MENTION=true
# restart gateway
# in an existing bot-thread, send "hello" without @mention
# expected: bot stays silent (was: bot replies)

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits
• I searched for existing PRs — no duplicate
• My PR contains only changes related to this feature (including the fixture-cleanup that the new test would otherwise depend on being clean)
• I've run impacted test files; all pass
• I've added tests — 6 new tests covering helper, gating logic, yaml→env bridge, env precedence
• I've tested on my platform: Ubuntu 24.04

Documentation & Housekeeping

• I've updated relevant documentation — website/docs/user-guide/messaging/discord.md updated in three places (env-var table, YAML example, new prose section + cross-link)
• cli-config.yaml.example — the example file doesn't currently have a runtime discord: settings block (settings live in env vars), so following the existing pattern: documented in website docs, not example yaml. Happy to add an example block if preferred.
• CONTRIBUTING.md / AGENTS.md — N/A, no architecture/workflow change
• Cross-platform impact — N/A, purely server-side adapter logic
• Tool descriptions/schemas — N/A

Changed files

• gateway/config.py (modified, +2/-0)
• gateway/platforms/discord.py (modified, +28/-2)
• hermes_cli/config.py (modified, +1/-0)
• tests/gateway/test_config.py (modified, +37/-0)
• tests/gateway/test_discord_free_response.py (modified, +84/-0)
• website/docs/user-guide/messaging/discord.md (modified, +17/-1)