Автоматизация действий с помощью 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"]
          }
        ]
      }
    ]
  }
}

​

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

​

Ограничения

• 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 не могут отменить действия, так как инструмент уже выполнен.
• Hooks PermissionRequest срабатывают, когда Claude Code собирается попросить у вас разрешение.
  • В неинтерактивном режиме с флагом -p этот запрос существует только когда обратный вызов canUseTool Agent SDK его предоставляет. В обычных запусках -p или с --permission-prompt-tool используйте hooks PreToolUse для автоматизированных решений разрешений вместо этого.
  • Фоновые подагенты не могут показать запрос в неинтерактивном режиме. Claude Code всё ещё запускает hooks для их вызовов инструментов, и если ни один hook не возвращает решение, он отклоняет вызов. В интерактивном сеансе запросы фоновых подагентов появляются в вашем основном сеансе и hooks срабатывают как обычно.
• 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

​

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 в вашем профиле оболочки, поэтому вывод больше не начинается с { и Claude Code не анализирует его как JSON. Причина и исправление следуют после этого списка.
• Поле на неправильном уровне: сравните размещение каждого поля с форматом JSON output. Например, permissionDecision должен находиться внутри hookSpecificOutput, а не на верхнем уровне.

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

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

​

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

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

​

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

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