feat(plugins): propagate session context to plugin hooks

[Gerkinfeltser]

Supersedes

Supersedes #42416, which targeted obsolete lifecycle boundaries and is being closed in favor of this current-main port.

Implementation

• Forwards gateway_session_key through the current turn_context.py and resolve_pre_tool_block() paths.
• Preserves strict legacy plugin hook and command-handler signatures through signature-aware context forwarding.
• Passes live session_id separately from the stable gateway key across CLI, gateway, and both TUI command routes.
• Resolves all awaitables, including asyncio.Future, in native gateway plugin dispatch.

Local verification

• Affected seven-file run: 703 passed; three known ambient plugin-discovery failures from installed tool-slimmer.
• Scoped plugin suite: 105 passed.
• Key gateway/session-context regressions: 5 passed.
• git diff --check, compilation, and Ruff pass.

Draft status

Kept as a draft while CI and independent final review complete. The repository canonical test wrapper cannot start locally because this worktree has no required local .venv or venv.

[teknium1]

Thanks for porting this across the current lifecycle boundaries. The premise is confirmed on current main: agent/turn_context.py:521-532 and the pre-tool paths beginning at agent/tool_executor.py:454 pass the live session_id but not the stable gateway key that agent/agent_init.py:420 retains; gateway plugin commands still call handlers with raw args only at gateway/run.py:10231-10244.

Problems

• The new public context contract is undocumented. The plugin guide presently specifies Callable[[str], str | None] and “Raw args string” for command handlers (website/docs/developer-guide/plugins/index.md:788-803), while the hook reference does not list gateway_session_key for pre_tool_call (website/docs/user-guide/features/hooks.md:401-417).

Suggested changes

• Document optional keyword-only session_id and gateway_session_key for registered slash-command handlers, and document the stable gateway key on the affected hook contexts. State that raw_args remains the first positional argument and that the two identifiers have different lifetimes.

This is an automated hermes-sweeper review.

[Gerkinfeltser]

Addressed in fcbb165.\n\n- Documented optional keyword-only session_id and gateway_session_key for plugin slash-command handlers, while preserving raw_args as the first positional argument.\n- Documented gateway_session_key for pre_tool_call and pre_llm_call, including its stable gateway scope versus the live, rotatable session_id.\n- Verified with npm run build (successful; existing unrelated link warnings remain) and git diff --check.

[GottZ]

This was generated by AI during triage.

Summary

Six PRs address adjacent gaps in the plugin extension surface: #38548 and #38645 add API-server route/capability hooks, #40839 adds executable plugin-command discovery and dispatch on that stack, #58538 consolidates plugin documentation, #61127 exposes opted-in plugin tools across messaging toolsets, and #65188 propagates live and stable session context through hooks and commands.

Related pull requests

• feat(plugins): expose API server route extensions #38548 [closed] related — (+319/-6) — n/a: Earlier implementation of plugin route/capability registration, API-server mounting, capability aggregation, and tests; although closed, it remains relevant as the narrower duplicate of feat(plugins): expose API server route extensions #38645, whose diff adds stricter namespace, authentication, isolation, validation, and documentation boundaries.
• feat(plugins): expose API server route extensions #38645 related — (+1388/-6) — n/a: Adds authenticated, plugin-owned API-server routes and capability metadata with namespace and callable validation, bounded off-loop execution, redacted failures, profile isolation, tests, and public documentation. Keep open with its contributor keep_open review: the diff contains the requested callback validation and documentation; the separate non-contributor CHANGES_REQUESTED review cited unspecified TODO/FIXME/HACK markers, while the visible added lines show no such markers.
• feat(api): expose executable plugin commands #40839 related — (+2284/-7) — n/a: Stacks feat(plugins): expose API server route extensions #38645's route/capability work and adds explicit api_executable command opt-in, authenticated POST /v1/commands/{name}, matching discovery, isolation, and end-to-end tests. Consistent with the maintainer-bot keep_open verdict, the diff addresses its execution-contract and documentation findings, but the command delta should be split or rebased away from the feat(plugins): expose API server route extensions #38645 stack.
• docs(plugins): fold middleware, API-hook, and allow_tool_override coverage into the canonical author guide #58538 related — (+71/-0) — n/a: Adds middleware, per-provider-request hook, and allow_tool_override guidance to the canonical plugin author guide rather than creating a parallel document. Keep open with the contributor keep_open review because the visible diff follows its salvage path into website/docs/developer-guide/plugins/index.md.
• feat(tools): let plugin tools opt into core messaging toolsets #61127 related — (+414/-7) — n/a: Adds include_in_messaging_toolsets and carries opted-in tools through the effective platform-selection-to-tool-definition path while preserving webhook, ACP, API-server, explicit-empty, and user-disable exclusions. Keep open with the contributor keep_open review because the diff adds the requested real-path integration coverage and membership-derived assertions.
• feat(plugins): propagate session context to plugin hooks #65188 related — (+713/-25) — n/a: Propagates live session_id and stable gateway_session_key through pre-LLM/pre-tool hooks and plugin commands, preserves strict legacy signatures, handles general awaitables across gateway/TUI paths, and documents the identifiers' distinct lifetimes. Keep open with the maintainer-bot keep_open verdict; the diff implements its requested public command-handler and hook-context documentation.

Duplicates

#38548 and #38645 substantially implement the same plugin API-server route/capability extension; leave closed #38548 as the narrower duplicate of #38645. #40839 includes #38645 because it is stacked, but its executable-command delta is distinct; #58538, #61127, and #65188 are not duplicates.

Suggested consolidation

Keep #38645, #58538, #61127, and #65188 open with the concrete salvage paths represented by their current diffs and visible keep_open reviews; leave #38548 closed as a duplicate of #38645. Author action for #40839: rebase onto main, or split out the executable-command registry and POST /v1/commands/{name} delta from its #38645 foundation; no merge recommendation is supported by the recorded n/a verdicts.

Cross-PR triage: Reviewed 6 pull requests and 0 issues in this complex. Each diff was read against this issue; Assessment working set: 287 kB of PR diffs, 16 kB of issue/PR text, 12 kB of discussion (13 comments), 0 verify verdicts. verdicts reflect diff content, not PR titles. Part of an automated triage batch.

[Gerkinfeltser]

Closing this. The gap it originally targeted is largely gone and what remains is being carried by other PRs.

• Hook-side live session_id propagation (the core of the original feat(plugins): propagate session context to plugin hooks #42416 work) is already on current main: fix(plugins): propagate session_id to pre_tool_call hook from all 3 callsites #34622 was closed with sweeper:implemented-on-main, and the dispatch sites (tool_executor.py, conversation_loop.py post_api_request) pass session_id today.
• The remaining delta, stable gateway_session_key propagation plus session kwargs for slash-command handlers, is still unfixed on main, but the active work on that gap lives in fix(langfuse): prefer gateway_session_key for session grouping #71608 (langfuse session grouping) and fix(mem0): honor gateway session memory scope #75740 (mem0 session scope), both of which forward agent._gateway_session_key from the consumer side. Consolidating there keeps the surface smaller than a generic plumbing change.
• None of my own plugins consume gateway_session_key or register slash commands, so I have no standing consumer for the generic version.

This branch is also 4.9k commits behind main with merge conflicts, and half its diff now duplicates shipped behavior. If the generic capability is wanted later it can be rebuilt on current main from the salvageable parts (command-handler session kwargs, hook gateway key).