feat(plugins): add pre_agent_dispatch plugin hook

[luperrypf]

Summary

Add a new plugin lifecycle hook pre_agent_dispatch that fires once per turn just before the agent processes a user message. This allows plugins to intercept, rewrite, or bypass normal agent dispatch — useful for routing, content filtering, pre-processing, and multi-agent orchestration.

Hook Protocol

A plugin's pre_agent_dispatch callback receives message, session_key, source, gateway, history, and optionally stream_callback. It returns a dict with an action key:

Action	Effect
allow / None	Normal agent dispatch (default)
skip	Drop the message silently — no reply, no agent run
route	Bypass the agent entirely; supply a pre-computed result
rewrite	Replace the message text, then dispatch normally

Changes

• hermes_cli/plugins.py: Register pre_agent_dispatch in VALID_HOOKS (24 total); add dispatch_pre_agent() shared helper with fail-closed error handling
• gateway/run.py: Integrate hook into gateway dispatch (Telegram, Discord, etc.)
• tui_gateway/server.py: Integrate hook into TUI/WebUI prompt submission
• plugins/router/: Reference plugin — pre-turn classifier for Flash→Orchestrator routing
• tests/test_pre_agent_dispatch_hook.py: 17 tests covering all actions and edge cases

Design Decisions

1. Fail-closed: Hook exceptions fall back to allow — never blocks the user
2. First-wins: First non-allow plugin return wins
3. Streaming passthrough: Optional stream_callback for progressive output during routing
4. Two call sites: Both tui_gateway and gateway use the shared dispatch_pre_agent() helper

[alt-glitch]

This was generated by AI during triage.

Related: #39751 covers lifecycle-hook execution safeguards on hot paths. This PR introduces a distinct pre-dispatch hook with rewrite, skip, and route authority; its intended dispatch contract needs a maintainer decision.

[teknium1]

Thanks for the concrete hook protocol and regression coverage. This needs contract and correctness work before it is safe to salvage.

Problems

• plugins/router/__init__.py:446 caches classification by session_key alone for 300 seconds. After a simple first turn, later complex requests in that session never classify; after a complex first turn, later requests route unconditionally.
• tui_gateway/server.py:10546 synthesizes result["messages"] without executing AIAgent. Current TUI only copies returned messages into in-memory history at tui_gateway/server.py:9267-9273; the normal agent path owns transcript persistence. Please establish and test durable persistence for routed turns.
• Main already documents pre_gateway_dispatch as the gateway routing/interception point (website/docs/user-guide/features/hooks.md:1011-1037) and explicitly says a separate UserPromptSubmit event is intentionally not provided (website/docs/user-guide/features/hooks.md:1440). The new route/bypass authority therefore needs a maintainer-approved contract, especially alongside #74272.

Suggested changes

• Make classification cache inputs message-sensitive, with alternating simple/complex regression coverage.
• Define the selected routing boundary and persistence/alternation guarantees, then cover all supported surfaces or narrow the claim.

Automated hermes-sweeper review.

[teknium1]

This cache is keyed only by session_key, so its first result controls every different message in the same session for five minutes. A simple greeting suppresses later complex routing, while a complex first task routes later simple turns. Remove this cache or include the inputs that determine classification, with an alternating-turn regression test.

[teknium1]

This bypasses AIAgent and only returns synthetic messages. The current TUI copies returned messages into in-memory history after a turn, but normal transcript persistence is performed through the agent path. Please persist this synthetic user/assistant pair through the established SessionDB path and add a resume/restart test.