Hooks Claude Code: події, exit code 2 і безпека
Дізнайтеся, де налаштовуються hooks Claude Code, які події їх запускають, як exit code 2 скасовує виклик tool і які ризики безпеки це створює.
Що таке hook Claude Code
Hooks Claude Code — це shell-команди, які Claude Code запускає самостійно у визначені моменти свого життєвого циклу. У цьому полягає вся різниця між hook і файлом правил. Інструкція у CLAUDE.md — це порада, яку модель оцінює разом з усім іншим контекстом. Hook — це код, який виконується незалежно від того, погоджується з ним модель чи ні. Якщо ваш агент постійно пропускає formatter, про який ви вже двічі йому сказали, потрібна не наполегливіша інструкція, а hook.
Механізм простий. Ви реєструєте команду у файлі налаштувань під назвою події. Коли подія відбувається, Claude Code запускає вашу команду та записує дані події у її стандартний ввід (stdin) у форматі JSON (JavaScript object notation). Команда читає ці дані, виконує потрібну роботу й повертає код завершення. Код завершення 2 для hook PreToolUse скасовує виклик інструмента до його запуску. Усе, що ваш скрипт записав у стандартний потік помилок (stderr), передається моделі як причина, якщо тільки hook не виводить JSON із рішенням про блокування. У такому разі пріоритет має причина з цього JSON.
Назви подій і полів у цьому тексті взято з довідника hooks Claude Code, перевіреного 12 листопада 2026 року. Цей інтерфейс швидко змінюється, тому перед копіюванням JSON із будь-якої публікації, зокрема цієї, перевірте довідник для своєї версії. Виведіть власну версію командою claude --version.
Де зберігається конфігурація hook
Hook — це JSON-блок у файлі налаштувань. Його можна зберігати в шести місцях. Область дії файла визначає область дії hook.
~/.claude/settings.json: усі проєкти на вашому комп’ютері, але не на комп’ютерах інших користувачів..claude/settings.json: один проєкт, збережений у репозиторії. Усі, хто клонує репозиторій, отримають цей hook..claude/settings.local.json: один проєкт, лише на вашому комп’ютері.- Керовані параметри політики: для всієї організації, налаштовуються адміністратором.
hooks/hooks.jsonусередині plugin: активні, доки plugin увімкнений.- Frontmatter skill або subagent. Hook skill залишається активним до кінця сеансу після виклику skill, а hook subagent активний, доки працює цей subagent.
Записи hook із цих файлів об’єднуються, а не замінюють один одного. Файл налаштувань проєкту додає свої hook до hook у налаштуваннях користувача, а не замінює їх. Тому одна подія може містити кілька hook із різних файлів. Параметр "disableAllHooks": true вимикає їх, але є один виняток: hook із керованих параметрів політики продовжують працювати, якщо цей параметр також не застосовано в керованих налаштуваннях.
Виконайте /hooks у сеансі, щоб переглянути всі зареєстровані hook, згруповані за подіями, із зазначенням файла-джерела та matcher для кожного. Це меню доступне лише для читання, тому для зміни hook відредагуйте файл налаштувань. Спостерігач за файлами зазвичай підхоплює зміни без перезапуску.
Які події hook підтримує Claude Code
У довідці з hook перелічено тридцять три події — від SessionStart до SessionEnd. Вони охоплюють compaction, subagents, worktrees і configuration files. Для роботи із серверами зазвичай потрібні лише деякі з них.
PreToolUse: перед виконанням виклику інструмента, крімEndConversation. Це єдина подія, яка може блокувати виконання.PostToolUse: після успішного виконання виклику інструмента, крімEndConversation. Якщо виклик завершується помилкою, натомість спрацьовуєPostToolUseFailure. Тому hook, який має бачити кожен результат, повинен обробляти обидві події.PermissionRequest: коли для виклику інструмента потрібне рішення щодо дозволу. У цей момент з’явився б запит на підтвердження.UserPromptSubmit: після надсилання prompt, але до його обробки Claude. Текст у stdout успішного hook додається до контексту моделі.SessionStartіSessionEnd: під час кожного завершення сеансу.SessionStartтакож спрацьовує після compaction, якщо значення matcher дорівнюєcompact.Stop: коли Claude завершує відповідь. Подія спрацьовує один раз за turn, а не один раз після завершення завдання.
Для подій, які підтримують matchers, група може містити matcher. Воно визначає, для яких випадків запускається hook. Для подій інструментів matcher фільтрує виклики за назвою інструмента. Наприклад, "Edit|Write" спрацьовує під час редагування файлів і більше ні під час яких подій. Matchers чутливі до регістру. Порожній matcher спрацьовує для кожного випадку. Інструменти з MCP (model context protocol) server мають назви у форматі mcp__<server>__<tool>. Тому matcher "mcp__github__.*" вибирає інструменти одного сервера й не зачіпає інші.
Stop hooks мають особливість, яку потрібно врахувати до написання hook. Якщо Stop hook блокує виконання, модель повертається до роботи. За замовчуванням Claude Code ігнорує наступний block після восьми послідовних продовжень. Лічильник скидається щоразу, коли Claude викликає інструмент. Прочитайте поле stop_hook_active у вхідних даних hook і завершіть виконання з кодом 0, якщо його значення true. Інакше hook може постійно повертати Claude до роботи.
Що hook отримує через stdin
Коли Claude готується виконати npm test, hook типу PreToolUse для Bash читає через stdin такі дані:
{
"session_id": "abc123",
"cwd": "/home/deploy/myproject",
"hook_event_name": "PreToolUse",
"tool_name": "Bash",
"tool_input": {
"command": "npm test"
}
}До поширених полів вхідних даних належать session_id, cwd, transcript_path і hook_event_name; permission_mode надсилається не під час кожної події. Події інструментів містять додаткові поля tool_name, tool_input і tool_use_id. Інші події мають власні поля: UserPromptSubmit містить текст prompt, а SessionStart — source зі значенням startup, resume, clear, compact або fork.
jq — стандартний спосіб прочитати ці дані в shell-скрипті, але в мінімальному образі сервера його немає. Спочатку встановіть його за допомогою sudo apt install -y jq в Ubuntu і Debian.
Що статус виходу робить із поточним викликом інструмента
Є три результати.
- Exit 0 означає успішне виконання, і всі допустимі поля рішення в JSON залишаються чинними, зокрема блокування або відмова. Для
PreToolUseexit 0 без рішення не означає схвалення, тому звичайний процес перевірки дозволу все одно виконується. ДляUserPromptSubmit,UserPromptExpansion,SessionStartіPostModelSwitchзвичайний текст зі stdout додається до контексту моделі. Для більшості інших подій stdout надходить лише до журналу налагодження. - Exit 2 блокує дію для подій, які можна блокувати, зокрема для
PreToolUse, а stderr стає повідомленням, що супроводжує блокування, якщо тільки вихід у форматі JSON не містить рішення про блокування. У такому разі пріоритет має причина з JSON. Хто читає це повідомлення, залежить від події. ДляPreToolUseіStopмодель бачить його як причину. ДляUserPromptSubmitіPreModelSwitchвоно показується вам і не додається до контексту моделі. ДляPostToolUseіPostToolUseFailure, які не можна блокувати, блокування ігнорується, але stderr все одно передається моделі як зворотний зв’язок. Для більшості інших подій, які не можна блокувати, stderr показується лише вам або ігнорується. ДляStop,SubagentStop,TaskCompletedі hookUserPromptSubmitплагіна exit 2 з порожнім stdout та помилкою про відсутній файл у stderr трактується як помилка, що не блокує дію. - Будь-який інший код виходу з текстовим або порожнім stdout зазвичай означає помилку, що не блокує дію. У transcript відображається повідомлення про помилку hook, яке містить перший рядок stderr після тексту
Failed with non-blocking status code:. Допустимий JSON усе ще може визначити результат для таких подій, якPreToolUse, якщо помилка hook не блокує дію.WorktreeCreateзавершується помилкою за будь-якого ненульового коду виходу, аWorktreeRemoveзавершується помилкою за ненульового коду виходу, якщо каталог після цього все ще існує.
Для будь-якої поведінки, крім блокування або відсутності дії, використовуйте exit 0 і виводьте об’єкт JSON у stdout. Hook PreToolUse визначає результат за допомогою permissionDecision:
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Database drops go through a migration, not through the agent."
}
}"allow" пропускає інтерактивний запит, якщо це дозволяють правила дозволів і вимоги інструмента до схвалення, "deny" скасовує виклик і передає причину моделі, а "ask" запитує підтвердження. Для кожного hook вибирайте один стиль. Поєднання exit 2 із рішенням у JSON у stdout зберігає блокування, навіть якщо JSON містить "allow".
Коли кілька hook відповідають одній події, вони виконуються паралельно. Для prompt hook і agent hook кількість одночасних запусків обмежена дванадцятьма. deny від одного hook не зупиняє його паралельні hook, тому logging hook все одно записує свій рядок, поки guardrail hook відхиляє той самий виклик. Для PreToolUse Claude Code об’єднує відповіді та залишає найсуворішу, у такому порядку: deny, defer, ask, allow.
Приклад 1: заблокувати небезпечну команду до її виконання
Збережіть це у файлі .claude/hooks/block-destructive.sh у вашому проєкті:
#!/bin/bash
# Deny a Bash tool call whose command matches a banned pattern.
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
for pattern in 'rm -rf /' 'mkfs' 'dd if=' 'DROP TABLE'; do
if printf '%s' "$COMMAND" | grep -qiF -- "$pattern"; then
echo "Blocked by policy: the command matches '$pattern'. A human runs this one." >&2
exit 2
fi
done
exit 0Зробіть файл виконуваним, а потім зареєструйте його для PreToolUse у .claude/settings.json:
chmod +x .claude/hooks/block-destructive.sh{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-destructive.sh",
"timeout": 10,
"statusMessage": "Checking the command against policy"
}
]
}
]
}
}Перевірте скрипт вручну, перш ніж довіряти йому, оскільки hook, який аварійно завершується на власному вхідному значенні, зазвичай пропускає виконання, якщо onFailure не задано. У Windows без Git Bash помилкове виконання hook-команди у формі shell для PreToolUse або PermissionRequest натомість може заблокувати виклик інструмента:
echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /var/lib/postgresql"}}' \
| .claude/hooks/block-destructive.sh
echo $?У stderr має з’явитися рядок Blocked by policy:, а код завершення має дорівнювати 2. Передайте безпечну команду, наприклад ls -la. Ви не повинні побачити жодного виводу, а код завершення має дорівнювати 0. У межах сеансу відхилений виклик з’являється в журналі діалогу разом із вашим повідомленням як причиною. Модель читає це повідомлення й адаптує свої дії.
Цю схему виправдовує одна властивість: hook-и PreToolUse спрацьовують до перевірки режиму дозволів у будь-якому режимі дозволів. Тому заборона діє навіть у режимі bypassPermissions. Саме це робить hook корисним у поєднанні з автоматичним режимом Claude Code і його налаштуваннями дозволів, де кількість запитів на підтвердження зменшено, але hook усе одно спрацьовує.
Важливо правильно розуміти призначення цього механізму. Пошук за шаблоном у рядку команди є запобіжним обмеженням проти необережних дій агента. Це не межа захисту від кмітливого агента, оскільки ту саму команду можна записати у формі, яку ваш grep не побачить. Суворі правила мають задаватися в системі дозволів і для облікового запису, від імені якого працює процес.
Приклад 2: форматування та перевірка стилю після кожного редагування
PostToolUse із matcher Edit|Write запускається після успішного виконання будь-якого з цих інструментів редагування файлів. Збережіть це як .claude/hooks/after-edit.sh:
#!/bin/bash
# Format the edited file, then report lint failures back to the model.
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
[ -z "$FILE" ] && exit 0
case "$FILE" in
*.py)
ruff format "$FILE" >/dev/null 2>&1
if ! ruff check "$FILE" >&2; then
exit 2
fi
;;
*.sh)
if ! shellcheck "$FILE" >&2; then
exit 2
fi
;;
esac
exit 0{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/after-edit.sh",
"timeout": 60
}
]
}
]
}
}Попросіть Claude додати до Python-файлу функцію з неправильними відступами, а потім відкрийте файл. Він буде відформатований. Це підтверджує, що hook спрацював, оскільки успішний hook нічого не виводить у діалог.
Код завершення 2 тут нічого не скасовує. PostToolUse запускається після виконання інструмента, тому зміни в будь-якому разі вже записані на диск. Код завершення 2 потрібен для того, щоб вивід ruff check надійшов до моделі як зворотний зв’язок. Тоді вона виправляє щойно внесену помилку, а не переходить далі. У цьому полягає різниця між помилкою перевірки стилю, яку ви виявляєте під час commit, і помилкою, яку агент виправляє в тому самому ході.
Тут важливі два обмеження matcher. Edit|Write не бачить файлів, змінених shell-командою, а Claude досить часто записує файли через Bash, тому ця прогалина має практичне значення. Для покриття кожного виклику додайте також Bash і налаштуйте script так, щоб він перелічував змінені файли за допомогою git status --porcelain. Для покриття один раз за хід помістіть сканування в hook Stop.
Приклад 3: запис кожного виклику інструмента для аудиту
Порожній matcher у PostToolUse спрацьовує після кожного успішного виклику інструмента, крім EndConversation. Надсилання запису до системного журналу, а не у файл у домашньому каталозі, не робить його недоступним для власної shell-сесії агента: доступ залежить від дозволів облікового запису. Користувачі можуть читати свої приватні журнали для окремого користувача, а root і учасники systemd-journal, adm або wheel можуть читати всі файли журналу:
{
"hooks": {
"PostToolUse": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "jq -c '{time: now|todate, session: .session_id, cwd: .cwd, tool: .tool_name, input: .tool_input}' | logger -t claude-code -p local0.info"
}
]
}
]
}
}Прочитайте запис за допомогою journalctl -t claude-code -o cat | tail -n 5. Якщо у вас є дозвіл на читання записів, ви маєте побачити по одному рядку JSON для кожного успішного виклику інструмента, крім EndConversation, причому останнім має бути найновіший запис. Якщо нічого не відображається, перевірте доступ до журналу та факт виконання hook; нижче в розділі з усунення несправностей описано перевірку hook.
Додайте такий самий блок у PostToolUseFailure, щоб записувати невдалі виклики, оскільки PostToolUse спрацьовує лише після успішного виконання, а невдала команда зазвичай містить найважливішу інформацію. Причина використання logger замість додавання даних у файл у домашньому каталозі — право власності: hook виконується від імені того самого користувача, що й shell-сесія агента, тому все, до чого цей користувач має доступ для додавання, він також може очистити. Записи до журналу виконує systemd-journald; захист від видалення все одно залежить від привілеїв облікового запису агента.
Скільки часу може виконуватися hook
Дані, на яких побудовано графік
[
{
"label": "command, http or mcp_tool hook",
"default_timeout_seconds": 600
},
{
"label": "agent hook",
"default_timeout_seconds": 60
},
{
"label": "prompt hook",
"default_timeout_seconds": 30
},
{
"label": "command, http or mcp_tool on UserPromptSubmit, PreModelSwitch or PostModelSwitch",
"default_timeout_seconds": 30
},
{
"label": "command, http or mcp_tool on MessageDisplay",
"default_timeout_seconds": 10
},
{
"label": "any hook on SessionEnd",
"default_timeout_seconds": 1.5
}
]За замовчуванням command hook має 600 секунд, тобто десять хвилин. Для деяких подій цей час значно коротший. Усі SessionEnd hooks мають спільний ліміт 1.5 секунди, тому очищення наприкінці сесії має виконуватися швидко. Водночас довше значення timeout для hook у файлах налаштувань збільшує цей спільний ліміт до відповідного значення, але не більше ніж до 60 секунд.
Якщо синхронний command, HTTP або MCP tool hook перевищує ліміт часу, його скасовують, і зазвичай він не повертає рішення; для PreModelSwitch перевищення ліміту блокує перемикання. Для PreToolUse guardrail перевищення ліміту зазвичай дає змогу продовжити виклик tool у звичайному процесі перевірки дозволів, за винятком описаної вище ситуації у Windows, коли onFailure не задано. Тому guardrail scripts мають бути короткими. Починаючи з release 2.1.295, цю поведінку за замовчуванням можна змінити для command або http hook за допомогою "onFailure": "block". У такому разі перевищення ліміту, збій або неочікуваний код завершення блокують операцію. Це не впливає на Stop, SubagentStop, TaskCompleted, TeammateIdle або background command hooks. Для повільних операцій, результат яких не потрібен негайно, наприклад передавання журналу в інше місце, задайте "async": true. Тоді hook виконуватиметься у фоні й не блокуватиме виклик tool.
Хуки, файли правил, навички та MCP-сервери
Чотири поняття часто плутають між собою, оскільки всі вони змінюють поведінку агента. Лише один із цих механізмів перестає бути рекомендацією.
Файл правил (CLAUDE.md або файл у каталозі .claude/rules/) — це текст, який завантажується в контекст моделі. Він формує поведінку, але нічого не забезпечує примусово. Під час довгої розмови, роботи з великим diff і надходження нового запиту користувача один його рядок може бути проігнорований. Саме так зазвичай виникає ситуація, коли агенти ігнорують записані вами інструкції.
Навичка — це каталог з інструкціями та скриптами, який модель завантажує, коли вважає навичку релевантною. Саме це рішення є суттю навички та водночас її обмеженням: модель усе одно вирішує сама. Обидві властивості видно на прикладі навички Ponytail, яка спрямовує агента до найменшої працездатної зміни: вона визначає підхід до виконання всього завдання так, як не зміг би жоден хук, але працює лише тоді, коли модель вирішує її завантажити.
MCP (model context protocol) сервер надає моделі нові інструменти для виклику. Він розширює доступ агента до ресурсів. Але він не змушує агента використовувати ці ресурси. Крім того, це окремий процес, яким потрібно керувати, а це самостійне завдання: див. запуск MCP-серверів на VPS.
Хук — єдиний із чотирьох механізмів, який запускається без рішення моделі. Використовуйте файл правил для побажання, а навичку — для процедури, якої модель має дотримуватися за відповідних умов. Використовуйте хук для кроку, який має виконуватися щоразу, або для дії, яка ніколи не повинна виконуватися. Докладніше порівняння, зокрема випадки, коли навичка краща за файл правил, наведено в матеріалі порівняння навичок, MCP і файлів правил.
Плагін — це спосіб пакування, а не п’ятий механізм. Він об’єднує хуки та навички в один встановлюваний компонент. Так команда розгортає однаковий захисний механізм на кожній машині: див. як працюють плагіни Claude Code.
Рішення щодо безпеки на спільному VPS
Hook — це код, який запускає агент. Він виконується від імені користувача, який запустив Claude Code, і успадковує права доступу до файлів та змінні середовища цього користувача. На ноутбуці це питання робочого процесу. На VPS, де агент працює без нагляду, це питання безпеки, яке має чотири практичні складові.
Hook у репозиторії — це код, якого ви не писали. .claude/settings.json зберігається в репозиторії, тому клонування репозиторію та запуск сеансу всередині нього можуть зареєструвати hooks, що надійшли разом із репозиторієм. В інтерактивному сеансі Claude Code запускає hooks проєкту лише після діалогу підтвердження довіри до робочої області для цієї папки. Отже, прийняття довіри — це момент, коли ви вирішуєте їх запустити. Спочатку прочитайте блок hooks. Сеанс claude -p або SDK, яким зазвичай запускають агента без нагляду, ніколи не показує цей діалог і вважає папку довіреною, тому hooks репозиторію запускаються без запиту. Перегляньте його файли .claude/, перш ніж автоматизувати роботу з ним, або запускайте з --settings '{"disableAllHooks": true}'.
Hook бачить повний ввід інструмента. Audit hook, який записує tool_input, зберігає в журналі кожен аргумент кожної команди, зокрема будь-який токен, що випадково опинився в командному рядку. Такий журнал потребує такого самого захисту, як і сам секрет. Це частина ширшої проблеми — не допускати секрети до зони доступу AI-агента.
Hook може записувати дані в контекст моделі. Текстовий stdout успішного hook SessionStart або UserPromptSubmit додається до розмови. Hook, який передає текст із зовнішнього джерела, системи відстеження завдань або файла журналу, передає моделі недовірений текст так, ніби ви ввели його самостійно. Hook, який пересилає повідомлення з іншого сеансу Claude Code на тому самому VPS, робить те саме. Вивід іншого агента не заслуговує на більшу довіру, ніж дані із системи відстеження завдань. Розглядайте цей stdout як ввід, а не як вивід.
Права доступу — це основний засіб контролю. Запускайте агента від імені окремого непривілейованого користувача, надавши йому лише потрібні правила sudo. Заборона PreToolUse корисна, але за задумом вона працює за принципом best effort. У довіднику зазначено те саме про фільтр if і рекомендовано використовувати систему дозволів, коли потрібна безумовна заборона. Саме правила дозволів і обліковий запис, від імені якого працює процес, забезпечують контроль у критичних ситуаціях.
Одна властивість діє в кожному режимі дозволів. Hooks PreToolUse запускаються до перевірки режиму дозволів у кожному режимі дозволів, тому hook, який повертає deny, блокує інструмент навіть у режимі bypassPermissions. Hooks можуть посилювати обмеження, встановлені правилами дозволів. Послабити їх вони не можуть. Винятком є mod. На машині без керованих налаштувань і без файла managed-mcp.json, у сеансі, який не виконано з входом через /login до плану Team або Enterprise, встановлений mod, що обробляє tool.check, може дозволити виклик, заблокований вашим hook PreToolUse. Якщо використовуються керовані налаштування, файл managed-mcp.json або облікові дані сеансу /login плану Team чи Enterprise, виклик, заблокований hook PreToolUse, за замовчуванням залишається заблокованим незалежно від того, з якого файла налаштувань походить hook. Сеанс, який працює з API key або довготривалим CLAUDE_CODE_OAUTH_TOKEN, як це часто буває на серверах, вважається таким, що не виконано з входом, навіть якщо дані входу збережено. Перед встановленням mod на сервері перевірте, що можуть змінювати mods Claude Code.
Чому мій hook не запускається?
Виконуйте перевірки в наведеному порядку. Кожен крок описує симптом, який ви фактично побачите.
- Виконайте
/hooksі перевірте, чи з’явився hook у меню потрібної події. Якщо hook відсутній у меню, зазвичай це означає синтаксичну помилку JSON у файлі налаштувань, оскільки кінцеві коми та коментарі не дозволені, або файл не розташований в одному із шести наведених вище місць. - Точно зіставте matcher з назвою інструмента. Matchers чутливі до регістру, тому
"bash"ніколи не відповідає інструментуBash. - Запустіть скрипт вручну з тестовими вхідними даними, як у прикладі 1 вище. Неочікуваний код завершення означає помилку у скрипті; також перевірте його stdout, оскільки коректний JSON усе одно може передати рішення для таких подій, як
PreToolUse. - Повідомлення
jq: command not foundозначає, що на цій машині відсутнійjq. Повідомленняcommand not foundдля вашого скрипту означає, що шлях не вдалося визначити, тому використайте${CLAUDE_PROJECT_DIR}або абсолютний шлях. Якщо скрипт взагалі не запускається, імовірно, він не має права на виконання. - Hook виводить коректний JSON, але нічого не відбувається. У macOS і Linux hook у shell-формі запускається через
sh -cу неінтерактивній оболонці, але деякі конфігурації все одно завантажують ваш профіль, наприкладBASH_ENV, що вказує на~/.bashrc. Якщо цей профіль виводить банер, банер додається перед вашим JSON. stdout більше не починається з{, тому Claude Code читає весь вивід як звичайний текст і ігнорує рішення. Оскільки hook завершився з кодом 0, у транскрипті помилка не відображається. Для більшості подій цей текст потрапляє лише до журналу налагодження, але дляUserPromptSubmit,UserPromptExpansion,SessionStartіPostModelSwitchвін додається до контексту моделі разом із банером. Обгорніть будь-якийechoу профілі так, щоб він виконувався лише в інтерактивних оболонках. - Якщо проблема не зникає, запустіть сесію з
claude --debug-file /tmp/claude.log, а в іншому терміналі виконайтеtail -f /tmp/claude.log. Журнал налагодження містить інформацію про те, які hooks спрацювали, який код завершення повернув кожен із них, а також усе, що вони записали до stdout і stderr.
FAQ
У чому різниця між hook Claude Code та інструкцією CLAUDE.md?
Інструкція CLAUDE.md є текстом у контексті моделі. Тому вона конкурує за увагу з розмовою та поточним запитом, а модель може зіставляти її з ними. Hook — це shell-команда, яку Claude Code запускає у визначений момент свого життєвого циклу. Тому вона виконується під час кожного настання відповідної події, незалежно від рішення моделі. Використовуйте інструкцію для бажаної поведінки. Використовуйте hook для кроку, який має виконуватися завжди, або дії, яка ніколи не має виконуватися.
Як заборонити Claude Code виконувати певну shell-команду?
Зареєструйте hook PreToolUse із matcher Bash, який читає команду з .tool_input.command, записує причину в stderr і завершується з кодом 2. Claude Code скасовує виклик і показує моделі вашу причину. Це відбувається до перевірки permission mode, тому заборона діє навіть у режимі bypassPermissions. Зіставлення за рядком команди є захисним механізмом, а не межею безпеки, оскільки ту саму команду можна записати у формі, яку pattern не розпізнає. Тому доповніть його правилами доступу та використанням непривілейованого облікового запису.
Hook виводить коректний JSON, але нічого не відбувається. Чому?
Перевірте shell profile на наявність тексту, який виводиться перед JSON. У macOS і Linux hook без поля args запускається через sh -c. У конфігураціях, де profile все ще підключається, наприклад коли BASH_ENV вказує на ~/.bashrc, profile, який виводить banner, записує його в stdout перед вашим JSON. Оскільки вивід більше не починається з {, Claude Code обробляє весь вивід як звичайний текст і ігнорує рішення. Оскільки hook завершився з кодом 0, у transcript не відображається помилка. Обгорніть будь-який echo у profile перевіркою інтерактивної shell. Потім підтвердьте виправлення, прочитавши debug log із claude --debug-file /tmp/claude.log.
Чи безпечно запускати hooks Claude Code на спільному сервері?
Hooks запускаються від імені користувача, який запустив Claude Code, і мають права доступу до файлів цього користувача. Тому hook може виконати будь-яку дію, доступну цьому обліковому запису. Два правила усувають більшість ризиків: запускайте агента від імені окремого непривілейованого облікового запису з обмеженою політикою sudo та читайте блок hooks у кожному repository, перш ніж приймати діалог довіри до його workspace або запускати в ньому claude -p. Project hooks зберігаються в .claude/settings.json, а режим -p ніколи не показує цей діалог. Установіть "disableAllHooks": true у settings file, щоб вимкнути hooks, за винятком managed hooks, для яких цей параметр має бути встановлений на managed level. Project setting false може перевизначити user setting true.