Claude subagents are specialized workers with their own prompts, context, and tool restrictions. They help when a bounded subtask needs isolation or parallel investigation, not when a larger prompt would suffice. The parent must have the Agent tool, delegation contracts must be clear, and the harness must bound fan-out, budget, authority, and result size.
You will define a read-only code reviewer subagent, explain what it inherits, and decide when delegation improves the system.
The SDK supports programmatic agent definitions and filesystem-based definitions. Prefer programmatic definitions when application code must control prompts and tools explicitly.
Conceptual Python configuration:
Check the current language reference for constructor field names in your installed version. The essential boundary is that the child receives only the tools its contract needs.
Isolation is incomplete if every child receives the same filesystem, credentials, network, and hidden configuration. Tool lists are one layer, not the whole sandbox.
Measure whether the parent delegates when appropriate, chooses the correct worker, avoids unnecessary delegation, integrates findings accurately, and remains within fan-out/turn/cost limits. Track child invocation in SDK messages and telemetry.
Failure injection: Give the parent an open-ended prompt and multiple overlapping subagents. If it creates redundant work, add explicit delegation criteria and a harness concurrency/fan-out cap.
Use per-subagent policy profiles, context manifests, timeouts, quotas, and result schemas. Disallow shared writes or coordinate them through a deterministic commit stage. Subagent spend contributes to the session budget, but operational concurrency still needs your own control.
Create two reviewers—security and tests—with disjoint prompts and read-only tools. Compare sequential and parallel execution for quality, latency, and cost; keep writes in a later deterministic merge stage.