From the Inside Claude Code - The Claude Code Ecosystem architecture map
Control-protocol failures escape the SDK exception hierarchy
Control Protocol Query and SDK MCP Bridge raise plain Exception at 13 sites: control request timeouts, CLI error responses, missing callbacks, unsupported subtypes and closed MCP sessions (query.py:404, 591-751, 1145; sdk_mcp_bridge.py:76-370). The Errors module defines ClaudeSDKError and typed subclasses, but none is used here.
Impact: Callers who catch ClaudeSDKError around interrupt(), set_model() or get_mcp_status() miss these failures and must string-match messages, which makes every wording change a breaking change.
Recommendation (small effort): Add ControlRequestError and ControlRequestTimeoutError subclasses of ClaudeSDKError (the timeout also subclassing TimeoutError) and raise them from _send_control_request and the bridge.
The trail
Open on the mapMore from this board
- Optional SessionStore methods raise instead of being absent, so a change in Types reaches 13 modules
- The Lowerer is one struct spread over 38 files and 29,700 lines with no unit tests
- Day 1: start with marketplace.json, the contract everything else serves
- Every SDK module imports its exceptions from one file, _errors.py
- Partner MCP plugins launch unpinned packages on every user's machine
- PR-controlled agent config is restored from the base branch before Claude starts
- The triage and dedupe agents are boxed in identity, tools and network
- Label decisions by the triage agent leave no reason a maintainer can see
- Spend and run length are bounded at the transport
- The subprocess transport carries five responsibilities in one file
- Every agent-driven closure has a human override before it happens
- Skip for now: config-only integrations, CI plumbing and single-file plugins
- External-PR workflows never execute contributor code