Автоматизация рабочих процессов с помощью hooks

Запускайте команды оболочки автоматически, когда Claude Code редактирует файлы, завершает задачи или требует ввода. Форматируйте код, отправляйте уведомления, проверяйте команды и применяйте правила проекта.

Hooks — это определяемые пользователем команды оболочки, которые выполняются в определённых точках жизненного цикла Claude Code. Они обеспечивают детерминированное управление поведением Claude Code, гарантируя, что определённые действия всегда происходят, а не полагаясь на то, что LLM выберет их запуск. Используйте hooks для применения правил проекта, автоматизации повторяющихся задач и интеграции Claude Code с вашими существующими инструментами.

Для решений, требующих суждения, а не детерминированных правил, вы также можете использовать hooks на основе подсказок или hooks на основе агентов, которые используют модель Claude для оценки условий.

Для других способов расширения Claude Code см. skills для предоставления Claude дополнительных инструкций и исполняемых команд, subagents для запуска задач в изолированных контекстах и plugins для упаковки расширений для совместного использования в проектах.

Настройка вашего первого hook

Чтобы создать hook, добавьте блок hooks в файл параметров. Это пошаговое руководство создаёт hook для уведомлений на рабочем столе, чтобы вы получали оповещение всякий раз, когда Claude ждёт вашего ввода вместо того, чтобы смотреть на терминал.

{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
}
]
}
]
}
}

{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
}
],
"Notification": [
{
"matcher": "",
"hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'" }]
}
]
}
}

Что вы можете автоматизировать

Hooks позволяют запускать код в ключевых точках жизненного цикла Claude Code: форматировать файлы после редактирования, блокировать команды перед их выполнением, отправлять уведомления, когда Claude требует ввода, внедрять контекст при запуске сеанса и многое другое. Для полного списка событий hook см. справочник Hooks.

Каждый пример включает готовый к использованию блок конфигурации, который вы добавляете в файл параметров. Наиболее распространённые шаблоны:

• Получайте уведомления, когда Claude требует ввода
• Автоматическое форматирование кода после редактирования
• Блокировка редактирования защищённых файлов
• Повторное внедрение контекста после компактирования
• Аудит изменений конфигурации
• Перезагрузка окружения при изменении каталога или файлов
• Автоматическое одобрение определённых запросов разрешений

Получайте уведомления, когда Claude требует ввода

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

Этот hook использует событие Notification, которое срабатывает, когда Claude ждёт ввода или разрешения. Каждая вкладка ниже использует собственную команду уведомления платформы. Добавьте это в ~/.claude/settings.json:

{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
}
]
}
]
}
}

osascript -e 'display notification "test"'

{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
}
]
}
]
}
}

{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
}
]
}
]
}
}

Пустой matcher срабатывает на все типы уведомлений. Чтобы срабатывать только на определённые события, установите его на одно из этих значений:

Введите /hooks и выберите Notification, чтобы подтвердить, что hook зарегистрирован. Для полной схемы события см. справочник Notification.

Автоматическое форматирование кода после редактирования

Автоматически запускайте Prettier на каждом файле, который редактирует Claude, чтобы форматирование оставалось согласованным без ручного вмешательства.

Этот hook использует событие PostToolUse с matcher Edit|Write, поэтому он запускается только после инструментов редактирования файлов. Команда извлекает путь отредактированного файла с помощью jq и передаёт его в Prettier. Добавьте это в .claude/settings.json в корне вашего проекта:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Блокировка редактирования защищённых файлов

Предотвратите изменение Claude чувствительных файлов, таких как .env, package-lock.json или что-либо в .git/. Claude получает обратную связь, объясняющую, почему редактирование было заблокировано, чтобы он мог скорректировать свой подход.

Этот пример использует отдельный файл скрипта, который вызывает hook. Скрипт проверяет путь целевого файла против списка защищённых шаблонов и выходит с кодом 2 для блокировки редактирования.

#!/bin/bash
# protect-files.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
if [[ "$FILE_PATH" == *"$pattern"* ]]; then
echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
exit 2
fi
done

