Claude Code: вложенные sub-agents, 5 уровней, математика токенов и 3 ловушки (2026)

Бо́льшую часть 2026 года в документации Claude Code висело жёсткое правило: «sub-agents не могут запускать других sub-agents». Намеренное ограждение от бесконечной рекурсии. 10 июня правило тихо сломалось — в v2.1.172 в changelog появилась одна строка: sub-agents теперь могут вкладываться, до 5 уровней вглубь.

Фича настолько свежая, что официальная страница sub-agents всё ещё уверяет: вложенность невозможна. Если вы уже привыкли к одноуровневому делегированию, апгрейд не такой большой — но математика токенов, поверхность настроек и сценарии отказа отличаются от того, к чему привыкли руки. Этот гайд — то, что стоило прочитать до первого вложенного запуска, о котором потом жалеешь.

Что можно делать со вложенными sub-agents (а что нельзя)

Ментальная модель за 30 секунд: вложенные sub-agents — рекурсия с лимитом стека в 5 кадров, каждый кадр со своим system prompt и моделью. Родитель читает только summary листа. Всё, что между, стоит токенов и исчезает.

Когда вкладывать (а когда — нет)

Когда стоит

1. Работа — дерево, а не список. Верхний reviewer задаёт трём специализированным sub-reviewer (security, perf, style) один и тот же вопрос про один и тот же diff, и у каждого специалиста — свой MCP-сервер или skill preload.
2. Работа рекурсивна по форме. Прогон по monorepo, где каждую packages/* нужно исследовать со своими конвенциями, а summary листьев свёртывается наверх.
3. Уже упёрлись в окно контекста на уровне 1. Одноуровневые sub-agents возвращают отчёты по 30K токенов, забивая главный разговор; ещё один уровень вниз позволит каждому листу сначала сжать, а потом отдать.

Когда НЕ стоит

1. Работа — последовательность. Пять шагов с зависимостями — это один sub-agent с maxTurns: 20, а не пять вложенных вызовов. Каждый слой — необратимое разделение контекста и одна запись system prompt.
2. Хочется параллельных воркеров, которые общаются между собой. Это agent teams, а не вложенность. Вложенные sub-agents общаются только вверх и вниз, никогда не вбок.
3. Лист дёрнет всего один tool. На этом этапе вы платите целый system prompt за один Read или Grep. Вызовите инструмент прямо из родителя.

Stop rule

Перед вложенностью напишите на стикере ожидаемый summary листа. Если это меньше ~500 токенов или родитель мог бы выдать то же самое двумя tool-вызовами — не вкладывайте. Вложенность окупается, когда лист делает осмысленную работу и возвращает осмысленно сжатый ответ.

Требования к системе

Если у вас 2.1.171 или ниже — npm i -g @anthropic-ai/claude-code. CLI печатает разрешённую версию при запуске; старые версии молча игнорируют вложенные вызовы и обрабатывают внутренний Agent tool use как обычный Read.

Пошагово: настраиваем цепочку вложенных sub-agents

Пример строит трёхуровневую цепочку: верхний triage-lead классифицирует входящий баг-репорт, делегирует repro-runner для подтверждения воспроизводимости, тот в свою очередь делегирует log-summariser сжатие сырых логов контейнера в 200-строчный summary.

Шаг 1: лист

Создайте .claude/agents/log-summariser.md:

---
name: log-summariser
description: Reads raw container logs and returns a structured summary of errors, timing, and suspicious patterns.
tools: Read, Grep
model: haiku
maxTurns: 8
---

You are a log summariser. Given a path to a log file, return:
1. Top 5 distinct error signatures with frequency
2. Earliest and latest timestamps observed
3. Any panic, OOM, or segfault entries with line numbers
Return strictly Markdown — no preamble.

Ожидаемый результат: файл подхватится сразу, если создавать через /agents, или при следующем старте сессии, если редактировать на диске.

Шаг 2: средний уровень

Создайте .claude/agents/repro-runner.md:

---
name: repro-runner
description: Reproduces a bug from a description, captures logs, and returns whether the failure is deterministic.
tools: Agent(log-summariser), Read, Bash
model: sonnet
maxTurns: 12
---

You reproduce bugs. Run the failing command, capture logs to /tmp/repro.log,
then call the log-summariser sub-agent to compress the output before returning.
Report: deterministic? yes/no, plus the summary.

Поле tools: Agent(log-summariser) — это и есть новизна. До 2.1.172 Agent(...) внутри определения sub-agent не имел никакого эффекта. Теперь это allowlist того, что данный sub-agent имеет право запускать.

Шаг 3: корень

Создайте .claude/agents/triage-lead.md:

---
name: triage-lead
description: Triages incoming bug reports end-to-end — classification, reproduction, log review.
tools: Agent(repro-runner), Read, Grep, Bash
model: opus
maxTurns: 15
---

Classify the bug (P0/P1/P2), delegate reproduction to repro-runner, then
return a triage memo with severity, repro status, and the summarised logs.

Цепочка теперь такая: главная сессия → triage-lead (Opus) → repro-runner (Sonnet) → log-summariser (Haiku). Три уровня.

Шаг 4: запуск из главной сессии

> Use the triage-lead agent on the bug report at ./bugs/2026-06-11-checkout-500.md

Claude читает поля description и автоматически прогоняет по цепочке. Можно и принудительно: Use triage-lead. Каждый handoff появляется отдельной панелью в /agents, с индикатором глубины.

Шаг 5: проверяем, что вложенность реально случилась

После прогона смотрим /agents (вкладка Running) или прокручиваем транскрипт в поисках трёх отдельных панелей sub-agent. Если видна только одна — родитель воспринял вызов Agent(...) как обычный tool-вызов. Почти всегда это несовпадение версии. Перепроверьте claude --version, нужно 2.1.172+.

/agents
> [Running]
>   triage-lead         opus       depth 1   ✓ completed
>     repro-runner      sonnet     depth 2   ✓ completed
>       log-summariser  haiku      depth 3   ✓ completed

Глубина 3 — нижний порог «работает». Лимит в 5 уровней — это потолок стека, а не цель. Большинство полезных цепочек живут на глубине 2-3.

Типовые ошибки при вложенности (и как чинить)

Третья строка — самая болезненная для команд. Changelog v2.1.172 явно отмечает фикс для фоновых sub-agents, которые залипали в active после остановки вложенного ребёнка — если вы продолжаете сессию, начатую на старой версии, один раз стартуйте с нуля, чтобы сбросить унаследованный state.

Математика токенов: почему вложенность стоит ~7× на ветку

Это расчёт, который решает, оправдан ли подход. Однопоточная сессия Claude Code переиспользует один закэшированный system prompt между ходами. Sub-agent работает в собственном окне контекста с собственным system prompt (меньше, чем у главной сессии, но не бесплатным). Вложите это — и платите ту же overhead на каждой глубине.

Цифра «~7× потребления токенов» из официального гайда по cost management — это канонический худший случай для sub-agent-интенсивных workflow. Вложенность не умножает её безгранично — листовые вызовы делают меньше работы и используют дешёвые модели — но подталкивает к ней всегда, когда дерево широкое.

С этой математикой борются два рычага:

1. Tiering модели по глубине. Листу редко нужен Opus. Типичный расклад для триаж-цепочки: Opus в корне, Sonnet на уровне 1, Haiku с уровня 2. Цены Opus и Haiku по входным токенам различаются примерно на порядок, поэтому экономия на листовом уровне компаундится по каждому вложенному вызову.
2. maxTurns на каждом слое. Без него лист может крутиться 30+ ходов, пытаясь «быть полезным». Ставьте на листья 8, на средние уровни 12; в основном вы не упрётесь, а когда упёрлись — это сигнал, что задача поставлена неверно.

Более глубокую модель издержек на сессиях Claude Code см. в гайде по оптимизации токенов. Его разбор cache_read_input_tokens применим к каждой ветке sub-agent, а не только к главному треду.

3 антипаттерна, которые разносят бюджет

Антипаттерн 1: бесконтрольная вложенность через универсальную рекурсию

Путь наименьшего сопротивления — дать каждому sub-agent tools: Agent (allowlist без ограничений) и позволить модели самой решать, кого запускать. Через несколько часов вы увидите транскрипт, где triage agent запустил «универсального researcher», который запустил «investigation specialist», который запустил «log reader», который запустил… снова универсального researcher. Каждый слой добавляет токены. Лимит глубины 5 спасает от бесконечных циклов, но не спасает от счёта.

Чинить: всегда явный allowlist. tools: Agent(repro-runner, log-summariser) — контракт между sub-agent и его детьми. Если модель не справляется с задачей через этих детей — неверно описана задача, чините описание, а не расширяйте allowlist.

Антипаттерн 2: Opus везде

Дефолт «каждый sub-agent на модели главной сессии» — это default, и для многоуровневого дерева он ровно неверен. Opus в корне оправдан (вы делаете синтез). Opus на листе, который читает лог-файл и считает частоты ошибок, — это оплата топового тарифа за работу, с которой Haiku справляется за долю цены.

Чинить: ставьте CLAUDE_CODE_SUBAGENT_MODEL=haiku на уровне shell, чтобы каждый sub-agent без override получал Haiku. Дальше повышайте только тех, кому нужно больше — обычно это корень и уровень 1. Подход к выбору модели под задачу разбирает гайд по hybrid routing pattern в Claude Code.

Антипаттерн 3: untyped Agent allowlist в production-файлах sub-agent

Проектные sub-agent файлы коммитятся в git. tools: Agent без скобок работает в разработке и выглядит обманчиво безобидно — но коллега, добавивший новый migration-runner через месяц, молча даст существующей триаж-цепочке право запускать его, потому что allowlist принимает всё.

Чинить: явно якорите allowlist в файле: tools: Agent(repro-runner, log-summariser), Read, Grep, Bash. Любое изменение этого списка обрабатывайте как security review — так же, как смену permissions.allow. Более общий принцип — в гайде по безопасности Claude Code: каждое поле, смежное с разрешениями, — это граница безопасности.

Конфигурация для команды / много разработчиков

Командам, гоняющим общие настройки Claude Code по многим репозиториям, три конвенции держат вложенные sub-agents дешёвыми, предсказуемыми и обозримыми:

Для организаций со стандартизацией по многим репам также стоит подумать о dotfiles-управляемой директории ~/.claude/agents/ с кросс-проектными агентами (review, security, doc-summariser). User-level определения выигрывают у project-level только когда проект не переобъявляет то же имя, поэтому конвенция: «общее — в user scope, repo-specific — в project scope».

Продвинутое: маршрутизация разных уровней на разные модели через ofox

Переменная CLAUDE_CODE_SUBAGENT_MODEL применяется к каждому sub-agent, который не задал собственный model. При направлении на Anthropic-совместимый шлюз одна эта переменная пересаживает весь leaf-уровень с одного model alias на другой, не трогая ни одного sub-agent файла. Интеграция — одна переменная окружения плюс model alias:

export ANTHROPIC_BASE_URL=https://api.ofox.ai/anthropic
export ANTHROPIC_API_KEY=<your_ofox_key>
export CLAUDE_CODE_SUBAGENT_MODEL=haiku

claude

Sub-agents любой глубины, не override-ящие model, теперь идут через ofox на Haiku. Корневой агент и любой sub-agent, явно задавший model: opus или model: sonnet, всё равно идёт через ofox на соответствующий tier — CLAUDE_CODE_SUBAGENT_MODEL это default, а не override. Полную настройку, включая то, как cache_control headers проходят без изменений и экономят на prompt caching у родителя, разбирает гайд по подключению Claude Code к ofox.

Ofox принимает и голые алиасы Claude Code (opus, sonnet, haiku), и явные ID с префиксом провайдера (anthropic/claude-opus-4.8, anthropic/claude-sonnet-4.6, anthropic/claude-haiku-4.5), которые писали бы при прямой интеграции. Алиасы держат frontmatter sub-agent переносимым между прямой Anthropic и шлюзом; явные ID фиксируют конкретную версию. Витрина моделей на ofox.ai/models показывает текущую линейку Claude — можно прикинуть фактический счёт под свою ярусную схему до того, как commit-ить.

Для очень длинных вложенных прогонов следующим ограничением становится дефолтный TTL prompt cache в 5 минут. ENABLE_PROMPT_CACHING_1H=1 растягивает его до часа за 2× к стоимости cache-write — обычно окупается, когда одна triage-цепочка переваливает за 15 минут wall clock.

Источники, проверенные для этой ревизии

• Claude Code CHANGELOG v2.1.172 (проверено 2026-06-11): github.com/anthropics/claude-code/blob/main/CHANGELOG.md — подтверждает «Sub-agents can now spawn their own sub-agents (up to 5 levels deep)» и сопутствующий фикс для застрявших фоновых sub-agents
• Справочник Claude Code sub-agents (проверено 2026-06-11): code.claude.com/docs/en/sub-agents — полная схема frontmatter (tools, model, maxTurns, mcpServers, hooks, permissionMode); страница до сих пор утверждает, что вложенность невозможна, что противоречит changelog 2.1.172
• Гайд Claude Code по cost management (проверено 2026-06-11): code.claude.com/docs/en/costs — источник цифры «~7× токенов для sub-agent-интенсивных workflow»
• Зеркало changelog Claude Code (проверено 2026-06-11): code.claude.com/docs/en/changelog — вторичное подтверждение записи 2.1.172
• Снимок витрины моделей ofox (проверено 2026-06-11): ofox.ai/models — текущие листинги anthropic/claude-opus-4.8, anthropic/claude-sonnet-4.6, anthropic/claude-haiku-4.5

Заголовок — «5 уровней вглубь», но полезное число — «глубина 2». Большинство вложенных цепочек окупаются на root-Opus, mid-Sonnet, leaf-Haiku — три уровня, три модельных tier, один явный Agent(name) allowlist на каждом handoff. Пропустите allowlist или tiering — и лимит в 5 уровней превращается из первой линии обороны в последнюю линию обороны кошелька.