SSD Nodes Learn Hosting plans →
Руководства Matt ConnorАвтор: Matt Connor

Как работают хуки в Claude Code: настройка и примеры

Узнайте, как хуки Claude Code принудительно выполняют shell-команды независимо от модели. Разбираем события, передачу данных через stdin и отмену вызовов через exit code 2.

Что такое хук Claude Code

Хуки Claude Code — это shell-команды, которые Claude Code выполняет самостоятельно в заданные моменты своего жизненного цикла. В этом заключается главное отличие хука от файла правил. Инструкция в CLAUDE.md — это рекомендация, которую модель сопоставляет со всем остальным контекстом. Хук — это код, и он выполняется независимо от того, согласна с ним модель или нет. Если ваш агент постоянно игнорирует форматтер, о котором вы дважды упоминали, вам не нужна более строгая инструкция. Вам нужен хук.

Механизм прост. Вы регистрируете команду в файле настроек под именем события. Когда это событие происходит, Claude Code запускает вашу команду и записывает данные события в свой стандартный поток ввода (stdin) в формате JSON (JavaScript object notation). Ваша команда считывает эти данные, выполняет работу и возвращает статус завершения. Код завершения 2 из хука PreToolUse отменяет вызов инструмента до его выполнения, а всё, что ваш скрипт записал в стандартный поток ошибок (stderr), передается модели в качестве причины, если только хук также не выводит JSON с решением о блокировке, причина которого имеет приоритет.

Имена событий и полей здесь взяты из справочника по хукам Claude Code, актуального на 12 ноября 2026 года. Эта область быстро меняется, поэтому перед копированием JSON из любого блога, включая этот, сверьтесь со справочником для вашей версии. Выведите свои настройки с помощью claude --version.

Где хранится конфигурация хуков

Хук представляет собой JSON-блок в файле настроек. Его можно разместить в одном из шести мест, при этом область действия файла определяет область действия хука.

  • ~/.claude/settings.json: каждый проект на вашей машине, но не на других.
  • .claude/settings.json: один проект, зафиксированный в репозитории, поэтому хук будет у каждого, кто клонирует этот репозиторий.
  • .claude/settings.local.json: один проект, только на вашей машине.
  • Управляемые настройки политики: на уровне всей организации, задаются администратором.
  • hooks/hooks.json внутри плагина, активны, пока включен этот плагин.
  • Frontmatter навыка или субагента. Хуки навыка остаются активными до конца сессии после его вызова, а хуки субагента работают, пока запущен сам субагент.

Записи хуков из этих файлов объединяются, а не перезаписывают друг друга. Файл настроек проекта добавляет свои хуки к тем, что указаны в пользовательских настройках, а не заменяет их, поэтому одно событие может содержать несколько хуков из разных файлов. Параметр "disableAllHooks": true отключает их, за одним исключением: хуки из управляемых настроек политики продолжают работать, если только этот параметр не применен также и в управляемых настройках.

Выполните /hooks во время сессии, чтобы вывести список всех зарегистрированных на данный момент хуков, сгруппированных по событиям, с указанием исходного файла и матчера для каждого из них. Меню доступно только для чтения, поэтому для изменения хука необходимо отредактировать файл настроек. Файловый наблюдатель обычно подхватывает изменения без перезапуска.

Какие события хуков поддерживает Claude Code

В справочнике по хукам указано тридцать три события: от SessionStart до SessionEnd. Они охватывают сжатие контекста, субагентов, worktree и файлы конфигурации. Для серверной работы обычно нужны лишь некоторые из них.

  • PreToolUse: перед выполнением вызова инструмента, кроме EndConversation. Это событие позволяет заблокировать вызов.
  • PostToolUse: после успешного вызова инструмента, кроме EndConversation. Если вызов завершается ошибкой, срабатывает PostToolUseFailure. Поэтому хуку, который должен видеть любой результат, нужны оба события.
  • PermissionRequest: когда для вызова инструмента требуется решение о разрешении. В этот момент появляется запрос на подтверждение.
  • UserPromptSubmit: после отправки запроса, но до его обработки Claude. Текст, выведенный успешным хуком в stdout, добавляется в контекст модели.
  • SessionStart и SessionEnd: при каждом завершении сеанса. SessionStart также срабатывает после сжатия контекста при значении matcher compact.
  • Stop: когда Claude завершает ответ. Событие срабатывает один раз за ход, а не один раз за завершённую задачу.

