feat(plugins): add pre_gateway_dispatch hook for gateway-level message interception

[keiravoss94]

What does this PR do?

Adds a new plugin hook pre_gateway_dispatch, fired once per incoming MessageEvent in GatewayRunner._handle_message — after the internal-event guard but before the auth / pairing chain. Plugins may return a dict to influence flow:

{"action": "skip",    "reason": "..."}  # drop (no reply; plugin handled)
{"action": "rewrite", "text":   "..."}  # replace event.text, continue normally
{"action": "allow"}   /  None           # normal dispatch

Motivation. Several commercially relevant message-flow patterns don't fit cleanly into any single platform adapter:

• Listen-only group chats — ambient-record a group conversation but only reply when the bot is @mentioned, and open a short follow-up window where replies continue without re-tagging.
• Human handover — when a customer hits a condition the owner wants to handle personally (design discussions, refunds, complaints), silently ingest subsequent customer messages into the transcript without the bot replying, until the owner issues a takeback command.
• Profile-specific auth / rate-limit / routing policies that today require forking core.

Today these patterns require modifying _handle_message directly. With this hook they can live entirely in plugins (e.g. a gateway-policy plugin we maintain out-of-tree at https://github.com/pebble-tech/hermes-plugin-gateway-policy), making them profile-agnostic and installable via hermes plugins install.

Design choices.

• Action taxonomy is deliberately minimal (skip | rewrite | allow). Any "side effect" (silent-ingest, handover state, owner notification, etc.) is the plugin's responsibility and results in skip for the core.
• Hook runs before auth so plugins can handle unauthorized senders (e.g. customer DMs during an active handover) without triggering the pairing-code flow.
• Exceptions from plugin callbacks are caught and logged; the gateway always falls through to the normal auth chain on error. First non-None action dict wins; remaining results are ignored.
• Internal events (event.internal == True) bypass the hook entirely — they're system-generated (background-process completions etc.) and must not be gate-kept by user-facing policy.

Related Issue

No existing issue; happy to file one if preferred.

Fixes #

Type of Change

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

Changes Made

• hermes_cli/plugins.py — add "pre_gateway_dispatch" to VALID_HOOKS with inline documentation of the action contract.
• gateway/run.py — add import dataclasses; invoke the hook in _handle_message after the is_internal check and before the source.user_id is None auth chain; handle skip / rewrite / allow actions and log a structured message on skip.
• tests/gateway/test_pre_gateway_dispatch.py — new file, 5 tests covering skip, rewrite, allow, exception safety, and internal-event bypass.
• tests/hermes_cli/test_plugins.py — 2 new tests confirming the hook is registered and that action dicts are collected across multiple plugin callbacks.
• website/docs/user-guide/features/plugins.md — new row in the "Available hooks" table.

Total: ~260 additions, 1 deletion across 5 files. No existing behavior changes when no plugin registers the hook.

How to Test

1. pip install -e .[dev] (or your usual dev setup).

2. pytest tests/gateway/test_pre_gateway_dispatch.py tests/hermes_cli/test_plugins.py -q — 59 tests pass locally.

3. Register a quick plugin to see it in action:

   def register(ctx):
       def _hook(event, gateway, session_store):
           if "ignore me" in (event.text or ""):
               return {"action": "skip", "reason": "demo"}
           return None
       ctx.register_hook("pre_gateway_dispatch", _hook)

   Send a message containing ignore me via any connected platform — the gateway logs the skip and returns without replying.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits
• I searched for existing PRs — no duplicate hook proposal found
• My PR contains only changes related to this feature
• I've run pytest tests/gateway/test_pre_gateway_dispatch.py tests/hermes_cli/test_plugins.py -q and all tests pass (59 passed)
• I've added tests for my changes
• I've tested on my platform: macOS 15 (Darwin 24.6.0), Python 3.11

Documentation & Housekeeping

• I've updated relevant documentation (website/docs/user-guide/features/plugins.md)
• No new config keys (hook is purely an extension point) — N/A for cli-config.yaml.example
• No architectural docs needed beyond the plugins doc table update — N/A for CONTRIBUTING.md / AGENTS.md
• Hook is Python-only and lives in platform-agnostic gateway code — N/A for cross-platform concerns
• No tool changes — N/A for tool descriptions/schemas

Screenshots / Logs

Example log line when a plugin returns skip:

INFO gateway.run: pre_gateway_dispatch skip: reason=listen-only-buffer platform=whatsapp chat=1234567890@g.us

Made with Cursor

[teknium1]

Merged via #15050 — your commits were cherry-picked onto current main with authorship preserved in git log (f33415a, 2f0ccb8). Thanks @keiravoss94! Full PR: #15050