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 как знания, а реестр служит входной дверью для новых инструментов. У каждого слоя своя работа, и как только один начнёт делать работу другого, вы это почувствуете в первый же вечер отладки.
on("tool_call"), а harness
выродится в одного очень толстого подписчика.
Если соберёте сами (необязательно)
Урок теоретический, но руки могут зачесаться, и это нормально. Тогда идите маленькими шагами и начните с самого безобидного подписчика:
dict[str, list[Handler]]+emitпо порядку с early-exit на block.- Вставить emit перед execute tool и после результата.
- Первые два подписчика - обёртки над lifecycle 4.5.
- Сначала только logging-расширение, потом blocking.
Проверьте (без кода)
Проверять будем не вывод в терминале, а собственное понимание. Четыре вопроса, честно и без подглядывания в текст выше.
- Назовите пять lifecycle-событий без подглядывания.
- Для каждого - одно реалистичное расширение.
- Два handler на tool_call оба вернули block - чей reason увидит модель? (обычно - первого, кто заблокировал.)
- Чем шина дополняет approval из модуля 2, а чем не заменяет?
Готово, если:
- Называете пять событий
- Объясняете pass / block / modify
- Можете проследить цепочку handler и предсказать итог
- Понимаете, как шина дополняет approval, а не выкидывает его