Автоматизация действий с помощью hooks

​

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

{
  "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\"'" }]
      }
    ]
  }
}

​

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

​

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

{
  "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'"
          }
        ]
      }
    ]
  }
}

notify-send 'Claude Code' 'test'

{
  "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')\""
          }
        ]
      }
    ]
  }
}

​

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

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

​

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

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

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

# Normalize Windows backslash separators so the patterns below match
FILE_PATH="${FILE_PATH//\\//}"

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"
          }
        ]
      }
    ]
  }
}

​

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

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

​

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

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

​

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

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

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

​

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

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

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

​

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

• "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": {
    "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"
          }
        ]
      }
    ]
  }
}

​

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

​

Ввод hook

• hook_event_name: событие, которое запустило hook
• tool_name: инструмент, который Claude собирается использовать
• tool_input: аргументы, которые Claude передал инструменту. Для Bash его поле command содержит команду оболочки.

{
  "session_id": "abc123",
  "cwd": "/Users/sarah/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

​

Вывод hook

#!/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: ваш hook не возражает через код выхода.
  • Для hook PreToolUse это не одобряет вызов инструмента: нормальный permission flow по-прежнему применяется.
  • Для hooks UserPromptSubmit, UserPromptExpansion, SessionStart и PostModelSwitch, Claude Code добавляет stdout, который он обрабатывает как простой текст, в контекст Claude.
• Exit 2: Claude Code блокирует действие. Напишите причину в stderr. Где она попадает, зависит от события: некоторые события передают её Claude как обратную связь, чтобы он мог скорректировать, другие показывают её пользователю, а несколько, таких как ConfigChange и Elicitation, не выводят никакого сообщения. Некоторые события не могут быть заблокированы: для SessionStart и других, exit 2 показывает stderr пользователю и выполнение продолжается. См. exit code 2 behavior per event для полного списка.
• Любой другой код выхода: для большинства событий результат зависит от того, что ваш hook вывел в stdout:
  • Разобранный объект, который проходит проверку схемы: Claude Code игнорирует код выхода, только JSON определяет результат, и hook не сообщается как ошибка. Исключения для каждого события, такие как WorktreeCreate, отказывающий при любом ненулевом выходе, перечислены в разделе Exit code output справочника.
  • Разобранный объект, который не проходит проверку схемы, или stdout, который Claude Code пытается разобрать как JSON, но это не является действительным JSON: неблокирующая ошибка; уведомление содержит сообщение проверки или разбора.
  • Stdout, который Claude Code обрабатывает как простой текст, или пустой stdout: действие продолжается как неблокирующая ошибка. Стенограмма показывает уведомление <hook name> hook error, затем первую строку stderr с префиксом Failed with non-blocking status code:. Чтобы захватить полный stderr, включите debug logging с claude --debug или запустив /debug во время сеанса.

​

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

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

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

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Current branch: release-42. Deploy freeze until Friday."
  }
}

​

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

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

{
  "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"
          }
        ]
      }
    ]
  }
}

​

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

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

​

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

​

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

• "ok": true: действие продолжается
• "ok": false: что происходит, зависит от события:
  • Stop и SubagentStop: значение reason передаётся обратно Claude, чтобы он продолжал работать, если только ответ также не устанавливает "impossible": true для обозначения условия, которое никогда не может быть выполнено, в этом случае Claude Code разрешает остановку и ход завершается
  • PreToolUse: вызов инструмента отклоняется; по умолчанию ход завершается и значение reason отказа появляется в чате как строка предупреждения. Установите continueOnBlock: true на hook, чтобы вместо этого вернуть значение reason Claude как ошибку инструмента, чтобы он мог скорректировать и продолжить. До версии 2.1.210 значение reason отказа возвращалось Claude как ошибка инструмента и ход продолжался
  • PostToolUse: по умолчанию ход завершается и значение reason появляется в чате как строка предупреждения. Установите continueOnBlock: true, чтобы передать значение reason обратно Claude и продолжить ход вместо этого
  • PostToolBatch, UserPromptSubmit и UserPromptExpansion: ход завершается и значение 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": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