Для событий, поддерживающих matchers, группа может содержать matcher. Он определяет, при каких случаях запускается хук. Для событий инструментов matcher фильтрует вызовы по имени инструмента. Поэтому "Edit|Write" срабатывает при изменении файлов и больше ни при каких вызовах. Matchers учитывают регистр. Пустой matcher срабатывает при каждом случае. Инструменты сервера MCP (model context protocol) имеют имена вида mcp__<server>__<tool>. Поэтому matcher "mcp__github__.*" выбирает инструменты одного сервера и не затрагивает остальные.

У хуков Stop есть важная особенность, которую нужно учитывать до их создания. Блокирующий хук Stop отправляет модель обратно к выполнению задачи. По умолчанию Claude Code игнорирует следующую блокировку после восьми последовательных продолжений. Счётчик сбрасывается каждый раз, когда Claude вызывает инструмент. Прочитайте поле stop_hook_active во входных данных хука и завершите его работу с кодом 0, если значение этого поля равно true. Иначе хук может постоянно отправлять Claude обратно к выполнению задачи.

Что хук получает через stdin

Когда Claude собирается выполнить npm test, хук 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.

Как код завершения влияет на выполнение вызова инструмента

Существует три возможных исхода.

  • Код завершения 0 означает успех. Все корректные поля решения в формате JSON продолжают действовать, включая блокировку или отказ. В PreToolUse код 0 без указания решения не является одобрением, и стандартный процесс проверки прав продолжает выполняться. В UserPromptSubmit, UserPromptExpansion, SessionStart и PostModelSwitch обычный текст из stdout добавляется в контекст модели. В большинстве других событий stdout направляется только в журнал отладки.
  • Код завершения 2 блокирует действие для событий, которые допускают блокировку (включая PreToolUse). Содержимое stderr становится сообщением, сопровождающим блокировку, если только вывод JSON не содержит решение о блокировке, причина которого имеет приоритет. Кто именно увидит это сообщение, зависит от типа события. В PreToolUse и Stop модель воспринимает его как причину. В UserPromptSubmit и PreModelSwitch сообщение отображается вам и не добавляется в контекст модели. В PostToolUse и PostToolUseFailure, которые нельзя заблокировать, блокировка игнорируется, хотя stderr всё равно передается модели в качестве обратной связи. В большинстве других событий, которые нельзя заблокировать, stderr отображается только вам или игнорируется. В Stop, SubagentStop, TaskCompleted и хуке UserPromptSubmit плагина код 2 с пустым stdout и ошибкой отсутствия файла в stderr считается неблокирующей ошибкой.
  • Любой другой код завершения с обычным текстом или пустым stdout обычно является неблокирующей ошибкой. В журнале отображается уведомление об ошибке хука, содержащее первую строку stderr после текста Failed with non-blocking status code:. Корректный JSON всё ещё может определять исход для таких событий, как PreToolUse, если только сбой хука не блокирует действие. WorktreeCreate завершается с ошибкой при любом ненулевом коде, а WorktreeRemove завершается с ошибкой при ненулевом коде, если директория всё ещё существует после выполнения.

Для любых действий, выходящих за рамки блокировки или отсутствия вывода, используйте код 0 и выводите объект JSON в stdout. Хук PreToolUse принимает решение с помощью permissionDecision:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database drops go through a migration, not through the agent."
  }
}

