feat: read _meta from MCP tool call responses

[Oxygen56]

Summary

Extracts and exposes the _meta field from MCP tool call responses via ToolCallOutputItem.mcp_meta.

Background

PR #2375 enabled sending _meta in MCP tool call requests (client → server). This PR adds the complementary feature: reading _meta from MCP tool call responses (server → client).

The MCP protocol spec defines CallToolResult._meta as an optional metadata dictionary that servers can return alongside the tool result. Currently the SDK ignores this field entirely.

Changes

• src/agents/items.py — Add mcp_meta: dict[str, Any] | None field to ToolCallOutputItem
• src/agents/tool_context.py — Add internal _mcp_response_meta field to ToolContext to transport the meta from tool invocation
• src/agents/mcp/util.py — Extract result._meta in invoke_mcp_tool and store it on the ToolContext
• src/agents/run_internal/tool_execution.py — Thread the meta through _FunctionToolTaskState to ToolCallOutputItem at result-build time

Usage

After an MCP tool call, consumers can access the server-returned _meta via the event stream:

from agents import RunResult

async for event in result.stream_events():
    if hasattr(event, 'item') and hasattr(event.item, 'mcp_meta'):
        meta = event.item.mcp_meta  # dict or None

Backward Compatibility

All new fields default to None. Existing code that constructs ToolCallOutputItem without mcp_meta continues to work unchanged.

Closes #3477

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d953ac1a47

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Read MCP response metadata from .meta

When an MCP server returns CallToolResult(..., _meta={...}), the Python MCP SDK exposes that value through the meta field while _meta is only the wire alias, so getattr(result, "_meta", None) stays None for normal CallToolResult objects. In that scenario this never populates the ToolContext, and ToolCallOutputItem.mcp_meta remains unset despite the server returning metadata; read result.meta here (with any needed fallback) before copying it.

Useful? React with 👍 / 👎.