feat(hooks): add message:pre_route event + multi-role-router reference hook

[ceverson70]

Summary

Closes #5143

Implements the multi-role auto-routing feature proposed in the RFC. Users talk naturally from the home session — a lightweight classifier transparently routes each message to the appropriate worker profile (code-worker, knowledge-worker, ml-worker, ops-worker) before the agent begins processing.

• gateway/hooks.py — adds message:pre_route to the documented hook events with full context spec and return-value contract
• gateway/run.py — inserts emit_collect("message:pre_route", ...) in _handle_message_with_agent after session resolution, before turn-lease acquisition; applies switch_session on decisive hook results (~27 lines, matches existing command:* pattern)
• optional-skills/multi-role-router/ — reference hook users drop into ~/.hermes/hooks/: classifier via existing auxiliary.triage_specifier slot, continuation fast-path (skips LLM on short acks), atomic meta.yaml writes, /role slash commands, config-driven role definitions with sane defaults
• tests/test_multi_role_router.py — 45 unit tests covering fast-path, role config, meta.yaml atomicity, LLM response parsing, handle() integration
• tests/gateway/test_message_pre_route_hook.py — 10 tests covering the emit_collect block in run.py (exception handling, switch_session trigger conditions, break placement)

Two bugs found during testing and fixed:

• _classify_message was not catching exceptions from _call_auxiliary_llm — exceptions would propagate through handle() to the gateway. Now caught with warning log + current_role fallback.
• CONTINUATION_RE didn't match multi-word acks ("ok thanks", "got it", "makes sense"). Fixed with proper alternation and word boundaries.

Relationship to open routing proposals

Two open issues propose routing hooks at adjacent but distinct layers:

• [Feature]: pre_gateway_dispatch action to route a turn to another profile (shared-token dynamic routing) #72942 proposes extending pre_gateway_dispatch with {"action": "route", "profile": "..."} — this fires at gateway ingress, before session auth.
• feat(plugins): add pre_agent_dispatch plugin hook #69693 proposes a pre_agent_dispatch event — this fires at the agent dispatch layer, after the session is fully resolved and a worker is selected.

message:pre_route fires between these two: after session resolution (get_or_create, delegation pinning, topic tip-walk, auto-reset) is complete, and before the turn-lease is claimed. This is a distinct layer with different semantics — session context is fully available, but the turn has not yet been committed.

The three hooks are complementary, not competing. They cover different phases of the call stack:

