feat: add transform_api_request plugin hook for full-payload request transformation

[raymondclowe]

Summary

Adds a transform_api_request plugin hook that fires once per API call, receiving the mutable api_kwargs dict by reference — the same dict passed to the provider client on the next line.

Unlike pre_api_request (observational, shallow-copied messages), this hook is mutative: plugins can modify messages, model, and other parameters before they reach the provider. Mutations are ephemeral — they affect only the current API call, never the persisted session DB.

Motivation

Closes #43237. See that issue for detailed rationale, use cases, and comparison to the related transform_api_message hook (#20307).

Use cases enabled:

• Context compression (Headroom, etc.) — compress full conversation context before the API call
• Security scanning — cross-message secret detection
• Provider format translation — rewrite requests between provider formats
• Cost-aware routing — inspect payload to choose cheap vs. expensive models

Changes

File	Change
hermes_cli/plugins.py	Add transform_api_request to VALID_HOOKS
agent/conversation_loop.py	Invoke hook between pre_api_request and the actual client API call, passing api_kwargs by mutable reference
hermes_cli/hooks.py	Add test-fixture kwargs
tests/run_agent/test_run_agent.py	Test that the hook receives mutable api_kwargs and can modify messages

Test Plan

• New test: test_transform_api_request_hook_mutates_api_kwargs — verifies hook receives api_kwargs, can mutate messages, metadata fields present
• Existing TestRunConversation suite — all 122 tests pass
• Existing TestPluginHooks suite — all tests pass
• No regressions in existing pre_api_request / post_api_request hook tests

Scope

~86 lines across 4 files. The integration point already exists — this adds a hook invocation in the gap between pre_api_request and the streaming/non-streaming API call.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a new mutative plugin hook (transform_api_request) to allow plugins to modify the outgoing provider request payload (api_kwargs) immediately before dispatch.

Changes:

• Registers transform_api_request as a supported plugin hook.
• Invokes transform_api_request in run_conversation with a mutable api_kwargs reference and request metadata.
• Adds a regression test covering hook invocation and payload shape.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
tests/run_agent/test_run_agent.py	Adds a test intended to validate that plugins can mutate api_kwargs before the provider call.
hermes_cli/plugins.py	Registers transform_api_request as a recognized hook name.
hermes_cli/hooks.py	Documents/example-payload update for the new hook in the hooks listing output.
agent/conversation_loop.py	Calls the new mutative hook immediately before the API request is sent.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[tonydwb]

Code Review Summary

Verdict: Approved

Looks Good:

• Adds a new mutative plugin hook called transform_api_request that fires once per API call, receives the mutable api_kwargs dict by reference, and lets plugins modify messages, model, and other parameters before the request is sent. This is a clean extension point for context compression, security scanning, format translation, and cost-aware model routing.
• Correctly documented as mutative (unlike pre_api_request which is observational and shallow-copied).
• Test verifies the hook receives api_kwargs, can mutate messages, and the mutation flows to the provider call.
• Hook registered in plugins.py, documented in hooks.py example payload.
• Only 4 files, +86/-0. Clean feature addition.

Reviewed by Hermes Agent

[teknium1]

Thanks for the focused plugin-extension proposal. Automated hermes-sweeper review found that the requested behavior is already available on current main through the existing middleware surface.

• hermes_cli/middleware.py:77 implements llm_request middleware, which accepts the complete provider kwargs and replaces the effective outgoing request from a plugin return value.
• agent/conversation_loop.py:1184 applies that middleware to api_kwargs before request observation and provider execution.
• docs/middleware/README.md:43 documents ctx.register_middleware("llm_request", ...), the full-request payload, and the {"request": ...} replacement contract.
• This was introduced by 2e0c9083db8425d6e087ba0af6024406aa513d05 (feat(middleware): add adaptive execution intercepts).

A plugin needing the proposed Headroom-style behavior can register llm_request middleware and return its transformed full request payload, so this additional mutative hook would duplicate an existing capability.