Research and concept mapping
Use this reference conditionally after tracing the source path. It is a decision guide, not a requirement to reproduce every Claude Code feature.
Primary documentation
Inspect the installed versions before migrating because the Claude Agent SDK, Pydantic AI, and Harness continue to evolve.
- Claude Agent SDK: Python reference, agent loop, and sessions.
- Pydantic AI: agents, message history, hooks, and deferred tools.
- Pydantic AI Harness: overview, shell execution, subagents, and step persistence.
The source SDK launches a bundled Claude Code process, passes configuration through CLI flags and a control protocol, and parses stream-JSON frames into Python message classes. That subprocess architecture is not a caller contract by itself. Preserve configured behavior, ordered outputs/events, errors, state, and external effects.
Ownership map
| Observed Claude Agent SDK behavior | Target owner and likely seam | Focused proof |
|---|---|---|
query() model/tool loop and ResultMessage.result |
Core: Agent.run() / run_sync(), AgentRunResult.output |
Assert caller output, errors, required usage data, and side effects without preserving the subprocess envelope. |
ClaudeAgentOptions.system_prompt, model, thinking, limits |
Core: instructions, model/provider settings, UsageLimits(request_limit=..., cost_limit=...); Harness: SpendLimits only for observed cross-run spend policy |
Assert that limit exhaustion raises UsageLimitExceeded and translate it if callers expect a Claude result subtype. Core cost limits are best-effort, depend on available pricing, and may be checked after a billed response; retain provider/application spend controls when the source promises a hard cap. |
Custom @tool and in-process SDK MCP server |
Core: @agent.tool, @agent.tool_plain, Tool, toolsets; MCP only for protocol interoperability |
Assert schema validation, retry/error behavior, concurrency, output content, and side effects. |
Built-in Read/Write/Edit/Glob/Grep/Bash |
Harness: FileSystem, Shell, RepoContext, or Coder; Application/infrastructure: ModalSandbox or existing isolation |
Assert file/process outcomes, path escape resistance, command containment, and output limits. |
| Built-in web tools | Core: WebSearch and WebFetch capabilities, backed by WebSearchTool and WebFetchTool where the provider supports them; otherwise retain the application integration |
Assert result shape, citations/events consumed by callers, credentials, and egress policy. |
| External MCP servers | Core: MCPToolset, load_mcp_toolsets() |
Assert discovery, collisions/prefixes, transport, credentials, errors, lifecycle, and any required live control. |
allowed_tools, disallowed_tools, permission modes, can_use_tool |
Core: tool preparation; requires_approval or ApprovalRequiredToolset to gate the tool; resolve inline with HandleDeferredToolCalls, or return DeferredToolRequests and resume a later run with DeferredToolResults; optional Harness policy; Application: authorization/UI/audit |
Assert availability and each pre-effect allow, deny, or ask outcome independently, including source callback precedence. |
Structured output_format and structured_output |
Core: typed output_type, Pydantic models, output validators and modes |
Assert validated values and invalid-output retry exhaustion; do not silently parse fallback text. |
| Completed assistant/tool/result messages | Core: normalized messages and agent stream events; Application: retained event adapter | Compare a stable-field golden trace and include trailing source events. |
Raw partial StreamEvents |
Core: run_stream(), run_stream_events(), event_stream_handler, or agent.iter() according to consumer intent |
Assert reconstruction, order, terminal detection, no duplicate final text, and cancellation. |
| Live multi-turn client | Core: repeated Agent.run(..., message_history=...); Application: connection/UI loop |
Assert next-turn context plus observed mid-run input or interrupt behavior. |
Disk resume, SessionStore, transcript list/read/rename/tag |
Core: serialized normalized messages; Application: storage, indexing, tenancy, metadata | Round-trip through the real store and continue in a fresh process. |
| Session fork/truncating resume | Application + Core: copy validated history and start a correlated conversation; optional Harness: StepPersistence for settled snapshots |
Assert branch point, source immutability, new lineage, tool-call pairing, and side-effect safety. |
| File checkpoint rewind | Application/infrastructure: VCS, overlay, snapshot, or workspace owner | Assert filesystem state independently of message history; otherwise record a tested gap. |
| Hooks and matchers | Core: Hooks or a custom capability; Application: audit/integration effects |
Golden-test firing, stable inputs, decisions, mutation, errors, ordering, retry, and streaming behavior. |
Model-directed AgentDefinition subagents |
Harness: SubAgents; Core: agent-as-tool for a fixed handoff |
Assert task-only input, isolated history, dependencies, budgets, handback, events, and recursion policy. |
| Agent Skills | Harness: Skills |
Assert SKILL.md discovery/loading and test any resources, scripts, or setting-source behavior separately. |
| Local plugins | Decompose used skills, agents, hooks, commands, and MCP servers across Core, Harness, and Application | Assert each used feature; record packaging or namespace parity as a gap only when caller-visible. |
| Planning/task tracking | Harness: Planning only for an observed model-owned plan |
Assert persistence and tenant/session keys only when required. |
| Cross-run model memory | Harness: Memory for its notebook semantics; otherwise retain application storage/retrieval |
Assert restart, namespace isolation, concurrency, and bounded injection. |
| Compaction/context management | Core: history processors/provider compaction; optional Harness: compaction, output limits, conversation search | Assert retained facts, tool pairing, thresholds, cache behavior, and retrieval of omitted history. |
| Interrupts and cancellation | Core: cancellation token/task cancellation; Application: transport semantics | Assert stopped work, terminal shape, cleanup, and next-turn continuation. |
| Durable restart/replay | Core: durable runtime integration; optional Harness durability capabilities | Kill and restart at each promised boundary; assert external effects are idempotent. |
| Cost, usage, rate-limit and telemetry events | Core: run usage and OTel; optional Harness: spend policy; Application: billing and retained adapters | Assert required metrics, event/trace mapping, and privacy settings; do not treat estimated cost as billing. |
| HTTP, WebSocket, queues, deployment and auth | Application/infrastructure | Exercise the retained production boundary, including tenancy, scheduling, secrets, scaling, and isolation. |