name |
string |
Yes |
Unique identifier using lowercase letters and hyphens |
description |
string |
Yes |
When to invoke. Use "PROACTIVELY" for auto-invocation by Claude |
tools |
string/list |
No |
Comma-separated allowlist of tools (e.g., Read, Write, Edit, Bash). Inherits all tools if omitted. Supports Agent(agent_type) syntax to restrict spawnable subagents; the older Task(agent_type) alias still works |
disallowedTools |
string/list |
No |
Tools to deny, removed from inherited or specified list |
model |
string |
No |
Model alias: haiku, sonnet, opus, or inherit (default: inherit) |
permissionMode |
string |
No |
Permission mode: default, acceptEdits, dontAsk, bypassPermissions, or plan |
maxTurns |
integer |
No |
Maximum number of agentic turns before the subagent stops |
skills |
list |
No |
Skill names to preload into agent context at startup (full content injected, not just made available) |
mcpServers |
list |
No |
MCP servers for this subagent — server name strings or inline {name: config} objects |
hooks |
object |
No |
Lifecycle hooks scoped to this subagent. All hook events are supported; PreToolUse, PostToolUse, and Stop are the most common |
memory |
string |
No |
Persistent memory scope: user, project, or local |
background |
boolean |
No |
Set to true to always run as a background task (default: false) |
effort |
string |
No |
Effort level override when this subagent is active: low, medium, high, max. Default: inherits from session |
isolation |
string |
No |
Set to "worktree" to run in a temporary git worktree (auto-cleaned if no changes) |
initialPrompt |
string |
No |
Auto-submitted as the first user turn when this agent runs as the main session agent (via --agent or the agent setting). Commands and skills are processed. Prepended to any user-provided prompt |
color |
string |
No |
CLI output color for visual distinction (e.g., green, magenta). Functional but absent from official frontmatter table — documented in interactive quickstart only |
