…istration

Per Council R3 close-out + operator pre-decision B + feedback-
local-first-upstream-after. Adds the Hermes-core extensions
KR-REASONING-ROUTE-THROUGH-GATEWAY will require. All changes in
our local fork on feature/phase2-upgrades. Upstream-PR
packaging waits until the route-through bucket battle-tests
these surfaces.

# Discovery findings (audit before code)

5 areas audited; 4 gaps confirmed + extension added; 1 deferred.

  1. pre_llm_call mutability     — gap (observer-only today). Added new
                                    hook pre_api_request_mutable.
  2. post_llm_call re-issue      — DEFERRED to follow-on bucket
                                    KR-HERMES-LOCAL-EXT-REISSUE.
                                    Substantial control-flow change
                                    inside conversation_loop; per §4
                                    STOP-ASK guidance for invasive
                                    extensions.
  3. context.route field         — gap (Hermes hooks carry `platform`
                                    not `route`). Threaded as `route`
                                    kwarg into 7 hook sites.
  4. Listener registration       — gap (register_platform is chat-
                                    platform shape, not background-
                                    daemon shape). Added
                                    register_background_daemon +
                                    BackgroundDaemonRegistry.
  5. Tool-list manipulation hook — gap. Added pre_tool_list_finalized
                                    in build_api_kwargs.

# Extension contracts

(a) Hook ``pre_api_request_mutable`` (VALID_HOOKS:135)
    Fires at api_kwargs construction site in conversation_loop
    (after _build_api_kwargs returns + before observer
    pre_api_request). Plugins return {"override": {...}} to
    replace api_kwargs keys before SDK call. Backward compat:
    pre_api_request observer still fires + sees the final
    post-override api_kwargs.

(b) Hook ``pre_tool_list_finalized`` (VALID_HOOKS:144)
    Fires in chat_completion_helpers.build_api_kwargs at the
    tools_for_api = agent.tools site. Plugins return
    {"override": [tool, ...]} to filter the tool list per-call
    WITHOUT mutating agent.tools (which is process-wide).
    First non-None override wins. Fail-safe: any hook exception
    → caught + logged → unfiltered tools.

(c) ``route`` kwarg threaded into 7 hook sites in
    conversation_loop.py (pre_llm_call, pre_api_request,
    pre_api_request_mutable, post_api_request, post_llm_call,
    on_session_start, on_session_end, transform_llm_output) +
    pre_tool_list_finalized in chat_completion_helpers. Sourced
    from getattr(agent, "route", "") or "". Backward compat:
    legacy CLI invocations that never set agent.route see "".

(d) PluginContext.register_background_daemon(name, startup,
    shutdown, *, periodic_task=None, shutdown_timeout=5.0) +
    BackgroundDaemonRegistry singleton at agent/background_
    daemon_registry.py. Registration-only in this bucket;
    lifecycle execution is the consumer's responsibility (Kora's
    DaemonCoordinator already implements consumer shape;
    gateway-side consumer wiring is the route-through bucket).

# Backward compatibility

  - All 17 pre-existing VALID_HOOKS entries preserved
  - All 7 pre-existing hook invocations gain a `route=` kwarg
    (additive; existing **kwargs plugins ignore it transparently)
  - register_hook contract unchanged for existing hook names
  - agent.tools is never mutated by pre_tool_list_finalized
  - 145/145 pre-existing hook tests (test_shell_hooks +
    test_plugin_llm + test_transform_llm_output_hook +
    test_transform_tool_result_hook + test_model_tools) pass

# Tests

tests/agent/test_hermes_local_extensions.py — 19 new tests:
  - VALID_HOOKS contains new entries (2 tests)
  - BackgroundDaemonRegistry: register / list / order / dup /
    by_name / periodic_task / shutdown_timeout / singleton (8)
  - PluginContext.register_background_daemon forwarder (3)
  - register_hook accepts new hook names without warning (2)
  - pre_tool_list_finalized integration: filter + no-override
    fall-through + exception fail-safe (3)
  - PeriodicTaskSpec round-trip (1)

# Documentation

kora_docs/14_research/hermes_local_extensions_2026-05-23.md
covers:
  - Discovery findings (per-surface gap analysis)
  - Per-extension contract (file:line, return semantics, fail
    handling)
  - Backward-compat assertions
  - Upstream-PR readiness checklist per extension (gates for
    when each can package into a Hermes-upstream PR)
  - Verification commands

# Regression

164/164 in-scope tests pass (19 new + 145 existing hook tests).
Full repo xdist: 9599 passed, 45 failed. 43 of 45 are pre-
existing baseline flakes; the +2 (test_panel_inventory_count_
matches_expected pin drift 34→36 + test_banner_hides_when_no_
active_alerts AlertsBanner.tsx regex drift) are pre-existing
FE-instrumentation snapshot tests unrelated to agent/ changes.

Zero failures in tests/agent/* or tests/test_*hook* —
backward compat for all existing Hermes plugin code preserved.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>