Субагенты Claude Code выглядят как суперсила: запустил пять параллельных задач и пошёл пить кофе. На практике вы вернётесь к пустым файлам, крашнутой сессии и ощущению, что потратили час впустую.
Task tool - это способ запустить из основной сессии Claude Code дочерние агенты. Каждый получает свою задачу и работает параллельно или последовательно. Звучит красиво. Я попробовал это на своём пет-проекте по генерации контента и собрал все грабли, которые только можно было собрать. Вот пять проблем, с которыми вы столкнётесь, и что с ними делать.
Камень 1: Background-субагенты молча теряют доступ к инструментам
У Task tool есть параметр run_in_background: true. Идея простая - субагент работает в фоне, не блокирует основную сессию. Проблема в том, что фоновый субагент не может показать permission prompt. А без подтверждения Write, Bash и другие инструменты, требующие разрешения, просто тихо отклоняются.
Я наступил на это в блог-пайплайне. Запустил три субагента-ресёрчера в background через Task tool. Все три отработали - собрали данные через exa.ai, сформировали результаты. Дальше каждый попытался записать собранное в файл через Write tool. Permission denied. Попробовали Bash - тоже denied. Субагенты вернулись с бодрым сообщением “я всё нашёл, но не могу записать файл”. Данные собраны, а результат - ноль.
Баг открыт с января этого года. Есть несколько issues на GitHub - #18172, #26851, #30693. Воспроизводится на macOS и WSL. Документация при этом противоречит сама себе: в одном месте написано, что субагенты наследуют все инструменты включая MCP, в другом - что MCP tools недоступны в background.
Workaround оказался тупым - запускать субагентов в foreground. Да, они блокируют сессию и работают последовательно. Зато работают. Правило: background - только для read-only задач. Всё, что пишет файлы - в foreground.
Камень 2: Ваш субагент тайно работает на дешёвой модели
Вы запускаете основную сессию на Opus. Создаёте субагент и ожидаете, что он тоже работает на Opus. А он работает на Haiku 4.5.
Один разработчик подключил OpenTelemetry-трейсинг к своему пайплайну и увидел неожиданную картину: при первом взгляде на дашборд казалось, что большинство API-вызовов идут к Haiku, хотя основная сессия крутилась на Opus. При детальном разборе доля Haiku оказалась около трети по проектам, но по числу вызовов (не токенов) Haiku доминировал. Explore-агент по умолчанию использует Haiku 4.5 - это by design, но нигде явно не подсвечено. Три разных проявления одной проблемы зафиксированы в issues #29768, #18346, #17562: Explore наследует модель родителя вместо Haiku, параметр model: opus молча подменяется на Sonnet, shorthand-имена вроде haiku вызывают 404.
Как заметить? Качество ответов субагента ощутимо ниже, чем у основной сессии. Субагент “тупит” на задачах, которые основной агент щёлкает без проблем. Подключите трейсинг - картина станет очевидной.
Явно указывайте модель в конфигурации каждого субагента. Не полагайтесь на наследование от родителя - оно работает непредсказуемо. Проверяйте через логи, какая модель реально обрабатывает запросы.
Камень 3: 5+ параллельных субагентов = гарантированный crash
Запустить восемь субагентов параллельно технически можно. Практически - гарантированный crash сессии.
Механика простая. Каждый субагент возвращает результат. Результаты объединяются в родительской сессии. Пять субагентов, каждый вернул развёрнутый ответ - и контекстное окно переполнено. Сессия входит в “death spiral”: не может обработать объединённый результат, не может сжать контекст. Зависает или падает.
Люди фиксируют это регулярно. Issues #23463, #15191, #25547 описывают одну и ту же картину с разных сторон. Борис Черни, создатель Claude Code, запускает 5 параллельных сессий в iTerm2 плюс несколько в веб-интерфейсе - но это отдельные сессии с изоляцией через git worktrees, а не субагенты в одном контексте. Разница принципиальная.
Практический лимит - 3-4 параллельных субагента. Если задач больше - стройте sequential pipeline, где следующая пачка запускается после завершения предыдущей.
Камень 4: Один отклонённый промпт блокирует всех
Запустили три субагента параллельно. Один запросил permission на запись файла. Вы нажали deny. И обнаружили, что остановились все три.
Deny permission одного субагента блокирует все параллельные агенты. После compaction (сжатия контекста) теряются ID фоновых агентов - восстановить связь с ними уже нельзя. Issues #2148, #29263.
Отдельная боль - Task tool игнорирует ask permission rules из конфигурации. Только deny-правила работают корректно. Вы не можете заранее разрешить субагенту писать в нужные директории через настройки - только запретить.
Workaround: настройте allowlists заранее в settings.local.json для каждого агента. Для доверенных пайплайнов есть --dangerously-skip-permissions, но тут надо понимать риски - субагент с полными правами может натворить дел. Минимизируйте количество операций, требующих подтверждения.
Камень 5: После 15-20 итераций агенты “забывают” свои роли
Длинные мульти-агентные сессии деградируют. Субагенты начинают дублировать работу друг друга, забывают свой первоначальный промпт, путают роли. Ограничение текущих LLM при работе с длинным контекстом, и ни один инструмент от этого не застрахован.
Issue #24256 описывает типичный сценарий. Balaji Viswanathan, у которого за плечами тысячи часов работы с Claude Code, формулирует прямо: “The biggest bottleneck is me. The agents go terrible when I let them go long without supervision.” Я пришёл к тому же выводу на своём блог-пайплайне: стоит отвлечься на полчаса - и три агента уже пишут одно и то же в разные файлы.
Помогают короткие сессии с чекпоинтами. Запустили субагентов, получили результат, проверили, начали новую сессию. Чёткие роли прописаны в CLAUDE.md - routing framework, где указано, какие задачи идут в parallel, какие в sequential. Используйте delegate mode с явными файловыми границами для каждого агента.
Три правила на стену
Субагенты - мощный инструмент, но сырой. Документация противоречит себе, баги висят месяцами.
После своих граблей с блог-пайплайном я выработал три правила:
- Background - только для чтения. Всё, что пишет файлы, запускай в foreground.
- Максимум 4 параллельных субагента. Больше - sequential pipeline.
- Короткие сессии. После 15-20 итераций - чекпоинт и перезапуск.
Начните с одного субагента. Убедитесь, что он работает как ожидается. Добавляйте следующих по мере понимания ограничений. Мульти-агентные пайплайны - это не “запустил и забыл”, а “запустил, присматриваешь, чинишь, перезапускаешь”. Когда они работают - это реально экономит часы. Но до этого момента придётся повозиться.