From the Inside Claude Code - The Claude Code Ecosystem architecture map
Every SDK module imports its exceptions from one file, _errors.py
The exception hierarchy in _errors.py (ClaudeSDKError, CLIConnectionError, CLINotFoundError, ProcessError, ResultError, CLIJSONDecodeError, MessageParseError) is imported directly by the CLI transport, ClaudeSDKClient, the control protocol query, the message parser and the package entry point. None has a fallback. A breaking change to this file reaches all five, and through the transport it reaches the internal client that drives one-shot queries.
Impact: Renaming or reshaping an exception breaks the public exports and every place that catches or raises it, so callers lose their error handling at once.
Recommendation (small effort): Treat _errors.py as a frozen public contract: add new exception classes as subclasses and keep existing names and constructor arguments stable. Cover the hierarchy with a test that imports every name the package entry point re-exports.
The trail
- Errors
- Subprocess CLI Transport
- Internal Client
- ClaudeSDKClient
- Control Protocol Query
- Message Parser
- Package Exports
More 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
- Partner MCP plugins launch unpinned packages on every user's machine
- PR-controlled agent config is restored from the base branch before Claude starts
- Control-protocol failures escape the SDK exception hierarchy
- Both public entry points share one control-protocol engine
- 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
- Command-line construction is hardened against argument injection
- 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
- Channel servers keep bot tokens owner-only and refuse injected pairing requests