Summary

Add a small generic plugin-runtime seam so plugin tool handlers can receive the active live agent object during tool execution.

Problem

Today Hermes plugins can register tools, but plugin tool handlers only receive generic dispatch kwargs like task_id and session_id. They do not receive the live AIAgent, which blocks plugin-owned features that need to mutate session-scoped runtime state.

A concrete example is a plugin-first reasoning_effort tool:

• the plugin can expose schema and validation
• but it cannot actually update agent.reasoning_config without a host seam

Proposed change

Thread optional agent=self through the live agent-loop tool execution path and pass it only to plugin-provided tools.

Proposed runtime contract

Plugin tool handlers may receive extra runtime kwargs during live execution, including:

• agent
• task_id
• session_id
• tool_call_id

Handlers that want this should accept **kwargs.

Why this approach

This is a generic capability, not a reasoning-effort special case.

Compared to provider/request patch hooks, passing the agent enables a wider class of plugin behaviors:

• session-scoped runtime mutation
• cache invalidation when plugin-owned state changes
• richer introspection of active runtime configuration
• future advanced plugins that need more than request shaping

Guardrails

• Only pass agent to plugin-provided tools, not all tools.
• Keep existing built-in tool behavior unchanged.
• Document this as advanced plugin API surface.

Acceptance criteria

• Plugin tool handlers can receive agent during live agent execution.
• Existing non-plugin tool behavior remains unchanged.
• Tests prove plugin handlers can observe/mutate live runtime state through this seam.
• The change remains generic and not feature-specific.

Related

This unblocks a plugin-first implementation of a reasoning_effort tool requested by maintainers before accepting a core feature.