"allow" пропускает интерактивный запрос, если правила разрешений и требования инструмента к одобрению это позволяют, "deny" отменяет вызов и отправляет причину модели, а "ask" запрашивает подтверждение. Выбирайте один стиль для каждого хука. Сочетание кода 2 с решением в формате JSON в stdout сохраняет блокировку, даже если в JSON указано "allow".

Если с одним событием сопоставлено несколько хуков, они выполняются параллельно. Для хуков запроса и агента действует ограничение: не более двенадцати одновременно запущенных процессов. deny от одного хука не останавливает выполнение остальных, поэтому хук логирования запишет свою строку, даже если хук-фильтр (guardrail) отклонит тот же вызов. Для 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"
          }
        ]
      }
    ]
  }
}

Протестируйте скрипт вручную, прежде чем доверять ему, так как хук, который аварийно завершается при обработке собственных входных данных, обычно открывает доступ, если onFailure не задана. В Windows без Git Bash неудачный вызов хука в формате shell-формы PreToolUse или PermissionRequest может вместо этого заблокировать вызов инструмента:

echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /var/lib/postgresql"}}' \
  | .claude/hooks/block-destructive.sh
echo $?

Вы должны увидеть строку Blocked by policy: в stderr и код завершения 2. Передайте ему безобидную команду, например ls -la, и вы не должны увидеть никакого вывода, а код завершения должен быть 0. В сессии отклоненный вызов отображается в транскрипте с вашим сообщением в качестве причины, модель считывает это сообщение и адаптируется.

Одно свойство делает это полезным: хуки PreToolUse срабатывают до проверки прав доступа в любом режиме разрешений, поэтому запрет действует даже в режиме bypassPermissions. Именно это делает хук полезным в сочетании с автоматическим режимом Claude Code и его настройками разрешений, где промпты ограничены, но хук всё равно срабатывает.

Будьте честны в отношении того, что это такое. Сопоставление с образцом в строке команды — это защитный барьер против неосторожности агента, а не граница против хитрости агента, поскольку одну и ту же команду можно написать в форме, которую ваш grep никогда не увидит. Жесткие правила должны быть реализованы в системе разрешений и в учетной записи, от имени которой выполняется процесс.

Пример 2: форматирование и линтинг после каждого редактирования

PostToolUse с матчером 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, а затем откройте этот файл. Он вернется уже отформатированным. Это подтверждает, что хук сработал, так как успешное выполнение хука не отображается в диалоге.

Код выхода 2 здесь ничего не отменяет. PostToolUse срабатывает уже после выполнения инструмента, поэтому изменения в любом случае записаны на диск. Код выхода 2 нужен для того, чтобы вывод ruff check попал к модели в качестве обратной связи, и она исправила только что допущенную ошибку, вместо того чтобы продолжать работу. В этом заключается разница между ошибкой линтинга, которую вы обнаруживаете при коммите, и ошибкой, которую агент исправляет в рамках одного и того же шага.

Здесь важны два ограничения матчера. Edit|Write не видит файлы, измененные с помощью shell-команды, а Claude достаточно часто записывает файлы через Bash, чтобы этот пробел стал существенным. Для покрытия каждого вызова добавьте в матчер Bash и настройте скрипт так, чтобы он выводил список измененных файлов с помощью git status --porcelain. Для покрытия один раз за шаг добавьте сканирование в хук Stop.

Пример 3: записывать каждый вызов инструмента для аудита

Пустой сопоставитель в PostToolUse срабатывает при каждом успешном вызове инструмента, кроме EndConversation. Отправка записи в системный журнал, а не в файл в домашнем каталоге, не делает её недоступной для собственной оболочки агента: доступ зависит от разрешений учётной записи. Пользователи могут читать свои закрытые пользовательские журналы, а 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 выполняется от имени того же пользователя, что и оболочка агента, поэтому всё, к чему этот пользователь может добавлять данные, он также может очистить. Запись в журнал выполняет systemd-journald; защита от удаления по-прежнему зависит от привилегий учётной записи агента.