exit 0

chmod +x .claude/hooks/protect-files.sh

{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
}
]
}
]
}
}

Повторное внедрение контекста после компактирования

Когда контекстное окно Claude заполняется, компактирование суммирует разговор для освобождения места. Это может привести к потере важных деталей. Используйте hook SessionStart с matcher compact для повторного внедрения критического контекста после каждого компактирования.

Любой текст, который ваша команда выводит в stdout, добавляется в контекст Claude. Этот пример напоминает Claude о соглашениях проекта и недавней работе. Добавьте это в .claude/settings.json в корне вашего проекта:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

Вы можете заменить echo любой командой, которая производит динамический вывод, например git log --oneline -5 для отображения недавних коммитов. Для внедрения контекста при каждом запуске сеанса рассмотрите использование CLAUDE.md вместо этого. Для переменных окружения см. CLAUDE_ENV_FILE в справочнике.

Аудит изменений конфигурации

Отслеживайте, когда файлы параметров или skills изменяются во время сеанса. Событие ConfigChange срабатывает, когда внешний процесс или редактор изменяет файл конфигурации, поэтому вы можете регистрировать изменения для соответствия или блокировать несанкционированные изменения.

Этот пример добавляет каждое изменение в журнал аудита. Добавьте это в ~/.claude/settings.json:

{
  "hooks": {
    "ConfigChange": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{timestamp: now | todate, source: .source, file: .file_path}' >> ~/claude-config-audit.log"
          }
        ]
      }
    ]
  }
}

Matcher фильтрует по типу конфигурации: user_settings, project_settings, local_settings, policy_settings или skills. Для блокировки вступления изменения в силу выйдите с кодом 2 или верните {"decision": "block"}. См. справочник ConfigChange для полной схемы ввода.

Перезагрузка окружения при изменении каталога или файлов

Некоторые проекты устанавливают разные переменные окружения в зависимости от того, в каком каталоге вы находитесь. Инструменты, такие как direnv, делают это автоматически в вашей оболочке, но инструмент Bash Claude не подхватывает эти изменения самостоятельно.

Сочетание hook SessionStart с hook CwdChanged исправляет это. SessionStart загружает переменные для каталога, в котором вы запускаетесь, а CwdChanged перезагружает их каждый раз, когда Claude меняет каталог. Оба записывают в CLAUDE_ENV_FILE, который Claude Code запускает как преамбулу скрипта перед каждой командой Bash. Добавьте это в ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ],
    "CwdChanged": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

Запустите direnv allow один раз в каждом каталоге, который имеет .envrc, чтобы direnv был разрешён загружать его. Если вы используете devbox или nix вместо direnv, тот же шаблон работает с devbox shellenv или devbox global shellenv вместо direnv export bash.

Чтобы реагировать на определённые файлы вместо каждого изменения каталога, используйте FileChanged с matcher, указывающим имена файлов для наблюдения, разделённые |. Для построения списка наблюдения это значение разбивается на буквальные имена файлов, а не оценивается как regex. См. FileChanged для того, как то же значение также фильтрует, какие группы hook запускаются при изменении файла. Этот пример наблюдает .envrc и .env в рабочем каталоге:

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": ".envrc|.env",
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

См. справочные записи CwdChanged и FileChanged для схем ввода, вывода watchPaths и деталей CLAUDE_ENV_FILE.

Автоматическое одобрение определённых запросов разрешений

Пропустите диалог одобрения для вызовов инструментов, которые вы всегда разрешаете. Этот пример автоматически одобряет ExitPlanMode, инструмент, который Claude вызывает, когда он завершает представление плана и просит продолжить, чтобы вас не спрашивали каждый раз, когда план готов.

В отличие от примеров с кодом выхода выше, автоматическое одобрение требует, чтобы ваш hook написал решение JSON в stdout. Hook PermissionRequest срабатывает, когда Claude Code собирается показать диалог разрешения, и возврат "behavior": "allow" отвечает на него от вашего имени.

