From the Inside Claude Code: The Claude Code Ecosystem architecture map
The transport is the only translator from options to Claude Code CLI flags
Subprocess CLI Transport is used by query(), the Internal Client, ClaudeSDKClient, Package Exports and Control Protocol Query, and is the sole path to the Claude Code CLI. _build_command reads 39 distinct ClaudeAgentOptions fields from Types and maps each to a CLI flag, yet the transport-to-Types dependency is not drawn. The CLI version check only logs a warning below 2.0.0.
Impact: Every new option or renamed CLI flag lands in one 1,228-line file, and a bundled or user-installed CLI that rejects a flag fails only at spawn time, in every entry point at once.
Recommendation (medium effort): Extract command building into a pure options-to-argv function with table-driven contract tests per CLI version, and move flag-only settings into the initialize request where the CLI can report unknown fields.
The trail
Open on the mapMore from this board
- Session Store is a single point of failure for 7 modules, from the clients to the package exports
- Optional SessionStore methods raise instead of being absent, so a change in Types reaches 13 modules
- Every defence against hidden instructions rests on one small sanitizer
- Interrupt and other control calls stall when nobody is reading messages
- Day 1: start with marketplace.json, the contract everything else serves
- Day 2: follow the install path from Claude Code into one plugin
- Session Store is shared by three groups of code, so a change to it reaches all of them
- Every SDK module imports its exceptions from one file, _errors.py
- can_use_tool is a ready gate seam with subagent provenance
- PR-controlled agent config is restored from the base branch before Claude starts
- Start with the gate order in the Run Orchestrator
- Then follow untrusted text from GitHub into the prompt
- The action and the base action share an untyped prompt-file contract
- Both public entry points share one control-protocol engine
- Learn issue automation as one loop from GitHub event back to GitHub
- The gh.sh wrapper is the safety contract both Claude jobs rest on
- The triage and dedupe agents are boxed in identity, tools and network
- Claude jobs reach GitHub only through a read-only wrapper and event-bound writes
- Day 3: the chat-channel flow shows the only long-running code
- Day 4: CI keeps the catalogue honest and current
- Public API code reaches straight into Session Store instead of going through a session entry point
- A failed SessionStore append is retried, then dropped; mirror_error is the only signal
- Channel messages carry sender identity, giving the session provenance
- CI already gates external plugins with an agent and reverts on failure
- Sessions copies the CLI's folder-naming hash, and 6 modules depend on that copy
- Spend and run length are bounded at the transport
- Tag mode gives Claude a narrow, workspace-bound tool list
- Skip post-run reporting and branch plumbing at first
- Command-line construction is hardened against argument injection
- Tool permission requests fail closed
- Skip the engine, mods and examples when the goal is issue automation
- Lifecycle timeouts are restated outside their single source of truth
- The duplicate comment script is pinned to the upstream repository
- Every agent-driven closure has a human override before it happens
- Skip for now: config-only integrations, CI plumbing and single-file plugins
- Key vocabulary: marketplace entry, plugin, channel, pairing, permission relay, SHA bump
- Plugins are fully independent and deploy on their own
- External-PR workflows never execute contributor code
- Channel servers keep bot tokens owner-only and refuse injected pairing requests