Problem or Use Case

Plugin authors who need to transform messages before they reach the LLM API currently have no clean hook point.

The existing hooks have limitations:

• transform_tool_result fires inside handle_function_call() when a tool result is first returned. It replaces the result in the in-memory messages list, which means the transformation persists to the SQLite session DB. This is fine for permanent transformations, but not for ephemeral ones (e.g., trimming verbose content for the current API call while preserving the full result for session resumption).

• pre_llm_call fires once per turn before the tool-calling loop. It receives conversation_history but: (a) it fires before the current turn's tool calls have executed, so it can't transform current-turn tool results; (b) its return value is interpreted as "context to inject into the user message", not as message transformations; and (c) if a callback mutates the list in-place, those mutations affect both the persisted messages list and api_messages.

• pre_api_request is purely observational — it receives metadata (message_count, tool_count, etc.) but not the actual messages.

The api_messages construction loop in run_conversation() (lines ~10991–11034) already implements the right pattern: it makes shallow copies of messages and applies ephemeral mutations (context injection, field stripping) only to the copies. But there is no hook there for plugins to participate.

Use cases that need this:

• Ephemeral content truncation/summarization (trade verbosity for context window)
• PII redaction before sending to third-party APIs (while retaining in local session)
• Injecting ephemeral hints or structured annotations into tool results for the current call
• Transforming provider-specific message formats without affecting the canonical conversation

Proposed Solution

Add a new plugin hook — tentatively transform_api_message — that fires for each message as it's being converted from messages to api_messages.

Hook signature

# Fired once per message during api_messages construction
ctx.register_hook("transform_api_message", callback)

# Callback receives:
def callback(
    hook_name: str,
    msg: dict,           # original message from `messages` (READ-ONLY)
    api_msg: dict,       # shallow copy being built for API (MUTABLE)
    idx: int,            # index in messages list
    session_id: str,
    model: str,
    **kwargs,
) -> None:
    ...

Behavior

• The hook is called for every message in the conversation, once per API call iteration.
• The callback receives both the original msg (for context) and the mutable api_msg (the copy being sent to the LLM).
• Modifications to api_msg are ephemeral — they affect only the current API request, not the persisted messages list.
• Return value is ignored (the hook mutates api_msg in place).
• Errors in any callback are caught and logged; the unmodified api_msg is used as fallback.

Integration point

The hook would be inserted in the api_messages construction loop in run_conversation(), after the shallow copy is made and existing ephemeral mutations are applied, but before api_msg is appended to the outgoing list (i.e., between lines ~11034 and 11035 in the current api_messages loop).

Config

No additional config needed. Like other plugin hooks, the hook is available whenever the plugin is loaded.

Alternatives Considered

1. Abuse pre_llm_call with in-place mutation + restore in post_api_request: Requires the plugin to mutate messages in-place, then restore original content before persistence. This is fragile — the persistence path has multiple exit points, and any missed restore corrupts the session DB.

2. Abuse transform_tool_result with side-channel storage: Store full results externally and always return trimmed. On session resume, a pre_llm_call hook (or session-load hook) would need to restore originals. This is complex, fragile, and couples the trimming logic to session load timing.

3. Monkey-patch run_conversation(): A plugin could monkey-patch the api_messages loop at import time. This works but is brittle across Hermes version upgrades and bypasses the hook system entirely.

The proposed hook is the natural extension of the existing api_messages copy-on-write pattern — it gives plugins the same ephemeral mutation capability that Hermes internals already use for context injection and field stripping.

Feature Type

Developer experience (tests, docs, CI)

Scope

Small (single file, < 50 lines)

Contribution

• I'd like to implement this myself and submit a PR