Хуки для ШІ-агента: захист від небезпечних команд і витоків

Що таке хук простими словами

Уяви, що ти дав дитині ключі від кухні. Загалом вона молодець: готує, миє посуд, складає тарілки стосиком. Але раз на сто заходів зопалу може встромити виделку в розетку або викинути твій паспорт - він же лежав на столі, заважав.

ШІ-агент влаштований точнісінько так само. У 99% випадків усе добре. А в решту 1% він спокійно виконає команду, яка видалить твою папку, заллє пароль у відкритий репозиторій або знесе робочу базу. І зробить це бадьоро, з упевненим обличчям і фразою «Готово!».

Щоб цей 1% не стався, ставлять хук Хук (від англ. hook - «гачок, перехоплювач») - це код, який автоматично спрацьовує в певний момент: перед командою, перед записом у файл, наприкінці відповіді агента. Він встигає перевірити дію ще до того, як вона сталася. - щось на кшталт охоронця на вході. Перед кожною небезпечною дією він стає і каже: «Так, стоп. А ну покажи, що ти задумав».

Навіщо вайбкодеру захист від небезпечних дій агента

Ти вайбкодер. Скидаєш на агента купу рутини - і правильно робиш. Але довіра без страховки одного разу коштує тобі нервів і даних. Хуки потрібні, щоб ти:

• спав спокійно - агент фізично не виконає те, що ти заборонив;
• не повторював одну й ту саму заборону по сто разів у кожному новому чаті;
• ловив помилки заздалегідь, а не розгрібав наслідки з кухлем холодної кави о третій ночі;
• не залив випадково паролі та ключі у відкритий доступ - класика, на якій обпеклися всі.

Між «агент видалив мені три дні роботи» і «агент спробував, але хук його зупинив» лежить один маленький текстовий файл із правилом. Зараз навчимося його писати.

Як працюють hookify-правила

Писати хуки руками на коді - боляче. Тому є інструмент hookify hookify - простий спосіб задавати хуки звичайним текстом, без програмування. Ти пишеш правило в маркдаун-файлі: на що дивитися і що сказати або зробити. Жодного коду. : ти створюєш звичайний текстовий файл-правило, і все. Жодного коду.

Кожне правило відповідає на три запитання.

КОЛИ дивитися - подія (event)

Охоронець не стирчить одразу всюди. Ти кажеш, у який момент йому прокидатися:

• bash - коли агент збирається виконати команду в терміналі (тут ловлять rm -rf, sudo та іншу важку артилерію);
• file - коли агент пише або редагує файл (тут ловлять паролі в коді й налагоджувальний мотлох);
• prompt - коли ти сам щось написав агенту;
• stop - момент, коли агент закінчив відповідь (зручно для нагадувалок);
• all - на будь-яку подію.

ЩО ловити - шаблон (pattern)

Це «словесний портрет» небезпечної дії. Технічно - патерн Патерн (регулярний вираз) - це шаблон для пошуку тексту. Наприклад, шаблон «rm один-або-більше-пробілів -rf» зловить команду видалення, хоч би як агент її написав - з одним пробілом чи з трьома. . Скажімо, шаблон rm\s+-rf зловить страшну команду видалення, навіть якщо агент впихне зайвий пробіл.

ЩО робити - дія (action)

Зловив охоронець порушника - і далі в нього два варіанти реакції:

• warn - попередити й пропустити. «Гей, ти точно хочеш це зробити? Ну гаразд, проходь». Режим за замовчуванням.
• block - заблокувати наглухо. «Стоп. Не пущу. Крапка». Дія не виконається взагалі.

Як виглядає hookify-правило

Саме правило - короткий текстовий файл. Згори між двома лініями --- ідуть налаштування, нижче - повідомлення, яке агент побачить, коли правило спрацює. От і вся конструкція.

Опишемо словами правило «блокуй небезпечне видалення файлів»:

• імʼя правила: block-rm-rf (імʼя краще починати з дієслова: warn-, block-, require-);
• увімкнено: так;
• подія: bash (стежимо за командами в терміналі);
• дія: block (блокуємо);
• шаблон: ловить команду видалення rm із прапорцями -rf;
• повідомлення: «Стоп. Це видалення без можливості відкату. Підтверди вручну, перш ніж продовжити».

Файли правил лежать у папці .claude всередині проєкту. І ось тут - найважливіша думка уроку.

Приклад: як хук ловить витік секретів

Ти майструєш свій перший стартап. Підключаєш платіжку, агент створює файл .env і кладе туди секретний ключ від Stripe. За пʼять хвилин ти просиш «залий усе на гітхаб», агент бадьоро робить git push - і твій грошовий ключ тепер бачить увесь інтернет. Ще пара годин - і хтось спокійно викачує по ньому ліміт. Вітаю, ти оплатив комусь вихідні.

Знайома катастрофа? А тепер дивись, як вона гаситься одним правилом.

Ти заздалегідь ставиш хук: «щойно агент пише щось схоже на API-ключ у файл .env - нагадай перевірити .gitignore». Ось промпт, який попросить агента зібрати такий захист за тебе.

Створи мені hookify-правило для захисту від витоку секретів.
Умови правила:

Подія - запис у файл (event file).
Спрацьовує, коли шлях файлу закінчується на .env
І коли в новому тексті трапляється API_KEY, SECRET або TOKEN.
Дія - попередити (warn), не блокувати.
Повідомлення агенту: «Ти пишеш секрет у .env. Перевір, що цей
файл додано в .gitignore і він не потрапить у публічний репозиторій».
Поклади правило в папку .claude проєкту і поясни мені простими
словами, що саме воно робить.

Гарне правило проти поганого

Хуки - потужна штука, але ними легко переборщити. Повісиш block на кожен чих - і агент перетвориться на паралітика, який кроку ступити не може. Ось як упіймати баланс.

Часті помилки новачка з хуками

• Думати, що слів у чаті достатньо. «Я ж просив не видаляти» - а агент забув після компакту. Заборона має жити у файлі.
• Вішати block на все підряд. Агент задихнеться, і ти сам у серцях вимкнеш хуки. Блокуй лише незворотне.
• Надто широкий шаблон. Заборонив слово rm - і агент більше не може написати слово «information». Роби шаблон точним.
• Заборона без підказки «а що тепер». Агент упнувся в стіну і ходить по колу. Пиши в повідомленні, як зробити правильно.
• Ігнорувати .gitignore для секретів. Хук попередив, а ти пропустив це повз вуха. Читай, що каже охоронець.
• Не перевірити, що правило взагалі спрацьовує. Попроси агента виконати тестову безпечну команду й переконайся, що хук її зловив.