Matcher ограничивает hook только ExitPlanMode, поэтому никакие другие запросы не затрагиваются. Добавьте это в ~/.claude/settings.json:

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PermissionRequest\", \"decision\": {\"behavior\": \"allow\"}}}'"
          }
        ]
      }
    ]
  }
}

Когда hook одобряет, Claude Code выходит из режима плана и восстанавливает любой режим разрешения, который был активен перед входом в режим плана. Стенограмма показывает "Allowed by PermissionRequest hook" там, где появился бы диалог. Путь hook всегда сохраняет текущий разговор: он не может очистить контекст и начать свежий сеанс реализации так, как может диалог.

Чтобы установить определённый режим разрешения вместо этого, вывод вашего hook может включать массив updatedPermissions с записью setMode. Значение mode — это любой режим разрешения, такой как default, acceptEdits или bypassPermissions, и destination: "session" применяет его только для текущего сеанса.

Чтобы переключить сеанс на acceptEdits, ваш hook пишет этот JSON в stdout:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedPermissions": [
        { "type": "setMode", "mode": "acceptEdits", "destination": "session" }
      ]
    }
  }
}

Держите matcher как можно более узким. Соответствие .* или оставление matcher пустым автоматически одобрит каждый запрос разрешения, включая записи файлов и команды оболочки. См. справочник PermissionRequest для полного набора полей решения.

Как работают hooks

События hook срабатывают в определённых точках жизненного цикла Claude Code. Когда событие срабатывает, все соответствующие hooks запускаются параллельно, и идентичные команды hook автоматически дедублируются. Таблица ниже показывает каждое событие и когда оно срабатывает:

Каждый hook имеет type, который определяет, как он запускается. Большинство hooks используют "type": "command", который запускает команду оболочки. Доступны четыре других типа:

• "type": "http": POST данные события на URL. См. HTTP hooks.
• "type": "mcp_tool": вызвать инструмент на уже подключённом MCP сервере. См. MCP tool hooks.
• "type": "prompt": однооборотная оценка LLM. См. Prompt-based hooks.
• "type": "agent": многооборотная проверка с доступом к инструментам. Agent hooks являются экспериментальными и могут измениться. См. Agent-based hooks.

Объединение результатов из нескольких hooks

Когда несколько hooks совпадают с одним и тем же событием, каждая команда hook выполняется до завершения, прежде чем Claude Code объединит результаты. Один hook, возвращающий deny, не останавливает выполнение родственных hooks. Не полагайтесь на deny одного hook для подавления побочных эффектов в другом hook.

После завершения всех соответствующих hooks Claude Code объединяет их выходные данные. Для решений о разрешениях PreToolUse побеждает наиболее ограничивающий ответ: deny переопределяет ask, который переопределяет allow. Текст из additionalContext сохраняется от каждого hook и передаётся Claude вместе.

Пример ниже регистрирует два hook PreToolUse на Bash. Первый добавляет каждую команду в файл журнала и выходит с 0. Второй запускает скрипт, который выходит с 2, чтобы отклонить, когда команда содержит rm -rf:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r .tool_input.command >> ~/.claude/bash.log"
          },
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm-rf.sh"
          }
        ]
      }
    ]
  }
}

Когда Claude пытается запустить rm -rf /tmp/build, оба hook выполняются параллельно. Hook логирования записывает команду в ~/.claude/bash.log и выходит с 0, что не сообщает никакого решения. Hook защиты выходит с 2, что отклоняет вызов инструмента. Отклонение побеждает, поэтому Claude Code блокирует команду и показывает Claude stderr защиты. Запись в журнал по-прежнему записывается, потому что hook логирования уже выполнился.

Чтение ввода и возврат вывода

Hooks взаимодействуют с Claude Code через stdin, stdout, stderr и коды выхода. Когда событие срабатывает, Claude Code передаёт данные, специфичные для события, в виде JSON в stdin вашего скрипта. Ваш скрипт читает эти данные, выполняет свою работу и сообщает Claude Code, что делать дальше, через код выхода.

Ввод hook

