feat(tools): MCP elicitation handler with gateway-aware approval routing

[lgalabru]

What does this PR do?

Adds support for the MCP elicitation/create request (Python SDK ≥ 1.11) so MCP servers can ask the user to confirm sensitive operations mid-tool-call — payment authorization, OAuth confirmation, anything that previously failed closed or required local biometrics that don't exist on a server / VM / Telegram chat.

The handler routes the prompt through Hermes's existing approval system, so the confirmation surfaces on whichever surface owns the active session (CLI, TUI, Telegram, Slack, etc.) — same UX as prompt_dangerous_approval for shell commands.

The non-obvious part is the contextvar bridge. The MCP recv-loop task that dispatches incoming elicitation/create requests is a different asyncio task from the one running the agent's tool call; it doesn't inherit HERMES_SESSION_PLATFORM or any of the other session-scoped contextvars. Without bridging, every gateway session was incorrectly classified as a CLI session, hit prompt_dangerous_approval in a worker thread with no TTY, and fail-closed declined every elicitation. The fix snapshots the agent's contextvars.copy_context() on the server task right before session.call_tool, then replays it inside the elicitation handler via Context.copy().run(...) so attribution survives the task hop.

Related Issue

No upstream issue — surfaced while integrating an MCP server (pay) whose payment authorization needs a user prompt on a remote messaging surface.

Type of Change

• ✨ New feature (non-breaking change that adds functionality)

Changes Made

• tools/mcp_tool.py: ElicitationHandler class, _format_elicitation_schema_summary helper, _pending_call_context slot on MCPServerTask, contextvars snapshot around session.call_tool, owner back-reference on the handler.
• tools/approval.py: request_elicitation_consent() — dispatches to _await_gateway_decision for gateway sessions, prompt_dangerous_approval for CLI/TUI; fails closed on timeout / missing notify_cb / exception.
• tests/tools/test_mcp_elicitation.py: 15 unit tests covering form-mode accept/decline/cancel, URL-mode decline, timeout, exception fail-closed, and four regression tests for the context bridge.

How to Test

1. uv sync --extra mcp --extra dev
2. uv run pytest tests/tools/test_mcp_elicitation.py -v — 15 passed.
3. Manual end-to-end against an MCP server that uses elicitation (any MCP server speaking SDK ≥ 1.11 with elicitation/create):
   • Configure the MCP server in ~/.hermes/config.yaml under mcp_servers:
   • hermes gateway setup to wire Telegram (or any gateway platform)
   • hermes gateway run
   • DM the bot, ask the agent to invoke an MCP tool whose handler emits an elicitation
   • Expected: the approval prompt arrives back on Telegram; replying accept/decline closes the elicitation and the tool call resumes accordingly

Verified locally end-to-end against pay (an MCP server that calls elicitation/create to authorize a payment): agent message arrives via Telegram → agent calls mcp_pay_curl against a paid HTTP endpoint → pay returns 402, fires elicitation/create → handler routes the approval back to the originating Telegram chat → reply approves → curl signs and completes.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this feature
• I've run uv run pytest tests/tools/test_mcp_elicitation.py -v and all tests pass
• I've added tests for my changes (4 new regression tests for the context bridge, plus 11 covering the broader handler)
• I've tested on my platform: macOS 14 (darwin/arm64)

Documentation & Housekeeping

• Docstrings updated; no user-facing config keys added — N/A for README / config example
• No cli-config.yaml.example changes (the elicitation handler is configured per-server under the existing mcp_servers.<name> block; it activates automatically when the MCP SDK reports elicitation capability)
• No architecture changes outside this scope — N/A for CONTRIBUTING.md / AGENTS.md
• Cross-platform impact considered: no Unix-only syscalls introduced; scripts/check-windows-footguns.py tools/mcp_tool.py tests/tools/test_mcp_elicitation.py is clean
• No tool schema changes (this adds an MCP-protocol-level callback, not a new Hermes tool)

[liuhao1024]

Verification review — no issues found.

Well-structured implementation of MCP elicitation support with strong safety properties.

Checked:

• ✅ Fail-closed design: timeout → cancel, exception → decline, import failure → decline, URL-mode → decline (no silent accepts)
• ✅ Context bridge: _pending_call_context is set/cleared within _rpc_lock (no race condition); Context.run() correctly uses .copy() to allow multiple elicitations per tool call
• ✅ Approval routing: request_elicitation_consent is offloaded via asyncio.to_thread to avoid blocking the MCP event loop; gateway session detection survives the task hop via contextvar replay
• ✅ Configuration gate: elicitation.enabled defaults to True but is explicitly checkable; SDK type availability gated separately via _MCP_ELICITATION_TYPES
• ✅ Test coverage: 14 tests covering accept/decline/cancel flows, URL-mode rejection, exception fail-closed, timeout behavior, context bridge replay, missing context fallback, multi-replay safety, None context safety

The _OUTER_TIMEOUT_GRACE_SECONDS = 5 safety net on asyncio.wait_for is a good defensive addition — prevents indefinite blocking if the inner approval timeout machinery is bypassed.

[teknium1]

Merged via PR #49203. Your commit was cherry-picked onto current main with your authorship preserved in git log (commit 239740a). Thanks for the contribution — clean implementation that mirrors the existing SamplingHandler pattern, all 15 tests plus the broader MCP suite pass, and E2E-verified against the real approval routing. Closes this.