A subagent is a separate role working in its own context window: it gets its own system prompt, model, tools and permissions, and returns a result to the main thread. This is useful for exploration, log analysis, review and recurring specialist roles - where a separate context and a pointed toolset are better than loading the main session. The built-in Explore, Plan and general-purpose already cover the basic cases, so your own role is not always needed.

Subagent definitions live in files: project in .claude/agents//*.md, user in ~/.claude/agents//*.md. On a name collision the precedence is: managed, then those passed by the --agents flag, then project, user and plugin. In a nested project the closer definition wins. The role's identity is set by the name field in the frontmatter, not the filename - this matters, because renaming a file does not change how the role is invoked.

A good subagent is described by an honest frontmatter and a narrow role. It helps to see a whole example once - the code-reviewer role: with a description, a tools set, an explicit disallowedTools for Write and Edit, a model, effort, a turn limit and memory, and in the body an instruction to act as a read-only reviewer and return only actionable findings. The supported frontmatter fields include name, description, tools, disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, effort, isolation, color and initialPrompt.

The key thing for security is how tools and permissions are inherited. A subagent usually inherits the parent session's available pool, and then tools and disallowedTools narrow it; it cannot get a tool the parent lacks. The crucial subtlety: forbidding only Write is not enough if Bash still lets it change files - a read-only reviewer must have either a read-only set or a narrow Bash allow. Permissions and denied actions meanwhile return through the parent flow.

The role's fields have limits to know. permissionMode can set the role's mode, but plugin-shipped agents for security do not support permissionMode, hooks and mcpServers. isolation: worktree gives the subagent a separate git worktree for edits - this is for independent implementation, not for plain reading. The skills field preloads selected procedures into the role's context (this is a preload, not a command call), and memory - user, project or local - keeps the role's knowledge between sessions and is as sensitive as auto memory.