Каждое событие включает общие поля, такие как session_id и cwd, но каждый тип события добавляет разные данные. Например, когда Claude запускает команду Bash, hook PreToolUse получает что-то вроде этого на stdin:

{
  "session_id": "abc123",          // уникальный ID для этого сеанса
  "cwd": "/Users/sarah/myproject", // рабочий каталог при срабатывании события
  "hook_event_name": "PreToolUse", // какое событие запустило этот hook
  "tool_name": "Bash",             // инструмент, который Claude собирается использовать
  "tool_input": {                  // аргументы, которые Claude передал инструменту
    "command": "npm test"          // для Bash это команда оболочки
  }
}

Ваш скрипт может анализировать этот JSON и действовать на основе любого из этих полей. Hooks UserPromptSubmit получают текст prompt вместо этого, hooks SessionStart получают source (startup, resume, clear, compact) и так далее. См. Common input fields в справочнике для общих полей и раздел каждого события для схем, специфичных для события.

Вывод hook

Ваш скрипт сообщает Claude Code, что делать дальше, записывая в stdout или stderr и выходя с определённым кодом. Например, hook PreToolUse, который хочет заблокировать команду:

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q "drop table"; then
  echo "Blocked: dropping tables is not allowed" >&2  # stderr становится обратной связью Claude
  exit 2 # exit 2 = блокировать действие
fi

exit 0  # exit 0 = позволить продолжить

Код выхода определяет, что происходит дальше:

• Exit 0: действие продолжается. Для hooks UserPromptSubmit, UserPromptExpansion и SessionStart всё, что вы пишете в stdout, добавляется в контекст Claude.
• Exit 2: действие блокируется. Напишите причину в stderr, и Claude получит её как обратную связь, чтобы он мог скорректировать. Некоторые события не могут быть заблокированы: для SessionStart, Setup, Notification и других, exit 2 показывает stderr пользователю и выполнение продолжается. См. exit code 2 behavior per event для полного списка.
• Любой другой код выхода: действие продолжается. Стенограмма показывает уведомление об ошибке <hook name> hook error, за которым следует первая строка stderr; полный stderr переходит в debug log.

Структурированный вывод JSON

Коды выхода дают вам два варианта: разрешить или заблокировать. Для большего контроля выйдите с 0 и выведите объект JSON в stdout вместо этого.

Например, hook PreToolUse может отклонить вызов инструмента и сказать Claude почему, или передать его пользователю на одобрение:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep for better performance"
  }
}

С "deny" Claude Code отменяет вызов инструмента и передаёт permissionDecisionReason обратно Claude. Эти значения permissionDecision специфичны для PreToolUse:

• "allow": пропустить интерактивный запрос разрешения. Правила отказа и запроса, включая управляемые списки отказов предприятия, по-прежнему применяются
• "deny": отменить вызов инструмента и отправить причину Claude
• "ask": показать запрос разрешения пользователю как обычно

Четвёртое значение, "defer", доступно в non-interactive mode с флагом -p. Оно выходит из процесса с сохранённым вызовом инструмента, чтобы обёртка Agent SDK могла собрать ввод и возобновить. См. Defer a tool call for later в справочнике.

Возврат "allow" пропускает интерактивный запрос, но не переопределяет permission rules. Если правило отказа соответствует вызову инструмента, вызов блокируется даже когда ваш hook возвращает "allow". Если правило запроса соответствует, пользователь по-прежнему получает запрос. Это означает, что правила отказа из любой области параметров, включая managed settings, всегда имеют приоритет над одобрениями hook.

Другие события используют разные шаблоны решений. Например, hooks PostToolUse и Stop используют поле decision: "block" верхнего уровня, а PermissionRequest использует hookSpecificOutput.decision.behavior. См. summary table в справочнике для полного разбора по событиям.

Для hooks UserPromptSubmit используйте additionalContext вместо этого для внедрения текста в контекст Claude. Prompt-based hooks (type: "prompt") обрабатывают вывод иначе: см. Prompt-based hooks.

Фильтрация hooks с помощью matchers