Как долго может выполняться hook

ГрафикDefault hook timeout in seconds, by hook type and event
Данные, на которых построен график
[
  {
    "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 секунд, то есть 10 минут. Для некоторых событий этот срок значительно меньше. Все hooks SessionEnd совместно используют лимит 1.5 секунды, поэтому очистка при завершении сессии должна выполняться быстро. Однако параметр timeout для hook в файлах настроек увеличивает общий лимит до указанного значения, но не более 60 секунд.

Если синхронный hook типа command, HTTP или MCP tool достигает лимита времени, его выполнение отменяется, и обычно решение не выносится. Для PreModelSwitch превышение лимита блокирует переключение. Для защитного механизма PreToolUse превышение лимита обычно позволяет tool call продолжить выполнение в рамках стандартной процедуры проверки разрешений. Исключение для Windows действует, если параметр onFailure не задан. Поэтому защитные скрипты должны быть небольшими. Начиная с release 2.1.295, это поведение по умолчанию можно изменить для hook command или http с помощью "onFailure": "block". В этом случае превышение лимита, сбой или неожиданный код завершения блокируют операцию. Параметр не влияет на Stop, SubagentStop, TaskCompleted, TeammateIdle и фоновые command hooks. Для медленных операций, результат которых не требуется сразу, например для отправки log в другое место, задайте "async": true. Тогда hook будет выполняться в фоне и не будет задерживать tool call.

Хуки, файлы правил, навыки и MCP-серверы

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

Файл правил (CLAUDE.md или файл в директории .claude/rules/) — это текст, загружаемый в контекст модели. Он формирует поведение, но ничего не принуждает. В условиях длинного диалога, большого diff и нового запроса пользователя одна строка из этого файла может быть проигнорирована. Это обычная причина, по которой агенты игнорируют написанные вами инструкции.

Навык (skill) — это папка с инструкциями и скриптами, которую модель загружает, когда считает навык подходящим. Это суждение — суть навыка, но в нем же кроется и ограничение: модель по-прежнему принимает решение сама. Обе стороны этого процесса видны в таком навыке, как Ponytail, который подталкивает агента к внесению минимально необходимых изменений. Он формирует подход к задаче так, как не смог бы ни один хук, но работает только до тех пор, пока модель решает его использовать.

MCP-сервер (Model Context Protocol) предоставляет модели новые инструменты для вызова. Он расширяет возможности доступа агента. Он не заставляет агента использовать что-либо, к тому же это отдельный процесс, который нужно поддерживать, что само по себе является задачей: см. запуск MCP-серверов на VPS.

Хук — единственный из четырех механизмов, который срабатывает без участия модели. Используйте файл правил для предпочтений, а навык — для процедур, которым модель должна следовать при их применении. Используйте хук для шага, который должен выполняться всегда, или для действия, которое никогда не должно происходить. Более глубокое сравнение, включая случаи, когда навык эффективнее файла правил, приведено в сравнении навыков, MCP и файлов правил.

Плагин — это скорее способ упаковки, а не пятый механизм. Он объединяет хуки и навыки в единый устанавливаемый модуль. Именно так команда распространяет одни и те же правила безопасности на все машины: см. как работают плагины Claude Code.

Вопросы безопасности на общем VPS

Хук — это код, который инициирует агент, и он выполняется от имени пользователя, запустившего Claude Code. Он наследует права доступа к файлам и окружение этого пользователя. На ноутбуке это вопрос рабочего процесса. На VPS, где агент работает без присмотра, это вопрос безопасности, состоящий из четырех практических аспектов.

Хук в репозитории — это код, который писали не вы. .claude/settings.json фиксируется в коммитах, поэтому клонирование репозитория и запуск сессии внутри него могут зарегистрировать хуки, которые поставлялись вместе с репозиторием. В интерактивной сессии Claude Code ограничивает хуки проекта диалоговым окном доверия к рабочей области для этой папки, что означает, что подтверждение доверия — это момент, когда вы решаете их запустить. Сначала прочитайте блок hooks. Сессия claude -p или SDK, в которой обычно работает агент без присмотра, никогда не показывает это диалоговое окно и считает папку доверенной, поэтому хуки репозитория выполняются без запроса. Просмотрите файлы .claude/ перед тем, как писать скрипты для них, или запускайте с --settings '{"disableAllHooks": true}'.

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

Хук может записывать данные в контекст модели. Обычный текст из stdout успешного хука SessionStart или UserPromptSubmit добавляется в диалог. Хук, который передает текст извне, например, из системы отслеживания задач или лог-файла, передает модели недоверенный текст так, как будто вы ввели его сами. Хук, который пересылает заметку из другой сессии Claude Code на том же VPS, делает то же самое, и вывод одного агента заслуживает доверия не больше, чем данные из системы отслеживания задач. Относитесь к такому stdout как к входным, а не выходным данным.

Привилегии — это реальный контроль. Запускайте агента от имени выделенного непривилегированного пользователя только с теми правилами sudo, которые ему необходимы. Стоит использовать запрет PreToolUse, но по своей архитектуре это лишь попытка ограничения: справочник говорит то же самое о фильтре if и рекомендует использовать системные права доступа, когда вам нужен жесткий запрет. Правила разрешений и учетная запись, от имени которой работает процесс, — это то, что обеспечивает безопасность под нагрузкой.

Одно свойство сохраняется во всех режимах разрешений. Хуки PreToolUse срабатывают до проверки режима разрешений в любом режиме, поэтому хук, возвращающий deny, блокирует инструмент даже в bypassPermissions. Хуки могут ужесточать то, что позволяют правила разрешений. Они не могут их ослабить. Исключением является мод. На машине без управляемых настроек и без файла managed-mcp.json, в сессии, которая не авторизована через /login в плане Team или Enterprise, установленный мод, обрабатывающий tool.check, может одобрить вызов, который заблокировал ваш хук PreToolUse. При наличии управляемых настроек, файла managed-mcp.json или учетных данных сессии Team или Enterprise /login, вызов, заблокированный хуком PreToolUse, остается заблокированным по умолчанию, независимо от того, из какого файла настроек пришел хук. Сессия, работающая по API-ключу или долгоживущему CLAUDE_CODE_OAUTH_TOKEN (так работает большинство серверов), считается неавторизованной, даже если логин сохранен. Проверьте, что могут изменять моды Claude Code, прежде чем устанавливать их на сервер.

Почему мой хук не срабатывает?

Выполняйте проверку по порядку. Каждый шаг соответствует симптому, который вы наблюдаете.

  • Запустите /hooks и убедитесь, что хук отображается в ожидаемом событии. Если хук отсутствует в меню, это обычно означает синтаксическую ошибку JSON в файле настроек, так как завершающие запятые и комментарии недопустимы, либо файл находится не в одном из шести указанных выше расположений.
  • Сравните сопоставитель (matcher) с именем инструмента в точности. Сопоставители чувствительны к регистру, поэтому "bash" никогда не совпадет с инструментом Bash.
  • Запустите скрипт вручную с тестовыми входными данными, как в примере 1 выше. Неожиданный код завершения указывает на ошибку в вашем скрипте; также проверьте его stdout, так как корректный JSON может содержать решение для таких событий, как PreToolUse.
  • Уведомление jq: command not found означает, что jq отсутствует на этой машине. Ошибка command not found для вашего скрипта означает, что путь не был разрешен, поэтому используйте ${CLAUDE_PROJECT_DIR} или абсолютный путь. Если скрипт вообще не запускается, вероятно, у него нет прав на выполнение.
  • Хук выводит корректный JSON, но ничего не происходит. В macOS и Linux хук в формате shell выполняется через sh -c в неинтерактивной оболочке, но некоторые конфигурации все равно загружают ваш профиль, например, если BASH_ENV указывает на ~/.bashrc. Если этот профиль выводит баннер, баннер добавляется перед вашим JSON. Stdout перестает начинаться с {, поэтому Claude Code считывает всё как обычный текст и игнорирует решение. Поскольку хук завершился с кодом 0, в журнале транскрипции нет ошибок. Для большинства событий этот текст попадает только в журнал отладки, тогда как для UserPromptSubmit, UserPromptExpansion, SessionStart и PostModelSwitch он добавляется в контекст модели, включая баннер. Оберните любой echo в вашем профиле так, чтобы он выполнялся только в интерактивных оболочках.
  • Если проблема сохраняется: начните сессию с claude --debug-file /tmp/claude.log и запустите tail -f /tmp/claude.log во втором терминале. Журнал отладки записывает, какие хуки сработали, какой код завершения вернул каждый из них, а также всё, что они вывели в stdout и stderr.

FAQ

В чем разница между хуком Claude Code и инструкцией в CLAUDE.md?

Инструкция CLAUDE.md — это текст в контексте модели, поэтому она конкурирует за внимание с диалогом и текущим запросом, и модель может сопоставлять её с ними. Хук — это shell-команда, которую Claude Code запускает в фиксированный момент своего жизненного цикла, поэтому она выполняется при каждом наступлении события, независимо от решения модели. Используйте инструкцию для предпочтений. Используйте хук для шага, который должен выполняться всегда, или для действия, которое никогда не должно происходить.

Как запретить Claude Code выполнение конкретной shell-команды?

Зарегистрируйте хук PreToolUse с матчером Bash, который считывает команду из .tool_input.command, записывает причину в stderr и завершается с кодом 2. Claude Code отменяет вызов и показывает модели вашу причину; это происходит до проверки режима разрешений, поэтому запрет действует даже в режиме bypassPermissions. Сопоставление шаблонов в строке команды — это скорее защитный барьер, а не граница безопасности, так как одну и ту же команду можно написать в форме, которую шаблон пропустит. Поэтому подкрепляйте это правилами разрешений и использованием непривилегированной учетной записи.

Мой хук выводит корректный JSON, но ничего не происходит. Почему?

Проверьте свой shell-профиль на наличие текста, выводимого до JSON. В macOS и Linux хук без поля args запускается через sh -c. В конфигурациях, которые по-прежнему считывают ваш профиль (например, BASH_ENV, указывающий на ~/.bashrc), профиль, выводящий приветственное сообщение, помещает его в stdout перед вашим JSON. Поскольку вывод больше не начинается с {, Claude Code воспринимает всё как обычный текст и игнорирует решение, а так как хук завершился с кодом 0, в журнале нет ошибок. Ограничьте любой вывод echo в профиле проверкой на интерактивную оболочку, затем подтвердите исправление, прочитав отладочный журнал из claude --debug-file /tmp/claude.log.

Безопасно ли запускать хуки Claude Code на общем сервере?

Хуки запускаются от имени пользователя, который запустил Claude Code, с правами доступа этого пользователя, поэтому хук может делать всё, что доступно этой учетной записи. Две привычки покрывают большую часть рисков: запускайте агента от имени выделенной непривилегированной учетной записи с узкой политикой sudo и читайте блок hooks любого репозитория перед тем, как принять диалог доверия к рабочей области или запустить в ней claude -p, так как проектные хуки поставляются внутри .claude/settings.json, а режим -p никогда не показывает этот диалог. Установите "disableAllHooks": true в файле настроек, чтобы отключить хуки, за исключением управляемых хуков, которые требуют настройки на управляемом уровне; настройка проекта false может переопределить пользовательскую настройку true.

Была ли эта статья полезной?