Claude Agent SDK for Python 0.2.140 adds MCP 2.x and subagent transcript forwarding

The Claude Agent SDK for Python reached 0.2.140 on 18 August 2026, published on GitHub at 20:58 UTC and listed on PyPI as claude-agent-sdk 0.2.140. The notes are a ship list, not a teaser. In-process SDK MCP servers now support mcp 2.x at full fidelity, and a new forward_subagent_text boolean on ClaudeAgentOptions forwards a subagent's text and thinking blocks as messages in the parent stream so a host can render the full nested transcript. That option matches the TypeScript SDK's forwardSubagentText.

The same tag also adds a structured ResultError exception, can_use_tool permission callbacks on query() and string prompts, recovery of parent_tool_use_id when reading subagent transcripts, and an update of the bundled Claude CLI to 2.1.235.

MCP 2.x for in-process servers

The SDK now supports mcp 2.x alongside 1.x. The dependency range is mcp>=1.23.0,<3.0.0.

In-process servers are served over mcp's own in-memory transport instead of a hand-rolled JSON-RPC dispatcher. Hand-built mcp.server.Server instances therefore work at full fidelity: resources, prompts, and all result content types reach the CLI verbatim. Tool cancellation on interrupt is supported on mcp 2.x. claude_agent_sdk.ToolAnnotations accepts both camelCase and snake_case hint names on every mcp version. That work is pull request #1218.

The PyPI documentation already describes a custom tool as a Python function offered to Claude through an in-process MCP server that runs inside the host application. Benefits listed there include no subprocess management, no IPC overhead on tool calls, a single process to deploy and debug, and ordinary Python type hints. Mixed maps are supported: an SDK server and an external stdio server can sit together in ClaudeAgentOptions.mcp_servers.

If you already construct mcp.server.Server by hand, this is the version where those objects stop looking like a subset of the protocol on the in-process path. Resources and prompts are included, result types pass through, and 2.x cancellation is available on interrupt.

Nested transcripts on the parent stream

forward_subagent_text is the observability switch. Set it on ClaudeAgentOptions and a subagent's text and thinking blocks arrive as stream messages. A consumer can render the nested transcript while the child run is still going, rather than waiting for a collapsed result. The release notes state that this matches the TypeScript SDK's forwardSubagentText. That is pull request #1206.

A companion bug fix lines historical reads up with the same parent. get_subagent_messages() and get_subagent_messages_from_store() now recover parent_tool_use_id from the subagent's metadata, linking each subagent's messages to the Agent tool_use block in the parent session. SessionMessage also gains a parent_agent_id field for the spawning agent's id. That is pull request #1207.

Live forwarding plus recovered parent ids is what a multi-agent UI needs: show what a nested agent is saying and thinking, and attach those messages to the parent tool call that spawned them.

ResultError and query() permission callbacks

When the CLI exits after a terminal error result, the SDK now raises ResultError instead of a bare "exit code 1" process failure. ResultError is a subclass of ProcessError. It carries subtype, errors, result, api_error_status, terminal_reason, session_id, and the raw data dict, so callers can branch on failure reason without string matching. The type is a new export (pull request #1205).

PyPI's error-handling example catches it as a distinct case and prints the structured fields:

except ResultError as e:
 print(f"Run failed: {e.subtype=} {e.terminal_reason=} {e.api_error_status=}")
 print(e.result or e.errors)
except ProcessError as e:
 print(f"Process failed with exit code: {e.exit_code}")

The notes also extend the can_use_tool permission callback to query() and string prompts, not only ClaudeSDKClient. Stdin is kept open so the CLI can send permission requests over the control protocol (pull request #1204). That matters if your host is a one-shot query() loop and you still need to approve tools over the control channel.

Install

Pin the release:

pip install claude-agent-sdk==0.2.140

The package requires Python 3.10+ and bundles the Claude Code CLI; this build ships CLI 2.1.235. You can still point ClaudeAgentOptions(cli_path=...) at a system install if you prefer. If your environment already pins mcp, confirm you are inside >=1.23.0,<3.0.0 before you upgrade the agent SDK.

Turn on forward_subagent_text in ClaudeAgentOptions and watch a nested agent's text and thinking arrive on the parent stream. If you ship custom tools, run a hand-built mcp.server.Server in-process and verify that resources, prompts, result types, and 2.x cancellation reach the CLI. Keep the GitHub v0.2.140 notes open for the ResultError field list and the two get_subagent_messages* helpers.