Без matcher hook срабатывает при каждом возникновении его события. Matchers позволяют вам сузить это. Например, если вы хотите запустить форматер только после редактирования файлов (не после каждого вызова инструмента), добавьте matcher к вашему hook PostToolUse:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "prettier --write ..." }
        ]
      }
    ]
  }
}

Matcher "Edit|Write" срабатывает только, когда Claude использует инструмент Edit или Write, а не когда он использует Bash, Read или любой другой инструмент. См. Matcher patterns для того, как простые имена и регулярные выражения оцениваются.

Каждый тип события соответствует определённому полю:

Несколько дополнительных примеров, показывающих matchers на разных типах событий:

{
"hooks": {
"PostToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
}
]
}
]
}
}

{
"hooks": {
"PreToolUse": [
{
"matcher": "mcp__github__.*",
"hooks": [
{
"type": "command",
"command": "echo \"GitHub tool called: $(jq -r '.tool_name')\" >&2"
}
]
}
]
}
}

{
"hooks": {
"SessionEnd": [
{
"matcher": "clear",
"hooks": [
{
"type": "command",
"command": "rm -f /tmp/claude-scratch-*.txt"
}
]
}
]
}
}

Для полного синтаксиса matcher см. Hooks reference.

Фильтрация по имени инструмента и аргументам с помощью поля if

Поле if использует permission rule syntax для фильтрации hooks по имени инструмента и аргументам вместе, поэтому процесс hook порождается только когда вызов инструмента совпадает, или когда команда Bash слишком сложна для анализа. Это выходит за рамки matcher, который фильтрует на уровне группы только по имени инструмента.

Например, чтобы запустить hook только когда Claude использует команды git вместо всех команд Bash:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-git-policy.sh"
          }
        ]
      }
    ]
  }
}

Процесс hook порождается только когда подкоманда команды Bash совпадает с git *, или когда команда слишком сложна для анализа в подкоманды. Для составных команд, таких как npm test && git push, Claude Code оценивает каждую подкоманду и запускает hook, потому что git push совпадает. Поле if принимает те же шаблоны, что и правила разрешений: "Bash(git *)", "Edit(*.ts)" и так далее. Для соответствия нескольким именам инструментов используйте отдельные обработчики каждый со своим значением if, или соответствуйте на уровне matcher, где поддерживается чередование трубой.

if работает только на событиях инструментов: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest и PermissionDenied. Добавление его к любому другому событию предотвращает запуск hook.

Настройка местоположения hook

Где вы добавляете hook, определяет его область:

Запустите /hooks в Claude Code для просмотра всех настроенных hooks, сгруппированных по событиям. Чтобы отключить hooks, установите "disableAllHooks": true в вашем файле параметров. Hooks, настроенные в управляемых параметрах, по-прежнему запускаются, если disableAllHooks также не установлен там.

Если вы редактируете файлы параметров напрямую во время работы Claude Code, наблюдатель файлов обычно автоматически подхватывает изменения hook.

Hooks на основе подсказок

Для решений, требующих суждения, а не детерминированных правил, используйте hooks type: "prompt". Вместо запуска команды оболочки Claude Code отправляет вашу подсказку и данные ввода hook модели Claude (Haiku по умолчанию) для принятия решения. Вы можете указать другую модель с полем model, если вам нужна большая возможность.

Единственная работа модели — вернуть решение да/нет в виде JSON:

• "ok": true: действие продолжается
• "ok": false: что происходит, зависит от события:
  • Stop и SubagentStop: значение reason передаётся обратно Claude, чтобы он продолжал работать
  • PreToolUse: вызов инструмента отклоняется и значение reason возвращается Claude как ошибка инструмента, чтобы он мог скорректировать и продолжить
  • PostToolUse, PostToolBatch, UserPromptSubmit и UserPromptExpansion: ход завершается и значение reason появляется в чате как строка предупреждения

Этот пример использует hook Stop для запроса модели, завершены ли все запрошенные задачи. Если модель возвращает "ok": false, Claude продолжает работать и использует reason как свою следующую инструкцию:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
          }
        ]
      }
    ]
  }
}

