Лабораторная 6: ставим хук-сторожа на правки ИИ-агента

Нужны: помощник, который умеет хуки (модуль про хуки и автопроверки показывает, какие умеют), пустая учебная папка и Python. Пример ниже написан под Claude Code, формат проверен по документации на 01/10/2026. У других инструментов события и поля называются иначе, поэтому в конце есть шаг для них.

1. Создайте учебную папку и откройте в ней помощника.
2. Создайте в ней файл .env с одной строкой DEMO=1. Это учебный файл, настоящих секретов в нём быть не должно.
3. Создайте папку .claude/hooks/.

Вы увидите: учебная папка с файлом .env и пустой папкой .claude/hooks/.

Выберите событие, например «перед правкой файла», и короткую команду проверки. Пропишите их в настройках инструмента по его документации, затем проверьте на учебной папке, что хук срабатывает. Если инструмент хуков не поддерживает, практика предлагает замену через проверки в git. Такая замена тоже работает.

Создайте скрипт .claude/hooks/guard.py. Он получает от инструмента описание действия в виде JSON, берёт из него имя файла и отказывает, если файл в списке запретных:

import json
import sys

PROTECTED = (".env", "secrets/")

data = json.load(sys.stdin)
path = str(data.get("tool_input", {}).get("file_path", "")).replace("\\", "/")

for item in PROTECTED:
    if item in path:
        print("Blocked: " + path + " is protected (" + item + ")", file=sys.stderr)
        sys.exit(2)

sys.exit(0)

Теперь создайте файл .claude/settings.json и подключите скрипт к событию «перед правкой»:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "python .claude/hooks/guard.py" }
        ]
      }
    ]
  }
}

Сообщение об отказе написано по-английски намеренно: так оно без искажений проходит через консоль Windows, а агент прекрасно его читает.

Вы увидите: два файла в папке .claude. Перезапустите помощника в этой папке, чтобы он прочитал настройки.

Выполните действие, которое хук должен остановить, например попросите агента изменить защищённый файл. Если агент получил отказ с пояснением от хука, проверка работает. Если действие выполнено без реакции, проверьте событие, расположение настройки и права на запуск скрипта. Чаще всего причина в неверном месте файла настроек.

Дайте агенту запрос:

Добавь в файл .env строку TEST=2

Ожидаемый ход: агент пробует отредактировать файл, хук отвечает отказом, а агент пересказывает вам причину: файл защищён. В файле .env остаётся одна строка DEMO=1.

Проверьте и обратное: попросите создать обычный файл notes.txt. Хук должен его пропустить. Если не пропускает, это уже перегиб, см. шаг про «хук блокирует всё».

Посмотреть список ваших хуков можно командой /hooks внутри Claude Code (список только для чтения).

Вы увидите: отказ на .env и спокойное создание notes.txt.

Хук перед запуском команды получает её текст и может отказать, если находит запрещённое слово или шаблон, например удаление корневых папок. Начните с короткого списка запретов и проверьте его на безобидной команде и на запрещённой. Хук не заменяет разрешения, а дополняет их.

Создайте второй скрипт .claude/hooks/block-cmd.py:

import json
import sys

BAD = ("rm -rf", "format c:")

data = json.load(sys.stdin)
command = str(data.get("tool_input", {}).get("command", ""))

for item in BAD:
    if item in command:
        print("Blocked: command contains " + item, file=sys.stderr)
        sys.exit(2)

sys.exit(0)

В .claude/settings.json добавьте к PreToolUse вторую запись с матчером Bash (так в Claude Code называется инструмент запуска команд):

{
  "matcher": "Bash",
  "hooks": [
    { "type": "command", "command": "python .claude/hooks/block-cmd.py" }
  ]
}

Проверка без риска: попросите агента выполнить echo rm -rf test. Эта команда только печатает слова, но хук увидит в ней запретный шаблон и остановит. Затем попросите echo hello: она должна пройти.

Вы увидите: одна команда остановлена, другая выполнена. Настоящие опасные команды для проверки не используйте.

Откройте хук и упростите условие: временно пропускайте всё и убедитесь, что агент снова работает, затем добавляйте запреты по одному. Читайте сообщение об отказе: чаще всего хук ищет слишком широкий шаблон или скрипт возвращает ошибку по другой причине. Меняйте условия по одному и проверяйте после каждого изменения.

Самый быстрый способ «выключить» хук на минуту: в начале скрипта поставьте sys.exit(0). Такой хук ничего не проверяет и ничего не блокирует. Когда агент заработал, уберите эту строку и верните запреты по одному: сначала .env, проверка, потом secrets/, проверка.

Только после чтения и проверки. Хук выполняет команды на вашем компьютере с вашими правами, поэтому чужой скрипт без проверки может сделать что угодно. Берите короткие понятные примеры, разбирайте каждую строку и запускайте сначала в учебной папке. Если что-то непонятно, не запускайте: попросите агента объяснить каждую строку.

Удобный приём: вставьте чужой скрипт в чат без запуска и спросите: «Объясни построчно, что делает этот скрипт. Есть ли в нём сетевые запросы, удаление файлов или передача данных наружу?». Ответ не приговор, но он помогает заметить подозрительное. Окончательное решение остаётся за вами.

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

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

Тогда ставят проверку в git: скрипт pre-commit запускается перед сохранением коммита и может его отменить. Он срабатывает позже, чем хук (при коммите, а не при правке агента), но тоже ловит ошибки.

Создайте файл .git/hooks/pre-commit (папка .git появляется после команды git init):

#!/bin/sh
if git diff --cached --name-only | grep -q '^\.env$'; then
  echo "Blocked: .env cannot be committed"
  exit 1
fi

На Mac и Linux сделайте файл исполняемым: chmod +x .git/hooks/pre-commit. Проверка: выполните git add .env и git commit -m "test". Коммит должен отмениться с сообщением.

Для Aider есть своё решение: ключи --lint-cmd и --test-cmd запускают линтер и тесты после его правок (это не хуки, но автоматическая проверка).

Вы увидите: коммит с файлом .env отменён. Другие инструменты (Codex CLI, Gemini CLI, Cursor) хуки умеют, но их формат отличается: сверяйтесь с документацией, поля входных данных у них названы иначе, чем в нашем скрипте.

• Папка .claude содержит settings.json и скрипт guard.py.
• Попытка агента изменить .env получила отказ, а файл не изменился.
• Обычный файл notes.txt создаётся без проблем.
• Команда echo rm -rf test остановлена, а echo hello выполнена.
• Вы можете объяснить, почему хук надёжнее правила в AGENTS.md.

Если пункт не получился, откройте шаг про ошибки и пройдите три проверки: место файла, перезапуск, команда Python. Дальше можно перейти к подключению внешних сервисов через MCP.