gateway ingress → [#72942: pre_gateway_dispatch + route action]
  ↓  session auth + resolution
message:pre_route  ← this PR (after session, before turn-lease)
  ↓  turn-lease acquired
  ↓  agent selected
agent dispatch  → [#69693: pre_agent_dispatch]

A new event name is justified because the layer is different: pre_gateway_dispatch has no session context, pre_agent_dispatch has already committed a turn, and message:pre_route sits between them with full session state but no turn commitment — which is exactly the right place to make a session-switch decision.

Note for maintainers: message:pre_route could also serve as the implementation vehicle for #72942's route action if that is preferred — the switch_session primitive it already uses is equivalent to what #72942 describes. The hook contract could be extended to accept a {"action": "route", "profile": "..."} return value alongside the existing {"decision": "switch_session", "session_id": "..."} form. This PR makes no claim on that design choice and defers to maintainer preference.

Test plan

• python -m pytest tests/test_multi_role_router.py tests/gateway/test_message_pre_route_hook.py -v — 58 tests, all pass
• ruff check gateway/hooks.py gateway/run.py optional-skills/multi-role-router/handler.py — clean
• python scripts/check-windows-footguns.py gateway/hooks.py gateway/run.py optional-skills/multi-role-router/handler.py — clean
• Existing hook events (agent:start, command:*) unaffected — no regressions in hook dispatch
• With reference hook installed: natural language message routes to correct worker profile
• multi_role_router.auto: false in config disables routing without error

Platform tested

macOS 15.5 (Apple Silicon), Python 3.11.15, Hermes v0.19.0 (cfa43f5)

Notes for reviewers

• The switch_session primitive used is the same one already called for Telegram topic binding and delegation routing — no new session APIs
• Hook ships in optional-skills/ as a reference users copy to ~/.hermes/hooks/ — zero gateway changes required to use or remove it
• Credit to the RFC authors in [Feature] Multi-Role Auto-Routing via Gateway Hooks #5143 for the contextual classifier design and the dual-logic history packing approach
• emit_collect is now wrapped with asyncio.wait_for(timeout=5.0) to bound hook execution and prevent a hanging handler from holding the turn-lease window open

🤖 Generated with Claude Code

[alt-glitch]

This was generated by AI during triage.

Related: #69693 and #72942 propose overlapping routing authority at different hook boundaries. This rebase is not a duplicate, but maintainers should choose the session-routing contract before merging.

[teknium1]

Thanks for the focused hook contract and reference implementation. The current patch needs correctness and integration work before it can provide the claimed role isolation.

Problems

• optional-skills/multi-role-router/handler.py:456 returns None for a newly selected role with no saved session. The gateway already creates the current inbound session at gateway/run.py:15527, so that first role turn stays in the existing session rather than creating isolation.
• Current main builds session context and tool session environment at gateway/run.py:15638-15641 before the proposed pre-lease insertion point. The new redirect only replaces session_entry; unlike /resume, it does not clear conversation scope or evict the cached agent (gateway/slash_commands.py:4430-4442).
• optional-skills/multi-role-router/ has no SKILL.md, but OptionalSkillSource discovers optional skills only through SKILL.md (tools/skills_hub.py:3175).

Suggested changes

• Resolve the routing-contract overlap noted for #69693 and #72942, then define the first-route session-creation behavior.
• Rework the integration around final session resolution and add an end-to-end gateway test for transcript and cached-agent isolation.
• Package the optional artifact as a valid optional skill, or relocate it to an appropriate reference-hook surface.

This is an automated hermes-sweeper review.

[teknium1]

The gateway has already run get_or_create_session() before this hook fires, so returning None cannot create a role session; it dispatches this first target-role message in the current session. Create or otherwise prepare a distinct target session here before returning a route decision, or explicitly scope the feature to previously created sessions.

[ceverson70]

Mechanical fixes are in progress (first-route isolation, agent cache eviction after session swap, SKILL.md).

One thing we can't resolve without a maintainer call: the routing-contract conflict with #69693 and #72942 flagged by @alt-glitch. We've documented the three-layer stack in the PR description (our hook sits between pre_gateway_dispatch and pre_agent_dispatch), but if the preferred direction is to extend pre_gateway_dispatch with a route action instead, we're happy to pivot.

Could we get a direction on #5143 so we know which design to finalize?

[raulvidis]

Update to my earlier note: rather than only offering the delta, I've rebuilt it properly as #78326 — your seven #74272 commits cherry-picked/rebased onto current main verbatim (your authorship intact), with my review-fix delta as one commit on top. My earlier #78269 is dead (it had re-committed your base work under my name — wrong way to do it).

The delta commit in #78326 covers what I flagged before, in case you'd rather fold it into this PR instead:

• config read via canonical load_config_readonly() (satisfies tests/hermes_cli/test_config_read_guard.py)
• classifier via async_call_llm() (triage_specifier slot) — the sync call_llm() in the current branch blocks the gateway event loop per classified message
• removed dead _update_meta_session() (expects an assistant response that doesn't exist at message:pre_route time)
• message:pre_route chat_type contract fixed to real MessageSource values (dm|group|channel|thread|webhook)
• README /role slash-command table removed (commands exist nowhere); SKILL.md description ≤60 chars; HOOK.yaml credits your original implementation

All 58 tests pass via scripts/run_tests.sh, ruff clean. Whichever vehicle maintainers prefer is fine with me — if this PR folds in the same fixes and merges first, #78326 closes.

[ceverson70]

Thanks @raulvidis for the thorough review and for standing up #78326 with the fixes properly attributed. The delta changes (async classifier via async_call_llm, dead _update_meta_session() removal, chat_type contract alignment to MessageSource values, config via load_config_readonly()) all look correct to me.

Happy to go either way — fold those fixes into this PR, or let #78326 be the merge vehicle. Whichever is cleaner for maintainers.

The blocking question remains: @alt-glitch, could we get a direction on #5143 re: the routing contract? Specifically, should message:pre_route be the canonical routing hook, or should we extend pre_gateway_dispatch with a route action per #72942? That decision unblocks both this PR and #74408 (TUI companion).

[ceverson70]

Three bugs fixed in optional-skills/multi-role-router/handler.py (commit e7f96e442):

1. _update_meta_session() never called (HIGH)
_update_meta_session() was defined and tested but never invoked from handle(), so classifier history was always empty and the prompt always showed "(no prior context)". Added a call after the decision block so each classified message is recorded in history for future classifier context. The decision block was refactored to avoid early returns inside the lock (since _update_meta_session takes its own _META_LOCK and would deadlock with a non-reentrant threading.Lock).

2. Synchronous call_llm blocks event loop (MEDIUM)
In _call_auxiliary_llm, the gateway-internal call_llm was called synchronously inside an async def, blocking the event loop. Wrapped with asyncio.to_thread() so the synchronous call runs in a thread pool instead.

3. Removed dead code CONTINUATION_PATTERNS (LOW)
The CONTINUATION_PATTERNS list was defined but never referenced — only CONTINUATION_RE / _CONTINUATION_RE are used. Removed the unused list.

All 48 tests in tests/test_multi_role_router.py pass.

[raulvidis]

Thanks for the review of the delta and for e7f96e442 — two of the three are good catches we converged on, one needs a second look:

Bug 1 (history dead) — diagnosis correct, but the fix clobbers the session map. You're right that history was never populated — and to be transparent, my #78326 delta had the same gap: I removed _update_meta_session() as dead code without replacing it, which killed the feature rather than wiring it. So good catch.

But the wiring in e7f96e442 calls _update_meta_session(role=target_role, session_id=current_session_id, ...) — and that helper writes sessions[role] = session_id. Trace a switch: the decision block correctly sets sessions[target_role] = <target session>, then _update_meta_session overwrites it with the inbound session id. Next message classified as that role reads the stale mapping and "switches" back to the shared inbound session — the isolated session is orphaned and role contexts leak together. I've landed the atomic version in #78326 (eb6435c83): history is appended inside the existing decision lock (one atomic write, no second lock, no early returns), the target role's mapping survives the switch, and there's a regression test for exactly this trace. Cherry-pickable if you'd rather fold it in here.

Bug 2 (event-loop block) — asyncio.to_thread() fixes the block, but the slot mismatch remains: the internal call still uses task="compression" while _get_auxiliary_config() reads the triage_specifier slot — a user who configures auxiliary.triage_specifier won't get that model used for classification. The #78326 delta uses async_call_llm(task="triage_specifier"), which matches the config read.

Bug 3 (CONTINUATION_PATTERNS) — adopted in the same commit.

All 61 tests pass via scripts/run_tests.sh, ruff clean. On the routing-contract question for @alt-glitch: agreed that's the blocker — +1 to whichever of message:pre_route vs. a pre_gateway_dispatch route action maintainers pick; both PRs can retarget.

[ceverson70]

Thanks @raulvidis for the thorough review — both bugs are now fixed and the branch has been rebased onto upstream/main.

Bug 1 (session-map clobber): The separate _update_meta_session() call after the decision block was writing sessions[target_role] = current_session_id, which overwrote the target role's session mapping and orphaned the isolated session. Fixed by inlining the history recording inside the existing _META_LOCK decision block — one atomic read-mutate-save, no second lock acquisition, no clobber.

Bug 2 (task="compression" vs triage_specifier): _call_auxiliary_llm() was using task="compression" while _get_auxiliary_config() reads the triage_specifier slot first. Users who configure auxiliary.triage_specifier would not get that model used for classification. Changed to task="triage_specifier" to match the config read path.

All 48 tests pass after the rebase. The _update_meta_session() function is retained (existing tests cover it directly) but is no longer called from handle() — the history logic is now inline in the decision block.