MODULE_11 · УРОК 11.3

Extension points

Реестр из прошлого урока отвечает на вопрос «какие инструменты есть». И совершенно не отвечает на вопрос «что происходит вокруг каждого вызова». А хотелок там накапливается изрядно: логировать все вызовы, запрещать запись в .env, ужесточать команды политикой проекта, коммитить недоделанное на выходе из сессии. Это заботы уровня всей сессии, и запихивать их внутрь конкретного tool - верный способ через месяц не найти, где же спрятана проверка.

Инструмент для таких задач один - события. Harness объявляет, что с ним происходит, расширения подписываются и решают: пропустить дальше, заблокировать или подменить данные. Урок чисто теоретический - код писать не нужно, и это не лень автора. Контракт событий стоит продумать до того, как вы напишете dict на тридцать строк и потом полгода будете жить с его формой.

ЧТО ПОЛУЧИТСЯ Сможете описать шину событий, три типа ответа обработчика (пропустить, заблокировать, изменить) и правила цепочки, из-за которых порядок подписок неожиданно много значит.

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

  • Шина событий (event bus) - список обработчиков для каждого имени события плюс функция emit, которая прогоняет их по очереди. Ничего мистического, обычный словарь со списками внутри.
  • block и modify - два способа обработчика вмешаться: остановить вызов совсем или подменить данные и пустить дело дальше. Третий вариант - промолчать, и он самый частый.

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

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

Поверхность событий

Начнём с контракта. Вот весь набор мест, где harness подаёт голос, и весь набор ответов, которые он готов услышать:

# контракт идеи
LifecycleEvent = (
    "session_start"
    | "tool_call"
    | "tool_result"
    | "session_before_compact"
    | "session_shutdown"
)

# handler возвращает None / {} - пропустить дальше
# или {"block": True, "reason": "..."}
# или {"modify": {...}}

Пять имён - это нарочно мало. Соблазн предусмотреть двадцать событий на все случаи жизни велик, но потом их приходится поддерживать, а половину никто так и не использует. Эти пять закрывают те места, куда расширения лезут в реальности; шестое добавите, когда упрётесь в конкретную задачу.

Четыре примера

Абстракция становится понятной на живых сценариях, так что вот четыре штуки, от совершенно безобидного до слегка наглого.

1. Лог каждого tool_call

async def on_tool_call(data):
    print(f"[log] {data['tool_name']}: {data['input']}", file=sys.stderr)
    # без return - пропустить дальше

2. Блок записи в защищённые файлы

PROTECTED = [".env", "uv.lock"]

async def on_tool_call(data):
    if data["tool_name"] != "write":
        return
    path = str(data["input"].get("path", ""))
    if any(path.endswith(p) for p in PROTECTED):
        return {
            "block": True,
            "reason": f"{path} защищён политикой проекта",
        }

Дальше происходит важное: harness не выполняет инструмент и отдаёт модели вместо результата ваш reason. Модель читает политику обычным текстом, понимает, почему её остановили, и может честно об этом написать в отчёте, вместо того чтобы биться в закрытую дверь ещё три раза.

3. Подсказка перед compaction

async def on_before_compact(data):
    return {
        "modify": {
            "extra_instructions": (
                "Сохрани все safety/approval правила после сжатия истории."
            )
        }
    }

Сжатие истории - это тот самый момент, когда из контекста особенно легко утекают правила безопасности: они старые, они не менялись, их жалеют меньше всего. Ответ modify тут работает как напоминание, которое подсовывают ровно перед опасной операцией.

4. Автокоммит на shutdown

async def on_shutdown(data):
    sandbox = data["sandbox"]
    status = await sandbox.exec("git status --porcelain")
    if status["stdout"].strip():
        await sandbox.exec(
            'git add -A && git commit -m "WIP: auto-save"'
        )

По духу это тот же before_stop из урока 4.5, только обобщённый до любой сессии и любого выхода. Обратите внимание, как дёшево такое расширение живёт снаружи: захотели автосохранение - подписались, надоело - отписались, harness об этом даже не узнал.

