Claude Code Subagent

Unique identifier for the subagent using lowercase letters, numbers, and hyphens. Used to reference the subagent in Task(agent-name) tool restrictions, permission deny rules, hook matchers, and the /agents interface. Plugin subagents appear namespaced as plugin-name:agent-name.

Describes when and how Claude should delegate to this subagent. Claude uses this to decide automatic delegation — write it as a triggering guide with concrete task patterns. Include phrases like "use proactively" to encourage automatic delegation. This is the single most important field for subagent behavior — a vague description means Claude won't know when to delegate. See automatic delegation.

Tools the subagent can use. If omitted, inherits all tools from the main conversation (including MCP tools). Specify a subset to restrict access. Built-in tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, Task, Skill, NotebookEdit. Supports patterns: Bash(git *) allows only git subcommands, Skill(commit) allows invoking a specific skill, Task(worker, researcher) restricts spawnable subagent types (only meaningful for agents run as main thread via claude --agent). MCP tools follow the pattern mcp__<server>__<tool>.

Tools to explicitly deny, removed from the inherited or specified tool list. Use when you want to grant most tools but block a few specific ones (e.g. block Write and Edit for a read-only agent). Supports the same tool name formats as tools.

Which Claude model the subagent uses. Set to inherit (default) to use the same model as the main conversation. Use haiku for fast, low-latency tasks (search, exploration). Use sonnet for balanced capability. Use opus for the most capable reasoning.

Controls how the subagent handles permission prompts. Subagents inherit the permission context from the main conversation but can override the mode. If the parent uses bypassPermissions, it takes precedence and cannot be overridden. Background subagents auto-deny unpermitted actions rather than prompting.

• default: Standard permission prompts
• acceptEdits: Auto-accept file edits (Write, Edit)
• dontAsk: Auto-deny permission prompts (explicitly allowed tools still work)
• bypassPermissions: Skip all permission checks (use with caution)
• plan: Read-only exploration, requires approval before implementation

Maximum number of agentic turns (API round-trips) before the subagent automatically stops and returns results. Each tool use counts as one turn. Use to prevent runaway subagents or control cost.

Skills to preload into the subagent's context at startup. The full content of each skill is injected (not just made available for invocation). Subagents do not inherit skills from the parent conversation — you must list them explicitly. This is the inverse of running a skill in a subagent (context: fork).

MCP servers available to this subagent. Each key is a server name — the value is either an empty object {} to reference an already-configured server by name, or an inline definition with a full MCP server config. MCP tools are not available in background subagents.

Lifecycle hooks scoped to this subagent. Hooks defined here only fire while this subagent is active and are cleaned up when it finishes. Stop hooks in frontmatter are automatically converted to SubagentStop events at runtime. See hooks in skills and agents.

Enable persistent memory that survives across conversations. The subagent gets a dedicated memory directory to build knowledge over time (codebase patterns, debugging insights, architectural decisions). When enabled, the first 200 lines of MEMORY.md are included in the system prompt, and Read/Write/Edit tools are automatically enabled.

• user: ~/.claude/agent-memory/<name>/ — learnings across all projects
• project: .claude/agent-memory/<name>/ — project-specific, shareable via VCS
• local: .claude/agent-memory-local/<name>/ — project-specific, gitignored

When true, always run this subagent as a background task. Background subagents run concurrently while the main conversation continues. Before launching, Claude prompts for needed tool permissions upfront. Background subagents auto-deny unpermitted actions and cannot use MCP tools or ask clarifying questions via AskUserQuestion. Set CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 to disable all background tasks. Users can also press Ctrl+B to background a running foreground subagent.

Set to worktree to run the subagent in a temporary git worktree, giving it an isolated copy of the repository. The subagent can make changes without affecting the main working tree. The worktree is automatically cleaned up if the subagent makes no changes. Useful for parallel exploration or risky operations that should be isolated.