docs(adr): first-class per-platform configuration

[chaodu-agent]

ADR proposing first-class per-platform config: promote all gateway-connected platforms (Telegram, LINE, Feishu, WeCom, Google Chat, MS Teams) to top-level config.toml sections, matching [discord] and [slack], and deprecate the [gateway] catch-all.

Scope (config only)

• Per-platform top-level sections: [telegram], [line], [feishu], [wecom], [googlechat], [teams]
• Fixes ID-format mixing and per-platform asymmetry in the shared [gateway] list
• [gateway] deprecation + migration path + sender-ID formats

Split note

The trust/security decision (identity trust-none default + L1/L2/L3 trust pyramid + router gate + type changes) was split into its own ADR — #1264 (docs/adr/identity-trust-none.md) — which depends on this one. Together they close #1262.

Doc: docs/adr/first-class-platform-config.md

[chaodu-agent]

LGTM ✅ — Clean, well-scoped ADR that formalizes per-platform config promotion and deprecates the broken [gateway] catch-all.

What This PR Does

Introduces an Architecture Decision Record proposing that all gateway-connected platforms (Telegram, LINE, Feishu, WeCom, Google Chat, MS Teams) be promoted to first-class top-level config.toml sections — matching the existing [discord] and [slack] pattern — and deprecates the shared [gateway] section.

How It Works

Single new file docs/adr/first-class-platform-config.md (147 lines) documenting:

• Motivation: the current [gateway] catch-all mixes ID formats, lacks per-platform scoping, and creates asymmetry with Discord/Slack
• Decision: each platform gets its own top-level section with platform-specific credentials + unified allowed_users field
• Migration: [gateway] remains functional (with deprecation warning) for one release cycle
• Sender ID formats: concrete reference table for implementers
• Rejected alternative: [gateway.telegram] sub-sections — rejected for treating gateway platforms as subordinate

Findings

#	Severity	Finding	Location
1	🟢	Scope is correctly narrow — config only, trust/security split to #1264	PR description
2	🟢	Clear motivation with concrete examples of current brokenness (ID mixing, no per-platform scoping)	§2
3	🟢	Config examples are complete — all 8 platforms shown with realistic credential patterns	§3.1
4	🟢	Sender ID format table provides unambiguous implementer reference	§4
5	🟢	Migration path is practical — backward-compat deprecation with one release cycle grace period	§5
6	🟢	Implementation plan is concrete and well-sequenced	§6

What's Good (🟢)

