feat(plugins): add four extension hooks for plugin-directed core behavior

[TurgutKural]

Summary

Add four narrow, fail-open plugin hooks so user-installed plugins (~/.hermes/plugins/) can override or veto specific core behaviors without patching core files.

Motivation

Several open PRs fix real bugs by patching core internals that the plugin system cannot reach:

PR	Problem	Core file patched
#72549	TRUNCATE checkpoint tears pages under SIGTERM race	hermes_state.py
#62701	Fuzzy repair silently substitutes MCP tool names	agent/agent_runtime_helpers.py
#61499	Nous delegation bypasses runtime JWT auth	tools/delegate_tool.py
#58512	Compression runs under stale context-engine binding	agent/conversation_compression.py

Rather than carrying fork-specific patches across every upstream rebase, this PR exposes narrow hook points that let a plugin implement the same fixes without touching core files.

Hook contracts

All hooks are fail-open: no plugin loaded → original behavior preserved exactly. Each call site wraps invoke_hook in try/except; a misbehaving plugin cannot break the core.

pre_db_checkpoint

Fired before WAL checkpoint in SessionDB.close() and all pre-VACUUM paths (3 call sites).

• Kwargs: context: "close" | "vacuum", default_mode: str
• Return: {"mode": "PASSIVE"} to override the checkpoint mode; anything else keeps the default.
• Enables: fix(state): use PASSIVE WAL checkpoint in close() and pre-VACUUM paths (#45383) #72549 as a plugin — force PASSIVE to prevent page-tear under SIGTERM races.

pre_fuzzy_repair

Fired before the fuzzy-match fallback in repair_tool_call().

• Kwargs: tool_name: str, valid_tool_names: set[str]
• Return: {"skip": True} to suppress fuzzy matching for this tool name.
• Enables: fix(agent): avoid fuzzy repair for MCP tool names #62701 as a plugin — skip fuzzy for mcp__* names where substitution changes semantics.

pre_delegation_credentials

Fired at the top of _resolve_delegation_credentials() before any built-in resolution.

• Kwargs: cfg: dict, parent_provider: str|None, parent_model: str|None
• Return: a full credential dict (must contain "provider" key) to short-circuit; None falls through.
• Enables: fix(delegation): resolve Nous auth before direct endpoint #61499 as a plugin — resolve Nous JWT credentials before the direct-endpoint path.

pre_compression

Fired just before context compression begins.

• Kwargs: agent, session_id: str, message_count: int
• Return: {"skip": True, "reason": str} to veto compression for this tick; side-effect hooks (e.g. rebinding a shared context engine) may run without returning.
• Enables: fix(compression): rebind context engine before compaction #58512 as a plugin — rebind a shared LCM engine to the host session before compress.

Changes

File	Change
hermes_cli/plugins.py	Add four hooks to VALID_HOOKS with docstrings
hermes_state.py	Fire pre_db_checkpoint in close() and pre-VACUUM
hermes_state_search.py	Fire pre_db_checkpoint in optimize-storage VACUUM
agent/agent_runtime_helpers.py	Fire pre_fuzzy_repair before fuzzy fallback
tools/delegate_tool.py	Fire pre_delegation_credentials at function entry
agent/conversation_compression.py	Fire pre_compression before compression starts
tests/hermes_cli/test_extension_hooks.py	26 tests covering all four hooks

Validation

• pytest tests/hermes_cli/test_extension_hooks.py → 26 passed
• pytest tests/test_wal_checkpoint_strategy.py tests/run_agent/test_repair_tool_call_name.py tests/hermes_cli/test_plugins.py tests/tools/test_delegate.py::TestDelegationCredentialResolution tests/run_agent/test_message_sequence_repair.py → 95 passed
• python -m py_compile on all six modified files → OK
• Pre-existing failures (No module named 'openai') confirmed identical on unmodified upstream/main — not caused by this change.

Design notes

• No new middleware kinds — these are observer-with-return hooks, not request-rewriting middleware. The existing invoke_hook contract (list of non-None returns) is sufficient.
• Lazy imports — every call site uses from hermes_cli.plugins import invoke_hook inside the function body, matching the existing pattern in hermes_state.py (which already lazy-imports from hermes_cli). No new import cycles.
• Copy-on-write semantics preserved — no hook mutates its input kwargs. The delegation hook returns a new dict; the checkpoint hook returns a mode string; the fuzzy hook returns a skip flag.
• AGENTS.md compliance — no new core tools, no new env vars, no cache-breaking. The hooks fire at points that are already per-operation (checkpoint, repair, credential resolution, compression), not per-API-call.

[teknium1]

Thanks for proposing a plugin-surface alternative to the four linked core patches. The target behaviors remain live on current main: agent/agent_runtime_helpers.py:2849 still has unconditional fuzzy fallback, hermes_state.py:2542 and :8322 still issue fixed TRUNCATE checkpoints, tools/delegate_tool.py:3500 has no pre-resolution interception, and agent/conversation_compression.py:1759 invokes the compressor without a pre-hook.

Problems

• hermes_state.py’s proposed mode handling accepts every {"mode": ...} value and interpolates it into PRAGMA wal_checkpoint(...). That contradicts the documented contract that anything except the supported override keeps the default; an invalid mode instead makes the checkpoint fail. The identical parsing appears in the proposed hermes_state_search.py hunk.
• tests/hermes_cli/test_extension_hooks.py:165 and :196 permit the vacuum tests to pass without firing a hook or executing a checkpoint. They also do not cover the modified SessionDB.vacuum() path.
• tests/hermes_cli/test_extension_hooks.py:450-502 tests dispatcher return values rather than compress_context(), so it does not prove the veto branch avoids compressor execution and releases its lease.

Suggested changes

• Validate checkpoint modes against an explicit allow-list and retain TRUNCATE on every invalid result.
• Add deterministic path-level checkpoint tests plus a real compression-veto integration test.

Automated hermes-sweeper review.