Create Claude Code Subagents with Focused Context, Tools, Models, and Permissions

Quick answer

Use a subagent when a task is bounded, benefits from a fresh context, and can return a compact artifact. Give it one objective, necessary background, explicit exclusions, minimal tools, an appropriate model, a verification method, and a return schema. Use read-only agents for research and review; grant edits only when file ownership is clear. Foreground work fits interactive dependencies, while background work fits independent tasks. Anthropic's subagent documentation defines current agent files and controls.

Delegate an outcome, not vague labor

Weak:

Look into auth.

Strong:

Determine why concurrent refresh requests revoke the new token. Read only auth source,
tests, and relevant history. Do not edit. Return: reproduction steps, earliest incorrect
state transition with file references, rejected hypotheses, smallest proposed fix,
and the exact regression test. Stop if production data or external access is required.

The parent should be able to evaluate the return without inheriting every tool result.

Build a focused agent definition

Custom agents are typically Markdown definitions with frontmatter. Validate current fields in the official docs. A security reviewer might declare a precise description, read/search tools, a chosen model tier, and instructions such as:

---
name: authorization-reviewer
description: Review a proposed diff for concrete authentication, authorization,
  tenant-isolation, and secret-handling vulnerabilities.
tools: Read, Grep, Glob, Bash
---

Review only changed code and the contracts it invokes. Do not edit files.
For each finding provide severity, file/line, attacker precondition, execution path,
impact, and a minimal remediation. Exclude style and speculative findings.
Run only read-only Git and focused test-listing commands.

Tool names and permission constraints must use canonical identifiers. If an agent does not need Bash, omit it.

Pick model and context intentionally

Use a fast model for inventory and mechanical checks, stronger reasoning for architecture or subtle security analysis, and inheritance when consistency is more valuable than specialization. Do not escalate model cost without improving the delegation contract and evidence.

Subagents receive separate context, which is useful for isolating large research. They still need relevant project instructions and must not be asked to rediscover the whole repository. Supply exact scope and let them load only required references.

Foreground versus background

Use foreground execution when the subtask may uncover a decision requiring immediate steering, shares mutable files, or gates the next action. Use background execution for independent read-only research, a long test, or separate package ownership. Background does not make unsafe actions acceptable; permissions and non-reversible boundaries still apply.

Require a return contract

Return at most 800 words:
1. Conclusion and confidence.
2. Evidence with file/line or command.
3. Counterevidence/rejected hypotheses.
4. Risks and unknowns.
5. Recommended next action.
Do not claim a check passed unless you ran it and include its result.

The parent must independently validate critical claims before editing or shipping.

Mastery lab

Create three agents: a read-only code-path mapper, an authorization reviewer, and a test-failure triager. Give all three the same auth bug and compare overlap, context use, and actionable evidence. Tighten each description until automatic delegation chooses the correct specialist without triggering on ordinary tasks.

FAQ

Are subagents cheaper than the main session?

They can save parent context but still consume model and tool resources. Measure total cost and outcome.

Can two editing subagents work in the same checkout?

Avoid overlapping ownership. Use isolated worktrees or strict non-overlapping files and an integration plan.

Should the parent trust a subagent's “tests pass” claim?

Require command evidence and rerun critical verification after integration.