Хуки

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

Хуки Cusp используют распространённый формат хуков: те же события, конфигурация, коды выхода и JSON-вывод. Хуки, которые у вас уже есть в .claude/settings.json, работают в Cusp.

КонфигурацияСкопировать ссылку на раздел

Хуки задаются в разделе hooks любого файла настроек. Каждому событию соответствует список групп с матчерами, а в каждой группе перечислены обработчики.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write|ApplyPatch",
        "hooks": [
          { "type": "command", "command": "bunx biome format --write \"$CUSP_PROJECT_DIR\"", "timeout": 30 }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.cusp/hooks/check-bash.sh" }
        ]
      }
    ]
  }
}

Хуки со всех уровней настроек объединяются: управляемые, локальные, проектные и пользовательские, плюс хуки, объявленные навыками и субагентами, пока те активны.

МатчерыСкопировать ссылку на раздел

matcher определяет, к каким вызовам инструментов (или подтипам событий) относится группа.

• Простое имя совпадает точно: Bash.
• Список через | совпадает с любым из элементов: Edit|Write.
• Всё, что содержит символы регулярных выражений, считается регулярным выражением: mcp__github__.*.
• Пустой или отсутствующий матчер совпадает со всем.

Матчеры видят канонические имена инструментов. Вызов apply_patch от модели GPT приходит как ApplyPatch, поэтому включайте его, когда отслеживаете правки.

Сужение с помощью ifСкопировать ссылку на раздел

У обработчика может быть условие if, записанное как одно правило разрешений. Обработчик запускается, только если вызов ему соответствует:

{ "type": "command", "command": "./scripts/guard-push.sh", "if": "Bash(git push *)" }

if проверяется только для событий инструментов.

Типы обработчиковСкопировать ссылку на раздел

Общие поля для всех обработчиков: timeout (в секундах), statusMessage (показывается во время работы), if и once (выполнить один раз и удалить; учитывается для хуков навыков).

onFailure: "block" превращает тайм-аут или сбой в блокировку. По умолчанию упавший хук не останавливает агента.

ВходСкопировать ссылку на раздел

Каждый хук получает JSON-объект. Общие поля:

События инструментов добавляют tool_name, tool_input и tool_use_id. PostToolUse добавляет tool_response.

Переменные окружения для хуков command:

ВыводСкопировать ссылку на раздел

Коды выходаСкопировать ссылку на раздел

JSON-выводСкопировать ссылку на раздел

Для более тонкого управления выведите JSON-объект в stdout с кодом выхода 0:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use the deploy skill instead of calling kubectl directly."
  }
}

Если на одно событие отвечают несколько хуков, побеждает самый строгий ответ: для PreToolUse deny сильнее defer, defer сильнее ask, а ask сильнее allow. Запрет от хука действует в любом режиме разрешений, включая bypass. Контекст от нескольких хуков объединяется в порядке конфигурации. Каждое текстовое поле ограничено 10 000 символов.

СобытияСкопировать ссылку на раздел

ПримерыСкопировать ссылку на раздел

Запретить правку сгенерированных файловСкопировать ссылку на раздел

#!/usr/bin/env bash
path=$(jq -r '.tool_input.file_path // empty')
if [[ "$path" == *"/generated/"* ]]; then
  echo "Files under generated/ are produced by 'bun run codegen'. Edit the schema instead." >&2
  exit 2
fi

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write|ApplyPatch|EditLines",
        "hooks": [{ "type": "command", "command": "${CUSP_PROJECT_DIR}/.cusp/hooks/no-generated.sh" }]
      }
    ]
  }
}

Продолжать, пока не пройдут тестыСкопировать ссылку на раздел

Хук Stop, который блокирует ход и передаёт вывод тестов, возвращает агента к работе:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "out=$(bun test 2>&1) || { echo \"$out\" | tail -40 >&2; exit 2; }", "timeout": 300 }
        ]
      }
    ]
  }
}

Когда тесты проходят, хук завершается с кодом 0, и ход заканчивается как обычно. Если сбой не зависит от агента, он будет пытаться снова, пока вы его не прервёте; в неинтерактивном режиме сочетайте это с --max-turns.

Добавить контекст при старте сессииСкопировать ссылку на раздел

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [{ "type": "command", "command": "echo \"Open issues assigned to me:\"; gh issue list --assignee @me --limit 5" }]
      }
    ]
  }
}

Попросить модель проверить работуСкопировать ссылку на раздел

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "The user asked for a change and the agent says it is done. Based on this transcript excerpt, did the agent run the tests and do they pass? $ARGUMENTS"
          }
        ]
      }
    ]
  }
}

БезопасностьСкопировать ссылку на раздел

• Хуки выполняются с правами вашего пользователя, вне песочницы. Прежде чем доверять репозиторию, проверьте его скрипты хуков.
• В недоверенной рабочей области проектные и локальные настройки не могут добавлять хуки.
• Администраторы могут разрешить хуки только из управляемых настроек с помощью allowManagedHooksOnly и ограничить HTTP-хуки одобренными URL с помощью allowedHttpHookUrls.
• disableAllHooks: true отключает хуки.