Правило цепочки

На одно событие обработчиков может быть несколько, и вот тут начинается самое неочевидное. Идут они в порядке регистрации. Первый же block обрывает цепочку, и модель получает именно его reason. А если кто-то вернул modify, все следующие обработчики видят уже изменённые данные, не исходные.

Запросили tool
  → emit tool_call
       1. лог (pass)
       2. protected files (может block)
       3. project policy (может block)
  → если block: reason модели, execute нет
  → иначе: execute
  → emit tool_result
       1. лог результата
       2. telemetry

Логирование стоит первым не из вежливости: так вы видите саму попытку, даже если её тут же запретили, а это как раз самое интересное в разборе инцидентов. Телеметрия, наоборот, вешается после результата, чтобы отражать то, что действительно выполнялось. Перепутаете порядок - и в трейсе окажется ровно половина истории, причём не та половина, которая нужна.

Как стыкуется с уже сделанным

К этому моменту в harness уже несколько механизмов с похожими обязанностями, и их легко перепутать. Разложим по полкам, пока не превратилось в кашу.

  • Approval (модуль 2) - режим сессии (кто решает). По-прежнему на уровне bash/конфига.
  • Шина - вокруг tools. Handler на tool_call может заблокировать даже то, что approval пропустил (урок 8.2 - тот же слой политик).
  • Lifecycle 4.5 - after_start / before_stop ≈ удобные имена для session_start / session_shutdown.
  • Skills 11.1 - отдельная поверхность retrieval. Модель решает грузить или нет; шина тут ни при чём.

Если собрать картинку целиком, получается слоёный пирог: инструменты внизу, вокруг них события, по краям сессии lifecycle, сбоку skills как знания, а реестр служит входной дверью для новых инструментов. У каждого слоя своя работа, и как только один начнёт делать работу другого, вы это почувствуете в первый же вечер отладки.

ПОЧЕМУ ЭТО ПОСЛЕДНИЙ УРОК Шина - самая гибкая поверхность в harness и по совместительству самая опасная. Один неудачный обработчик подвесит агента, залогирует секрет в открытом виде или запретит совершенно нормальную работу, и искать это вы будете долго. Поэтому она стоит в конце: после инструментов, песочницы, промптов, контекста, субагентов и lifecycle вы уже понимаете, во что втыкаетесь. Дай такую свободу в третьем модуле - и любая проблема начнёт чиниться ещё одним on("tool_call"), а harness выродится в одного очень толстого подписчика.

Если соберёте сами (необязательно)

Урок теоретический, но руки могут зачесаться, и это нормально. Тогда идите маленькими шагами и начните с самого безобидного подписчика:

  1. dict[str, list[Handler]] + emit по порядку с early-exit на block.
  2. Вставить emit перед execute tool и после результата.
  3. Первые два подписчика - обёртки над lifecycle 4.5.
  4. Сначала только logging-расширение, потом blocking.

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

Проверять будем не вывод в терминале, а собственное понимание. Четыре вопроса, честно и без подглядывания в текст выше.

  1. Назовите пять lifecycle-событий без подглядывания.
  2. Для каждого - одно реалистичное расширение.
  3. Два handler на tool_call оба вернули block - чей reason увидит модель? (обычно - первого, кто заблокировал.)
  4. Чем шина дополняет approval из модуля 2, а чем не заменяет?

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

  • Называете пять событий
  • Объясняете pass / block / modify
  • Можете проследить цепочку handler и предсказать итог
  • Понимаете, как шина дополняет approval, а не выкидывает его
КУРС СОБРАН Одиннадцать модулей назад у вас был чат, который умел только разговаривать. Теперь это harness: с инструментами и песочницей, с управлением контекстом и субагентами, с lifecycle, участием человека в опасных решениях, планом и верификацией, поверхностями и точками расширения. Дальше начинается ваш собственный проект, и рецепт на нём тот же, что был весь курс: ужесточайте описания инструментов, выносите знания в skills, вешайте политики на шину - и не раздувайте ядро. Оно у вас получилось маленьким, пусть таким и останется.