Subagent - это отдельная роль, работающая в своём context window: он получает собственный system prompt, модель, инструменты и разрешения, а в основной поток возвращает результат. Это полезно для исследования, разбора логов, review и повторяющихся специализированных ролей - там, где отдельный контекст и точечный набор инструментов лучше, чем нагружать основную сессию. Встроенные Explore, Plan и general-purpose уже покрывают базовые случаи, так что своя роль нужна не всегда.

Определения субагентов лежат в файлах: project - в .claude/agents//*.md, user - в ~/.claude/agents//*.md. При совпадении имени приоритет таков: managed, затем переданные флагом --agents, затем project, user и plugin. Во вложенном проекте выигрывает ближе расположенное определение. Идентичность роли задаёт поле name во frontmatter, а не имя файла - это важно, потому что переименование файла не меняет того, как роль вызывается.

Хороший субагент описывается честным frontmatter и узкой ролью. Полезно один раз увидеть цельный пример - роль code-reviewer: с описанием, набором tools, явным disallowedTools для Write и Edit, моделью, effort, лимитом ходов и памятью, а в теле - инструкция вести себя как read-only ревьюер. Поддерживаемые поля frontmatter - name, description, tools, disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, effort, isolation, color, initialPrompt; name и description - основа discovery.

Ключевое для безопасности - как наследуются инструменты и разрешения. Субагент обычно наследует доступный пул родительской сессии, а затем tools и disallowedTools сужают его; получить инструмент, которого нет у родителя, он не может. Важнейшая тонкость: запретить только Write недостаточно, если Bash всё ещё позволяет менять файлы - read-only ревьюер должен иметь либо read-only набор, либо узкий Bash allow. Разрешения и отклонённые действия при этом возвращаются через родительский flow.

У полей роли есть ограничения, которые надо знать. permissionMode может задать режим роли, но plugin-поставляемые агенты из соображений безопасности не поддерживают permissionMode, hooks и mcpServers. isolation: worktree даёт субагенту отдельный git worktree для правок - это для независимой реализации, а не для простого чтения. Поле skills подгружает выбранные процедуры в контекст роли (это preload, а не вызов команды), а memory - user, project или local - сохраняет знания роли между сессиями и так же чувствительна, как auto memory.