Claude Code Hooks

Коротко: Команди оболонки (або промпти/агенти), які Claude Code автоматично виконує в певні моменти робочого процесу — наприклад, перед запуском інструмента, після того як Claude закінчив відповідати, або коли сеанс починається чи закінчується.

Докладніше: Хуки налаштовуються в settings.json за подіями (наприклад, Stop, PreToolUse, SessionEnd) і, за бажання, з «матчером» (наприклад, лише для певних інструментів). Важливо: Stop спрацьовує після кожного ходу відповіді, а не один раз наприкінці всієї розмови — для «один раз за сеанс» призначений SessionEnd.

Наш контекст: Як тест ми зробили хук Stop, який після кожної відповіді вивантажував повну стенограму JSONL 1:1 у нотатку Obsidian — але потім відмовилися від нього, бо ви хотіли структуровані нотатки за змістом, а не сирий текст. Тепер я пишу глосарні статті на кшталт цієї наживо під час розмови.

Подробиці

Конфігурація та матчери

Хуки налаштовуються за подіями в settings.json (або в settings.local.json для локальних, що не потрапляють у коміт, перевизначень). Типове визначення виглядає так:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "echo 'Bash is being run' >> log.txt" }]
      }
    ]
  }
}

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

Доступні типи подій

Окрім PreToolUse/PostToolUse (до й після кожного виконання інструмента) та Stop (після кожного ходу відповіді), є, серед іншого, SessionStart/SessionEnd (один раз на початку/наприкінці сеансу), UserPromptSubmit (коли користувач надсилає повідомлення, до його обробки Claude) і PreCompact (перед стисненням контексту). Кожен тип події отримує через stdin різні структуровані дані (наприклад, для PreToolUse — назву інструмента та його вхідні параметри у вигляді JSON) — скрипт хука може прочитати ці дані й на їх основі вирішити, чи реагувати і як.

Блокування викликів інструментів

Хук PreToolUse може навіть заблокувати виконання інструмента (відповівши певним кодом завершення чи певним виводом), що можна використати, наприклад, для власних правил безпеки — скажімо, щоб повністю заборонити певні команди Bash незалежно від власного судження Claude. Це важлива відмінність від простих інструкцій у CLAUDE.md: хук — це жорстке правило, яке забезпечує сама обв’язка (harness) і яке не можна обійти хитрим формулюванням промпта, тоді як текстові інструкції в принципі завжди лише рекомендації щодо поведінки, яких дотримується модель.

Команди оболонки та промпти/агенти

Окрім простих команд оболонки хуки можуть запускати й складніші промпти чи спеціальних агентів, а не лише однорядкові скрипти. Це дає змогу, наприклад, зробити хук Stop, який після кожної відповіді автоматично спрямовує агента-рецензента на останні змінені файли, або хук SessionEnd, що створює зведення сеансу — значно потужніше за простий скрипт оболонки, але й з відповідно вищою витратою ресурсів, бо додається ще один виклик LLM.

Важливі відмінності між подібними за звучанням подіями

Stop спрацьовує після кожного ходу відповіді, а не один раз наприкінці всієї розмови — легко недооцінена пастка, якщо насправді потрібно «один раз за сеанс». Для цієї мети призначений SessionEnd; він справді спрацьовує лише коли закінчується весь сеанс. Хто плутає їх, ризикує отримати або хук, що надмірно часто виконується на кожному ході відповіді, або такий, що не реагує в справжньому кінці, як задумано.

Див. також: JSONL