feat(discord)!: scope free_response_channels to mention gating only

[zucram]

What this is

A proposal to change a deliberate design decision, not a bugfix. The branch was originally titled fix(discord), which misrepresented it — apologies for the noise. Retitled and rewritten.

free_response_channels currently skips auto-threading. That is intentional: 93fe4b3 folded is_free_channel into skip_thread on purpose, and #12728 then documented it explicitly, noting the behavior "was intentional but never documented, causing user confusion." This PR argues the intent should change. If you disagree, closing it is a perfectly reasonable outcome and no rework is wasted.

Why change it

free_response_channels decides two unrelated things:

1. May the bot reply without an @mention? (mention gating)
2. Where does the reply go — inline or in a thread? (routing)

Consequences of coupling them:

• An operator cannot express "mention-free chat, but still thread each conversation." There is no configuration that produces it. The only way to get threading is to give up mention-free replies.
• The threading rule is non-local. auto_thread and no_thread_channels are where a reader looks to answer "does this channel thread?", and both can say yes while a third setting silently overrides them.
• Two settings now do the same job. no_thread_channels already exists and is documented as the threading opt-out.

After this change, threading is governed only by auto_thread + no_thread_channels, and no_thread_channels is the single escape hatch.

To be precise about the scope: this is not a new capability for unmentioned messages. With require_mention: false and auto_thread: true, ordinary channel messages already auto-threaded. free_response_channels was the one place that opted out.

Unchanged: voice-linked text channels and reply-type messages still skip threading, and DISCORD_HISTORY_BACKFILL's free-response exemption is untouched — that one is about the mention gap, not routing.

Breaking change

Channels in discord.free_response_channels / DISCORD_FREE_RESPONSE_CHANNELS now auto-thread instead of replying inline. Anyone relying on the documented behavior will see a thread per conversation where they previously saw inline replies.

Migration: add the same channel IDs to discord.no_thread_channels / DISCORD_NO_THREAD_CHANNELS.

discord:
  free_response_channels: [1234567890]   # no @mention needed (unchanged)
  no_thread_channels: [1234567890]       # add this to keep inline replies

The commit is marked feat(discord)!: with a BREAKING CHANGE: trailer. If you would rather this land behind an opt-in flag than as a default change, say so and I will rework it that way.

Changes

• plugins/platforms/discord/adapter.py — drop or is_free_channel from the skip_thread gate; update the comment to describe the new rule.
• Docs — the previous revision of this branch shipped code that contradicted its own docs. Now updated in six places across website/docs/user-guide/messaging/discord.md, configuration.md, reference/environment-variables.md and cli-config.yaml.example, including a migration note under discord.free_response_channels. The zh-Hans translations asserted the same behavior and are updated to match.
• Tests — test_discord_free_response.py::test_discord_free_response_channel_skips_auto_thread (added by 93fe4b3) asserted the old behavior and failed on the previous revision of this branch. Replaced with the inverse assertion, plus new coverage for the migration path (free-response + no_thread_channels → inline).

Validated

Run on Linux, Python 3.11.15, discord.py 2.7.1, in an isolated venv.

• scripts/run_tests.sh tests/gateway/test_discord_channel_controls.py tests/gateway/test_discord_free_response.py -q → 2 files, 29 tests passed, 0 failed
• Full Discord surface, tests/gateway -k discord, per-file isolation → 275 passed, 2 skipped, no failures attributable to this change.
• ruff check . (the blocking lint job) → All checks passed
• ascii-guard lint --exclude-code-blocks docs (docs-site-checks) → 401 files, 0 errors
• npm run build:fast (Docusaurus, en) → success; the only broken links reported are the pre-existing /docs/llms.txt and /docs/llms-full.txt, unrelated to these pages.

Not run: the full suite, Windows/macOS, and a live Discord server. This touches one boolean in a routing gate, so the risk is concentrated in the config semantics rather than the platform, but a maintainer sanity-check against a real server before merging would be sensible.

🤖 Generated with Claude Code