Agent Configuration#

Agent configuration in Claude Code uses Markdown files with YAML frontmatter to define autonomous subprocesses that handle complex, multi-step tasks. Each agent file lives under an agents/ subdirectory within a plugin (e.g., plugins/my-plugin/agents/agent-name.md) and is auto-discovered at session start 1.

The Agent Teams feature — which enables a parent Claude instance to spawn and coordinate these agents at runtime — shipped in v2.1.32 as a research preview behind the env flag CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 2.

Frontmatter Schema#

The agent-development SKILL.md documents the complete file format. Fields at a glance:

A real example — the agent-creator agent in the plugin-dev plugin — shows model: sonnet, color: magenta, and tools: ["Write", "Read"] 10.

Subagent Spawning Restrictions#

A parent agent can restrict which child agent types it is allowed to spawn using Task(agent_type) syntax inside the tools frontmatter (added v2.1.33):

tools: ["Read", "Write", "Task(code-reviewer)", "Task(test-generator)"]

This declares the parent is permitted to dispatch only the listed agent types 11. A later fix in v2.1.147 resolved a bug where declaring multiple Agent(...) types caused all but the last to be silently dropped 12.

Lifecycle Hooks for Multi-Agent Monitoring#

v2.1.33 introduced two hook events specifically for monitoring teammate agents 13:

Both hooks support the {"continue": false, "stopReason": "..."} response to halt a teammate — identical to the behavior of the Stop hook 14.

Hook configuration uses the same hooks/hooks.json format as other hook types. For plugin hooks, events are wrapped in {"hooks": {...}}; for user settings in .claude/settings.json, events sit at the top level 15. See the hook-development SKILL.md for full hook output formats, matchers, and timeout defaults.

Observability#

Parent–child relationships are tracked via OTEL spans: agent_id and parent_agent_id attributes appear on claude_code.tool spans, and background subagent spans nest under the dispatching Agent tool span. All sub-agent API requests carry x-claude-code-agent-id / x-claude-code-parent-agent-id HTTP headers 2.

The env variable CLAUDE_CODE_SUBAGENT_MODEL controls the model used by teammate processes; a fix resolved this variable not applying to agent-teams spawned teammates 16.

Key Source Files#