​

HTTP hooks

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

• Код состояния 2xx: чтобы заблокировать вызов инструмента, верните в теле ответа соответствующие поля hookSpecificOutput.
• Любой другой код состояния или сбой запроса: Claude Code сообщает о неблокирующей ошибке и позволяет действию продолжиться. Чтобы сбой эндпоинта блокировал действие, задайте для хука onFailure: "block".

​

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

​

Ограничения

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

​

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

​

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

• Запустите /hooks и подтвердите, что hook появляется под правильным событием
• Проверьте, что шаблон matcher точно соответствует имени инструмента. Matchers чувствительны к регистру
• Убедитесь, что вы запускаете правильный тип события: PreToolUse срабатывает перед выполнением инструмента, PostToolUse срабатывает после. Hook PermissionRequest срабатывает, когда Claude Code собирается попросить у вас разрешение; см. ограничения для неинтерактивных случаев

​

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

• Ваш скрипт неожиданно вышел с ненулевым кодом. Протестируйте его вручную, передав образец 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
• Если уведомление показывает сообщение о валидации JSON, stdout вашего hook был проанализирован как JSON, но не прошёл валидацию схемы. Если оно показывает сообщение об анализе JSON, stdout выглядел как объект JSON, но не был действительным JSON. Оба случая происходят даже при выходе 0. Чтобы исправить ошибку анализа, создайте полезную нагрузку с помощью кодировщика JSON, такого как jq, вместо конкатенации строк, чтобы кавычки и обратные слэши внутри значений были экранированы. Раздел Exit code output справочника охватывает комбинации кодов выхода и JSON
• Если скрипт вообще не запускается, сделайте его исполняемым: chmod +x ./my-hook.sh

​

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

• Редактирования файлов обычно подхватываются автоматически. Если они не появились через несколько секунд, наблюдатель файлов мог пропустить изменение: перезагрузите сеанс для принудительной перезагрузки.
• Убедитесь, что ваш JSON действителен: конечные запятые и комментарии не допускаются
• Подтвердите, что файл параметров находится в правильном месте: .claude/settings.json для hooks проекта, ~/.claude/settings.json для глобальных hooks
• Если в меню отображается Only hooks from managed settings run here, ваша организация установила allowManagedHooksOnly. Хуки в ваших пользовательских, проектных и локальных файлах настроек не запускаются и не отображаются в списке

​

Stop hook достигает предела блокировки

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

​

Hook JSON не имеет эффекта

• Дополнительный вывод перед JSON: что-то ещё записывает в stdout раньше, обычно безусловный echo в вашем профиле оболочки, поэтому вывод больше не начинается с {. См. Вывод профиля оболочки перед JSON.
• Поле на неправильном уровне: сравните размещение каждого поля с форматом JSON output. Например, permissionDecision должен находиться внутри hookSpecificOutput, а не на верхнем уровне. См. Поля на неправильном уровне.

​

Вывод профиля оболочки перед JSON

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

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

​

Поля на неправильном уровне

​

Проверка того, что сделал хук

• Успех: вы ничего не видите, если только JSON хука не выводит что-либо, например systemMessage или обратную связь Stop-хука.
  • Чтобы убедиться, что хук запустился, проверьте его эффект, например переформатированный файл
• Блокирующая ошибка: для большинства событий вы видите сообщение, сопровождавшее блокировку, например Blocked: rm commands are not allowed. Для нескольких событий, таких как ConfigChange и Elicitation, сообщение не отображается. Откуда берётся сообщение, описано в разделе Exit code 2.
• Неблокирующая ошибка: вы видите уведомление <hook name> hook error с кратким объяснением, например первой строкой stderr после Failed with non-blocking status code:, или сообщением о валидации либо разборе JSON. Действие было выполнено.

​

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

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