• Focused scope: the split into config (docs(adr): first-class per-platform configuration #1263) and trust (docs(adr): identity trust-none default & trust pyramid #1264) makes each ADR reviewable independently — good decision
• Concrete examples: showing the broken [gateway] config alongside the clean per-platform alternative makes the value proposition obvious
• Symmetric design: [telegram] mirrors [discord]/[slack] — no special-casing, just extending an established pattern
• Rejected alternatives section clearly explains why sub-sections were discarded
• First ADR in docs/adr/ — establishes the convention for future architectural decisions
• Cross-reference to docs(adr): identity trust-none default & trust pyramid #1264 makes the dependency chain explicit

Baseline Check

• PR opened: 2026-06-30
• Main already has: [discord], [slack], and [gateway] sections in config; the pattern of per-platform allowed_users fields exists but [gateway] lumps all non-Discord/Slack platforms together
• Net-new value: Formal ADR documenting the decision to extend the per-platform pattern to all platforms, deprecate [gateway], and standardize sender ID formats. Design document only — no code changes.
• Related: docs(adr): identity trust-none default & trust pyramid #1264 (trust/security ADR) depends on this one; together they close feat(channels): default trust-none policy with UID echo for all channel adapters #1262

[howie]

Mob review of the ADR (3 independent LLM reviewers: Claude / Codex / agy)

These are suggestions — the call on what to apply is yours. Since this PR is an ADR (design,
no code yet), the findings below are about whether the design as written would hold up when
implemented. Every claim about the current codebase was verified against the tree at
upstream/main; file:line references are included so you can check each one.

Overall this is a well-structured ADR — clear Trust Pyramid, good "Rejected Alternatives", correct
fail-closed posture (get() -> DEFAULT_DENY), and ADR hygiene is right (Status: Proposed, reviewer

• tracking issue, no forged decision). The blocking items below are concentrated in one root
  issue: the chosen single chokepoint does not match how messages actually flow today.

---

Blocking concerns (strongly recommend addressing before merge)

1. AdapterRouter::handle_message() is the wrong chokepoint — live traffic never reaches it.
first-class-platform-config.md:156 (§4.3) and the §5 diagram make handle_message() the single
L3 gate. But all three reviewers independently traced the real inbound path and it bypasses that
method entirely:

• The only production caller of AdapterRouter::handle_message() is cron.rs:726.
• Discord (discord.rs → dispatcher.submit), Slack (slack.rs:1185 free handle_message fn →
  dispatcher.submit), and gateway platforms (gateway.rs → dispatcher.submit) all submit to
  the Dispatcher, which runs dispatch_batch() (dispatch.rs:600) → stream_prompt_blocks()
  (adapter.rs:647). None of them call the router's handle_message().

Consequence: if Implementation Plan step 3 ("wire trust gate into handle_message()") and step 4
("remove scattered checks") are done literally, the per-adapter checks that enforce trust today
get deleted, and the new gate sits on a path no live message traverses → a fully open bot. If a
single chokepoint is wanted, it should be dispatch_batch / stream_prompt_blocks (or the
Dispatcher::submit boundary), not handle_message(). Please update §4.3/§5/§8 to gate the actual
convergence point.

2. Unified mode breaks the per-platform trust lookup and the echo text.
UnifiedGatewayAdapter::platform() returns the literal "unified" (src/unified_adapter.rs:128),
not telegram/line/etc. A gate that keys PlatformTrustConfigs::get(adapter.platform()) (§5,
§ is_allowed) would look up [unified] — never matching [telegram]/[line] — and the echo
would tell users to add themselves to a non-existent [unified].allowed_users. In unified mode the
real platform lives in ChannelRef.platform; the ADR needs to key trust off the per-event platform,
not the adapter's static name.

3. Removing should_skip_event() exposes gateway slash commands to untrusted users.
Today should_skip_event() runs at gateway.rs:832 (and :1160 for the unified path) before
the slash-command interception at gateway.rs:999-1029 / :1295-1322. /reset and /cancel are
handled inline in the gateway loop before anything reaches the dispatcher. So if step 4 removes
should_skip_event() and the new gate is on the (unreached) handle_message(), any untrusted
sender can reset sessions or cancel running tasks. The ADR should state that slash-command handling
must sit behind the same L3 gate.

---

Important suggestions

4. The "scattered checks to remove" list is incomplete. §8 step 4 names Discord
is_denied_user() (discord.rs:2892), gateway should_skip_event() (gateway.rs:56), and the
Feishu adapter check (feishu.rs:425) — all real. But it omits Slack's inline user allowlist
(slack.rs:1224) and other per-adapter gates (Discord reaction-dispatch gating discord.rs:1241,
trusted_bot_ids/bot-message handling, allowed_channels/allow_dm/allowed_role_ids). A
removal-by-name pass would leave Slack double-gated or inconsistently gated. Please make the
inventory exhaustive (and note Feishu's L3 check currently lives in the gateway crate, which
contradicts the ADR's "gateway = L1 only" model — that's another check to relocate, not just delete).

5. The ADR doesn't actually require allowed_users to be defined (ruling #2). The migration
example (§6) preserves old behavior with only allow_all_users = true and no allowed_users.
Config structs default a missing list to an empty vec (config.rs:383/477/538) and
resolve_allow_all() (config.rs:956) treats empty list as allow-all today. To honor "every
platform must define allowed_users", the ADR needs explicit semantics (missing vs empty) and/or
startup validation that fails closed.

6. Default-flip should be a transition, not a hard cutover (ruling #5). §6 flips the default
immediately ("deployments with no allowed_users… will stop accepting messages"). Ruling #5 asks
to transition before the next GA, unless explicitly opted in. Recommend a phased rollout: a beta
release that warns when relying on implicit allow-all, then GA flips the default — so live bots
aren't silently severed on upgrade.

7. Echo-on-deny needs rate-limiting / dedupe / loop-prevention. §4.2/§5 reply to every
untrusted message via send_message(). L1 only proves the request came from the platform, not that
the user is benign — this is a spam/DoS amplification path, a presence-confirmation oracle, and (two
unconfigured bots messaging each other) an infinite reply loop. Add a per-sender cooldown / once-per
-sender guard, and consider DM-only echo (echoing a UID into a shared group leaks it and is noisy).

8. [gateway] vs first-class section precedence is undefined. §6 keeps [gateway] "functional
but deprecated" alongside new [telegram] etc. If both carry allowed_users, which wins? An
undefined merge on a security-relevant list is dangerous. Specify it (recommend: first-class section
wins; [gateway] ignored when a matching section exists; log a deprecation warning).

9. static DEFAULT_DENY won't compile as written. HashSet::new() (default RandomState) is
not usable in a static initializer (first-class-platform-config.md:230). Use LazyLock, or have
get() return Option<&TrustConfig> and treat None as deny. (agy compile-tested this.)

10. "All messages logged with sender ID + platform" (issue AC) isn't covered. The ADR only logs
on deny (§4.2/§5), and current logs use sender name, not ID (gateway.rs:836/1164,
dispatch.rs:645/817). Add an explicit logging requirement for allowed traffic too.

11. Teams sender-ID format looks inconsistent — please verify. §7 labels Teams IDs "AAD Object
ID" but the example is 29:1abc.... Current Teams code parses aad_object_id yet uses
activity.from.id as the sender id (teams.rs:32/504/530). Operators following the table may
configure the wrong identifier. (Single-reviewer finding — worth a quick confirm.)

12. Echo reliability varies by gateway platform — call out LINE. Sending to an untrusted sender
before any session exists is structurally fine (gateway.rs:231 send_gateway_reply needs only
channel_id + origin_event_id, no session). But LINE replies use a single-use, short-TTL reply
token, so a retry or any delay can make the echo fail; push delivery is a different API/quota. The
ADR's echo section should note per-platform delivery caveats.

---

Minor suggestions (nits)

• 13. is_allowed(sender_id) drops existing bot-message semantics — Discord/Slack
  intentionally skip the user allowlist for bot messages after separate bot gating
  (discord.rs:2890, slack.rs:1223). State whether the unified L3 gate preserves that.
• 14. Diagram/code mismatch: §5 box shows is_allowed(platform, sender_id) (2 args) but the
  struct method is is_allowed(&self, sender_id) (1 arg; platform is the map key).
• 15. Slack example (§4.1) adds app_token, not present in issue feat(channels): default trust-none policy with UID echo for all channel adapters #1262's example / §7 — confirm
  the canonical key name.

---

Verification: the [Critical] convergence-point finding (#1) was independently reproduced by all
three reviewers; #2 and #3 were grounded with file:line and re-checked. No findings were disputed
across reviewers.