Для полных параметров конфигурации см. Hooks на основе подсказок в справочнике.

Hooks на основе агентов

Когда проверка требует проверки файлов или запуска команд, используйте hooks type: "agent". В отличие от hooks подсказок, которые делают один вызов LLM, hooks агентов порождают subagent, который может читать файлы, искать код и использовать другие инструменты для проверки условий перед возвратом решения.

Hooks агентов используют тот же формат ответа "ok" / "reason", что и hooks подсказок, но с более длинным временем ожидания по умолчанию 60 секунд и до 50 оборотов использования инструмента.

Этот пример проверяет, что тесты проходят перед тем, как позволить Claude остановиться:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Используйте hooks подсказок, когда данных ввода hook достаточно для принятия решения. Используйте hooks агентов, когда вам нужно проверить что-то против фактического состояния кодовой базы.

Для полных параметров конфигурации см. Hooks на основе агентов в справочнике.

HTTP hooks

Используйте hooks type: "http" для POST данных события на HTTP конечную точку вместо запуска команды оболочки. Конечная точка получает тот же JSON, который hook команды получил бы на stdin, и возвращает результаты через тело ответа HTTP, используя тот же формат JSON.

HTTP hooks полезны, когда вы хотите, чтобы веб-сервер, облачная функция или внешний сервис обрабатывали логику hook: например, общий сервис аудита, который регистрирует события использования инструмента в команде.

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

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/tool-use",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

Конечная точка должна вернуть тело ответа JSON, используя тот же формат вывода, что и hooks команд. Для блокировки вызова инструмента верните ответ 2xx с соответствующими полями hookSpecificOutput. Коды состояния HTTP сами по себе не могут блокировать действия.

Значения заголовков поддерживают интерполяцию переменных окружения, используя синтаксис $VAR_NAME или ${VAR_NAME}. Разрешены только переменные, указанные в массиве allowedEnvVars; все остальные ссылки $VAR остаются пустыми.

Для полных параметров конфигурации и обработки ответов см. HTTP hooks в справочнике.

Ограничения и устранение неполадок

Ограничения

• Command hooks взаимодействуют только через stdout, stderr и коды выхода. Они не могут запускать команды / или вызовы инструментов. Текст, возвращённый через additionalContext, внедряется как системное напоминание, которое Claude читает как простой текст. HTTP hooks взаимодействуют через тело ответа вместо этого.
• Время ожидания hook варьируется в зависимости от типа. Переопределите для каждого hook с помощью поля timeout в секундах.
  • command, http, mcp_tool: 10 минут. UserPromptSubmit снижает эти значения до 30 секунд.
  • prompt: 30 секунд.
  • agent: 60 секунд.
• Hooks PostToolUse не могут отменить действия, так как инструмент уже выполнен.
• Hooks PermissionRequest не срабатывают в неинтерактивном режиме (-p). Используйте hooks PreToolUse для автоматизированных решений разрешений.
• Hooks Stop срабатывают всякий раз, когда Claude завершает ответ, а не только при завершении задачи. Они не срабатывают при прерывании пользователем. Ошибки API срабатывают StopFailure вместо этого.
• Когда несколько hooks PreToolUse возвращают updatedInput для переписания аргументов инструмента, последний завершённый побеждает. Поскольку hooks запускаются параллельно, порядок недетерминирован. Избегайте наличия более одного hook, изменяющего ввод одного и того же инструмента.

Hooks и режимы разрешений

Hooks PreToolUse срабатывают перед любой проверкой режима разрешений. Hook, возвращающий permissionDecision: "deny", блокирует инструмент даже в режиме bypassPermissions или с --dangerously-skip-permissions. Это позволяет вам применять политику, которую пользователи не могут обойти, изменив свой режим разрешений.

Обратное неверно: hook, возвращающий "allow", не обходит правила отказа из параметров. Hooks могут ужесточить ограничения, но не ослабить их сверх того, что разрешают правила разрешений.

Hook не срабатывает

Hook настроен, но никогда не выполняется.

