docs(skill): claude-subagent-playbook — handoff прогона 2026-07-07

- Зачем:
  - зафиксировать уроки боевого прогона для сессии доработки скилла.
- Что:
  - handoff с шестью уроками: таймер-подстраховка и её экономика, прямой
    codex exec вместо плагина (с номерами issues), поправки пользователя
    к флагам CLI, идея читающего форвардера, вердикт из логов умершего
    агента, паттерн ожидания через отслеживаемый фоновый Bash.
- Проверка:
  - чтение handoff; коммит только одного файла, чужие untracked не задеты.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

agents/.agents/skills/claude-subagent-playbook/handoffs/20260707-2234-uroki-progona-i-codex-cli.md

@@ -0,0 +1,60 @@
+# Handoff: уроки прогона 2026-07-07 для доработки скилла
+
+Дата: 2026-07-07 22:34. Прогон: проверка пути менти + диагноз флаки-гейта
+в репозитории clickstream-ch-kafka-superset-demo (Claude — оркестратор,
+два Claude-субагента, Codex-диагност через плагин).
+
+## Что сработало
+
+- Пара «читатель-скептик (Opus) + прогонщик-механик (Sonnet)» параллельно:
+  читатель нашёл 4 доковых находки, прогонщик — реальное падение гейта.
+- «Шум в файлы» окупился дважды: когда прогонщик умер без отчёта, вердикт
+  собрался из его логов; когда форвардер Codex соврал «finished», результат
+  забрался из output-файла фонового задания.
+- Перепроверка ключевого факта диагноза своими глазами (grep по коду) —
+  дёшево и поймала бы подмену анализа (bug #158 плагина).
+
+## Находки для SKILL.md / references/lessons.md
+
+1. **Таймер-подстраховка для фоновых субагентов** (совет пользователя):
+   субагенты молча останавливаются («жду уведомления», которого не будет;
+   «закончил и умер без отчёта»). Ставить ScheduleWakeup сроком больше
+   ожидаемой длительности, при пробуждении смотреть логи агента самому,
+   снимать таймер по приходу результата. Экономика: кэш мастер-сессии живёт
+   ~1 час — пробуждение в пределах часа тёплое (~0,1×); таймер — страховка,
+   не поллинг.
+2. **Прямой `codex exec` вместо плагина** (веб-ресёрч, первоисточники):
+   обёртка codex-companion.mjs — багованная машина фоновых задач
+   (openai/codex-plugin-cc issues #279, #158, #49, #277; #158 — молчаливая
+   подмена Codex своим анализом, ломает слепое ревью разных родословных).
+   Рекомендация: CLI в собственном run_in_background Bash оркестратора
+   (pid/код выхода/лог у нас), `codex exec resume <session-id>` для раундов.
+3. **Поправки пользователя к флагам CLI** (важно, расходится с ресёрчем):
+   НЕ дефолтить `-s read-only -c approval_policy=never`. Рабочая практика:
+   сессия с правом записи, ограниченная промтом (иначе Codex не гоняет тесты
+   и не гуглит), плюс авто-режим аппрува, где отдельная модель оценивает
+   безопасность действий. `timeout 600` мал — сессии запросто длиннее,
+   таймаут подбирать под задачу. В скилле развести два режима: «ревьюер»
+   (можно жёстко read-only) и «исполнитель/диагност» (запись + авто-аппрув).
+4. **Идея пользователя для форвардера:** субагент-обёртка мог бы читать
+   историю сессии Codex (JSONL / resume) и отвечать на поллинг оркестратора,
+   вместо «выстрелил и умер». Казус прогона: codex-rescue отказался проверять
+   статус своего же вызова, сославшись на мандат «только один проброс».
+5. **Казус «умер без отчёта»:** правильный ход — не воскрешать агента ради
+   отчёта, а собрать вердикт из его логов (дополнение к приёму «шум в файлы»).
+6. **Правильный паттерн ожидания у субагента** (это реально разбудило
+   заснувшего прогонщика): долгий шаг ждать через отслеживаемый харнесом
+   фоновый Bash (`run_in_background`) с командой-ожидателем под `timeout` —
+   `until grep -q '<маркер>' <лог>; do sleep 30; done` — тогда харнес
+   переинвоцирует агента по выходу процесса. Самодельные «фоновые мониторы»
+   и «жду уведомления» без отслеживаемого процесса не будят никогда.
+   Вписывать этот паттерн в промпт раннера сразу, а не после двух побудок.
+
+## Открытое
+
+- Механику references/codex-companion.md стоит пересмотреть в пользу прямого
+  CLI (пункты 2–3); плагин оставить для интерактива.
+- Определения deep-reasoner/fast-worker из references/claude-agents.md
+  созданы в репозитории демо (закоммичены); фрагмент «Orchestration
+  workflow» в CLAUDE.md демо-репозитория НЕ добавлен — пользователь решил
+  не засорять учебный контракт, вопрос «куда класть» открыт.