hermes-agent/gateway
Teknium 11310068c6 feat(plugins): pre_command observer hook + capability-gated ctx.call_mcp (#64204)
Part A — pre_command observer hook (observer-first per #64182 ground rule 3):
- New VALID_HOOKS event `pre_command`: fires when a recognized slash command
  is about to be dispatched, BEFORE the handler runs, on both surfaces:
  - CLI: cli.py process_command (right after alias resolution)
  - Gateway: gateway/run.py _handle_message cold-path canonical dispatch
- Payload: surface ('cli'|'gateway'), command (canonical), alias_used,
  args_raw, session_key, platform. Return values IGNORED in v1; a plugin
  returning a directive-shaped dict gets a debug log so future
  block/rewrite adopters are discoverable (#64231 taxonomy).
- Deliberately NOT fired on the gateway running-agent intercept path
  (/stop, /approve, busy_policy dispatch during an active run): those are
  control-plane escape hatches on an in-flight run and must stay outside
  plugin observation/veto reach.
- fire_pre_command_hook() helper never raises, so broken plugin infra can
  never break command dispatch.

Part B — ctx.call_mcp (capability-gated, default-off, ground rule 4):
- PluginContext.call_mcp(server, tool, arguments, timeout=30): synchronous,
  callable from plugin hooks/tools, routes through the EXISTING native MCP
  client machinery (tools.mcp_tool._make_tool_handler: background loop,
  trust-tier gates, circuit breaker, reconnect) — never a parallel client.
- Gate: plugins.entries.<id>.mcp_allowlist (list of server names).
  Absent key / unreadable config / non-list value => default-deny.
  Unlisted server raises PermissionError naming the exact config key.
  TODO seam left for the #64228 declared-capability model.
- Bounded: timeout clamped to 1-600s and forwarded to the MCP loop call;
  results capped at 64KB with truncation marker; stable
  {ok, result|error, structuredContent?, truncated?} envelope.

Tests (transport mocked, no live MCP servers):
- tests/hermes_cli/test_pre_command_hook.py: both surfaces fire, canonical
  alias reporting (/exit->quit, /q->queue), hook-before-handler ordering,
  control-plane exclusion, hook failure non-fatal, observer-only directive
  handling.
- tests/hermes_cli/test_plugin_call_mcp.py: default-deny (absent entry,
  unreadable config, non-list, '*'), allowlist enforced per-server,
  denied calls never touch transport, timeout forwarding/clamping,
  result truncation, error/structuredContent envelopes.

Docs: hooks.md shipped-catalog row for pre_command; plugins.md
"Calling MCP servers from plugins" section with the security note.

Closes #64204
2026-08-12 19:16:59 -07:00
..
assets chore: limit generic status phrases to long-running notifications 2026-07-05 06:29:26 -07:00
builtin_hooks
…
platforms fix(review): harden plugin gateway injection 2026-08-12 18:25:33 -07:00
relay fix(relay): stamp logical platform + relay trust on Discord interaction events (#84318) 2026-08-12 17:04:02 +10:00
__init__.py
…
agent_cache_pressure.py fix: follow-ups for salvaged PR #80795 2026-08-07 21:02:33 +05:30
authz_mixin.py fix(plugins): isolate ownership by profile 2026-08-12 19:13:32 -07:00
cgroup_cleanup.py
…
channel_directory.py fix(gateway): run channel-directory write off the event loop 2026-08-11 20:37:06 +05:30
code_skew.py
…
config.py feat(gateway): allow selective multiplex profile serving 2026-08-10 22:48:24 -07:00
cwd_placeholder.py fix(gateway): resolve terminal.cwd placeholders per backend and mount mode 2026-07-04 13:28:47 -07:00
dead_targets.py fix(gateway): add utf-8 encoding to dead target registry 2026-07-24 15:47:12 -07:00
delivery.py fix(gateway): pass encoding="utf-8" to read_text/write_text in update path (#37423) 2026-07-24 15:47:12 -07:00
delivery_ledger.py fix(gateway,tools,agent): close leaked SQLite connections in delivery, delegation, and verification ledgers 2026-07-24 15:55:08 -07:00
display_config.py fix(slack): quiet Slack display defaults — no heartbeat/busy-ack breadcrumbs in channels 2026-07-23 11:34:11 -07:00
drain_control.py feat(gateway): suppress home-channel shutdown broadcast on flagged drains (#54824) 2026-06-29 12:18:11 -07:00
hooks.py fix: handle replacement transforms after CLI streaming 2026-08-08 14:06:30 +05:30
kanban_watchers.py fix: complete kanban review lifecycle 2026-08-10 12:43:46 -07:00
lifecycle_ledger.py fix(gateway): treat pid=None lifecycle sentinel as unknown ownership in mark_exited 2026-07-28 22:41:09 -07:00
memory_monitor.py
…
message_timestamps.py
…
mirror.py refactor: consolidate gateway session metadata into state.db (#58899) 2026-07-05 14:01:03 -07:00
pairing.py fix(secrets): route authz gate and pairing allowlist reads through the profile secret scope 2026-08-02 10:02:33 -07:00
platform_registry.py fix(plugins): isolate ownership by profile 2026-08-12 19:13:32 -07:00
profile_routing.py feat(gateway): allow selective multiplex profile serving 2026-08-10 22:48:24 -07:00
readiness.py fix(gateway): close readiness-probe SQLite connection deterministically 2026-07-24 15:55:08 -07:00
response_filters.py refactor(gateway): promote autonomous silence matcher to shared response_filters helper 2026-07-26 16:55:42 -07:00
restart.py fix(gateway): defer in-band restart until active turns finish (#77184) 2026-08-03 09:57:58 +05:30
restart_loop_guard.py fix(gateway): make the restart-loop breaker see slow crash cycles (#81642) 2026-08-09 21:40:23 +05:30
rich_sent_store.py style(profile): frame comments around what the code does 2026-06-30 15:30:06 -07:00
run.py feat(plugins): pre_command observer hook + capability-gated ctx.call_mcp (#64204) 2026-08-12 19:16:59 -07:00
runtime_footer.py feat(gateway): add opt-in 'latency' runtime footer field 2026-08-03 17:16:57 +05:30
scale_to_zero.py fix(gateway): scale-to-zero gateway self-suspends via flaps socket instead of relying on Fly autostop (#84295) 2026-08-12 14:45:48 +10:00
session.py feat(gateway): allow plugins to inject session messages 2026-08-12 18:25:33 -07:00
session_context.py fix(gateway,relay): stop frozen-preview finals and dropped idle-session delegation callbacks (#82592) 2026-08-11 09:56:13 +10:00
session_stall.py feat(gateway): session activity watchdog, stall notify, compress timeout (#72424) 2026-08-02 16:16:36 -07:00
session_state.py refactor(gateway): extract the hygiene recovery gate and forward the failure reason 2026-08-06 15:04:53 +05:30
shutdown_flush.py fix(gateway): spool cap-dropped pending transcript messages instead of discarding 2026-08-09 14:08:51 -07:00
shutdown_forensics.py fix: add explicit UTF-8 encoding to all subprocess text=True calls (#53428) 2026-07-24 11:45:57 -07:00
shutdown_watchdog.py fix(gateway): detect and report unclean shutdowns via lifecycle ledger (NS-608) 2026-07-28 22:41:09 -07:00
slash_access.py
…
slash_commands.py fix(gateway): offload remaining atomic_json_write calls in async paths 2026-08-11 20:37:06 +05:30
status.py fix(gateway): self-reacquire scoped lock by PID alone 2026-08-08 13:50:08 +05:30
status_phrases.py chore: limit generic status phrases to long-running notifications 2026-07-05 06:29:26 -07:00
sticker_cache.py
…
stream_consumer.py fix(gateway,relay): stop frozen-preview finals and dropped idle-session delegation callbacks (#82592) 2026-08-11 09:56:13 +10:00
stream_dispatch.py
…
stream_events.py
…
streaming_tts_consumer.py feat(gateway): streaming TTS adapter contract and consumer (#60671) 2026-07-28 22:31:40 -07:00
systemd_notify.py fix(gateway): recover Discord websocket and event-loop stalls 2026-07-18 20:01:55 +05:30
turn_context.py fix(gateway): reap only the background processes an abandoned turn created 2026-08-02 14:23:55 +05:30
turn_lease.py refactor(gateway): drop dead degraded token field; de-churn salvage diff 2026-08-07 18:23:57 +05:30
wake.py fix(gateway): deliver kanban/delegate wake-ups to api_server sessions 2026-07-23 11:55:17 -07:00
whatsapp_identity.py
…