• Запустите /hooks и подтвердите, что hook появляется под правильным событием
• Проверьте, что шаблон matcher точно соответствует имени инструмента (matchers чувствительны к регистру)
• Убедитесь, что вы запускаете правильный тип события (например, PreToolUse срабатывает перед выполнением инструмента, PostToolUse срабатывает после)
• Если используете hooks PermissionRequest в неинтерактивном режиме (-p), переключитесь на PreToolUse вместо этого

Ошибка hook в выводе

Вы видите сообщение вроде "PreToolUse hook error: ..." в стенограмме.

• Ваш скрипт неожиданно вышел с ненулевым кодом. Протестируйте его вручную, передав образец JSON:

  echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
  echo $?  # Проверьте код выхода
  

• Если вы видите "command not found", используйте абсолютные пути или ${CLAUDE_PROJECT_DIR} для ссылки на скрипты. Чтобы полностью избежать экранирования оболочки, добавьте "args": [] для переключения на exec form, который порождает скрипт напрямую без оболочки
• Если вы видите "jq: command not found", установите jq или используйте Python/Node.js для анализа JSON
• Если скрипт вообще не запускается, сделайте его исполняемым: chmod +x ./my-hook.sh

/hooks показывает, что hooks не настроены

Вы отредактировали файл параметров, но hooks не появляются в меню.

• Редактирования файлов обычно подхватываются автоматически. Если они не появились через несколько секунд, наблюдатель файлов мог пропустить изменение: перезагрузите сеанс для принудительной перезагрузки.
• Убедитесь, что ваш JSON действителен (конечные запятые и комментарии не допускаются)
• Подтвердите, что файл параметров находится в правильном месте: .claude/settings.json для hooks проекта, ~/.claude/settings.json для глобальных hooks

Stop hook работает вечно

Claude продолжает работать в бесконечном цикле вместо остановки.

Ваш скрипт Stop hook должен проверить, не срабатывал ли он уже. Проанализируйте поле stop_hook_active из JSON ввода и выйдите рано, если оно true:

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Позволить Claude остановиться
fi
# ... остальная логика вашего hook

Ошибка валидации JSON

Claude Code показывает ошибку анализа JSON, даже если ваш скрипт hook выводит действительный JSON.

Когда Claude Code запускает hook-команду в форме shell (без args), он порождает sh -c на macOS и Linux или Git Bash на Windows по умолчанию. Эта оболочка неинтерактивна, но Git Bash и некоторые конфигурации (такие как BASH_ENV, указывающий на ~/.bashrc) всё ещё источают ваш профиль. Если этот профиль содержит безусловные операторы echo, вывод добавляется к JSON вашего hook:

Shell ready on arm64
{"decision": "block", "reason": "Not allowed"}

Claude Code пытается проанализировать это как JSON и не удаётся. Чтобы исправить это, оберните операторы echo в вашем профиле оболочки, чтобы они запускались только в интерактивных оболочках:

# В ~/.zshrc или ~/.bashrc
if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

Переменная $- содержит флаги оболочки, и i означает интерактивный. Hooks запускаются в неинтерактивных оболочках, поэтому echo пропускается.

Методы отладки

Представление стенограммы, переключаемое с помощью Ctrl+O, показывает однострочную сводку для каждого hook, который срабатывал: успех молчит, блокирующие ошибки показывают stderr, и неблокирующие ошибки показывают уведомление об ошибке <hook name> hook error, за которым следует первая строка stderr.

Для полных деталей выполнения, включая какие hooks совпали, их коды выхода, stdout и stderr, прочитайте журнал отладки. Запустите Claude Code с claude --debug-file /tmp/claude.log для записи в известный путь, затем tail -f /tmp/claude.log в другом терминале. Если вы запустили без этого флага, запустите /debug во время сеанса для включения логирования и поиска пути журнала.

Узнайте больше

• Справочник Hooks: полные схемы событий, формат вывода JSON, асинхронные hooks и MCP tool hooks
• Соображения безопасности: просмотрите перед развёртыванием hooks в общих или производственных средах
• Пример валидатора команд Bash: полная справочная реализация