dotfiles/agents/.agents/skills/claude-subagent-playbook/references/codex-companion.md

Codex companion из Claude Code: команды и ловушки

Проверено 2026-07-06 (плагин openai-codex/codex 1.0.5). Путь к скрипту зависит от версии — найди актуальный:

ls ~/.claude/plugins/cache/openai-codex/codex/*/scripts/codex-companion.mjs

Далее $CC = node <найденный путь>.

Команды

$CC task --background --write --fresh "промпт"   # реализация (пишет файлы)
$CC adversarial-review --background --scope working-tree "фокус ревью"
$CC status                    # все задачи; status <job-id> — одна, с прогрессом
$CC result <job-id>           # финальный отчёт завершённой задачи
$CC cancel <job-id>
$CC task-resume-candidate --json   # есть ли возобновляемый тред этой сессии

Запуск через раннера-субагента — рекомендуемый путь

Приём из /adversarial-review: оркестратор не зовёт CLI сам и не городит мониторы — фоновый субагент-раннер синхронно гоняет команду у себя, шум остаётся в нём, а завершение субагента само будит оркестратора.

Ключевое правило: раннеру — готовую команду, не постановку задачи. Получив постановку, «тонкий» агент реализует её сам (ловушка форвардера). Промпт задачи живёт только внутри строки-аргумента команды.

Рецепт: Agent tool, subagent_type: "general-purpose" (или fast-worker, если есть), run_in_background: true, промпт раннеру:

Выполни ровно одну команду Bash, ничего не решай и не делай сверх неё:
$CC task --wait --write --fresh "<полный промпт задачи>" \
  > /tmp/<scratchpad>/codex-run-<id>.log 2>&1
Затем верни: код возврата, путь к логу и последние ~30 строк лога.

Так же запускается и ревью (adversarial-review --wait ...). Прямой вызов CLI с --background + фоновый bash-монитор (ниже) — запасной путь, когда раннер нежелателен (например, экономия субагентов).

Ловушки (все выстраданы)

• Без --write среда Codex только на чтение. Задача «реализуй…» без этого флага молча не сможет писать файлы.
• task --help не существует — строка --help уходит Кодексу как промпт и создаёт мусорный тред. Синтаксис смотри $CC без аргументов.
• --fresh против --resume-last: resume-last цепляет самый свежий тред, а им может оказаться тред ревью, не реализации. Для точечных починок надёжнее --fresh + точный промпт («добавь только X, ничего больше не меняй»).
• Коммит запрещай промптом («коммит не делай — оставь в рабочем дереве»): ревью идёт по незакоммиченному дифу, коммитит оркестратор.
• Тонкому агенту-форвардеру не давай содержательный промпт. Субагент codex:codex-rescue должен только пробросить команду; получив постановку задачи, он реализует её сам вместо передачи (казус 2026-07-06 — второй писатель в дереве). Либо зови companion напрямую из Bash, либо давай форвардеру только готовую команду.

Мониторинг фоновых задач (запасной путь)

При прямом --background уведомлений от companion нет — повесь фоновый bash-монитор, он разбудит оркестратора по завершении:

# run_in_background: true
for i in $(seq 1 120); do
  st=$($CC status <job-id> 2>/dev/null)
  if echo "$st" | grep -q '| running |'; then sleep 30; else echo FINISHED; exit 0; fi
done

Парсить plain-text: status --json устроен иначе, чем кажется (грабли 2026-07-06 — монитор на JSON-поле state крутился вечно на unknown).

Фоновые Claude-субагенты (Agent tool)

• Ревьюеров запускай model: "opus" (экономия лимитов; ревью на Фабуле — ~60k токенов за прогон).
• Фоновый агент по завершении шлёт idle-уведомление без содержимого. Финальный отчёт запроси SendMessage: «верни готовый результат, ничего нового не проверяй».
• Проверяй, что делегат сделал именно то, что просили: git status до и после, кто и когда трогал файлы (stat -c '%y'), прежде чем запускать следующего писателя.