MODULE_08 · УРОК 8.2

Approval config

Три режима проверки из модуля 2 - interactive, background и delegated - отвечают ровно на один вопрос: кто принимает решение, человек за клавиатурой, автоматика в CI или короткий список доверенных команд. Вопрос хороший, но он не единственный.

Есть второй, и звучит он иначе: что нельзя трогать никогда, даже если человек в порыве энтузиазма нажал «да»? Режимами это не выражается, сколько их ни добавляй. Нужен второй слой - политики, которые срабатывают на каждом вызове инструмента.

ЧТО ПОЛУЧИТСЯ Вы сможете назвать оба слоя проверки, выбрать подходящий под конкретную задачу и объяснить, почему они работают вместе, а не вместо друг друга. Это и называется защитой в глубину: слои независимы, и один не отменяет второй. Урок чисто теоретический - код писать не нужно, события мы соберём в модуле про расширяемость.

Слова, которые встретятся

  • Слой конфига - режим, выбранный на всю сессию: interactive, background или delegated из вашего approval.py.
  • Слой событий - подписка на каждый вызов инструмента, где можно запретить операцию, поправить её аргументы или молча пропустить дальше.
  • Defense in depth - защита в глубину, то есть два независимых фильтра подряд. Первый пропустил - у второго всё ещё есть право сказать «нет».

Какие файлы трогаем

Файл Что делать
проект ученика Не трогать. Урок чисто теоретический - код писать не нужно. Слой событий появится позже.

Слой 1: конфиг (у вас уже есть)

ApprovalConfig =
    {"mode": "interactive"}
  | {"mode": "background"}
  | {"mode": "delegated", "trust": list[str]}

Этот слой ставится один раз при старте и внутри сессии обычно не меняется. Он отвечает на вопрос, кто решает.

Слой 2: события (набросок)

Здесь всё динамичнее. На каждый вызов инструмента приходит обработчик, который волен запретить операцию, подправить её аргументы или пропустить как есть. И отвечает он уже на другой вопрос - какие правила у этого проекта.

# псевдокод идеи - в проект пока не копировать
async def on_tool_call(event):
    tool_name = event["tool_name"]
    inp = event["input"]

    if tool_name == "write" and str(inp.get("path", "")).endswith(".env"):
        return {"block": True, "reason": "Нельзя менять .env"}

    if tool_name == "bash":
        # пример: обернуть команду жёстче (идея, не готовый рецепт)
        inp["command"] = f"timeout 30s {inp['command']}"

    return {"block": False}

Когда какой слой

Ситуация Конфиг События
CI, всё автоматом background Избыточно
Субагент с узким trust delegated Не тот уровень
Запрет писать в конкретные файлы Слишком грубо Политика на путь
Обернуть bash (таймаут, изоляция) Не меняет вход Правка input
Правила именно этого репо Глобально на сессию Расширение под проект

Если свести таблицу к одной мысли: конфиг описывает операционный режим, то есть кто сейчас за клавиатурой, а события - тонкие правила, которые обычно рождаются из особенностей конкретного репозитория. Слегка пересекаются, но подменить друг друга не могут.

Как работают вместе

needs_approval = create_approval({"mode": "interactive"})

# позже, когда появится шина событий:
# on_tool_call: никогда не трогать .env - даже если человек сказал «да»

Читается это так. Конфиг говорит: режим interactive, человек подтверждает всё опасное. Событие добавляет: а .env мы не трогаем вообще, и обсуждать тут нечего. Порядок важен - событие срабатывает после того, как режим вынес своё решение, и до того, как инструмент реально запустится. Два фильтра подряд, и пройти надо оба.

Разделение не ради красоты архитектуры: у этих правил разные источники. Режим определяется тем, кто запускает harness прямо сейчас - вы с ноутбука, CI по расписанию или субагент из урока 6.3. Политики же диктует сам проект: файл с секретами неприкосновенен, каталог сборки только на чтение, продовые ключи живут в отдельном контуре. Попытка обслужить оба мира одним переключателем очень быстро превращается в кашу, где никто не помнит, что и почему запрещено.

КУДА ЭТО В КУРСЕ Первый слой у вас давно работает - он живёт в approval.py с урока 2.3. Шина событий и подписчики приедут в модуле про расширяемость, и там перехватчик на tool_call окажется отличным коротким примером, зачем эта шина вообще нужна. Пока достаточно держать картинку в голове.
ЧТО НЕ ДЕЛАТЬ СЕЙЧАС Соблазн велик, но не пилите самодельный pub/sub на коленке в main.py ради галочки. Без общей шины это выйдет мёртвым кодом, который через два урока придётся выбрасывать. Дождитесь модуля, где события станут общей точкой расширения, а проверка перед опасным действием - всего лишь одним из подписчиков.

Что добавить, когда дойдёте (чеклист на потом)

  1. Маленький typed emitter в harness.
  2. Перед каждым tool - emit tool_call.
  3. Подписчики возвращают {block, reason} или правят input.
  4. Один smoke-подписчик: блок записи в захардкоженный файл.

Проверьте (без кода)

  1. Для каждой строки таблицы выше - какой слой уместнее.
  2. Придумайте кейс, где нужны оба: что делает конфиг, что - событие.
  3. Вспомните проект, где правило «никогда не трогай X» спасло бы. Как бы звучала одна строка в on_tool_call?

Готово, если:

  • Объясняете слой конфига и на какой вопрос он отвечает
  • Объясняете слой событий и на какой вопрос он отвечает
  • Можете выбрать слой под типовую ситуацию
  • Можете набросать, как оба слоя работают вместе
ДАЛЬШЕ МОДУЛЬ 9 С человеком в цикле мы разобрались: агент умеет спрашивать, а опасные действия прикрыты двумя слоями. Следующий модуль про дисциплину самого агента - план перед работой и честная проверка после неё: todo-инструмент, привычка сначала искать, и контракт на проверку результата.