Що таке hook у двох реченнях

Hook — це shell-команда у settings.json, яку CC запускає на одній із подій життєвого циклу. Команда виконується процесом-нащадком shell'а; її stdout/stderr/exit code впливають на CC (можна заблокувати tool-виклик, можна повернути дані моделі, можна нічого не повертати — тоді hook просто «зробив свою справу»).

Це принципово відрізняється від tool-ів: tool — це функція, яку викликає модель; hook — функція, яку викликає система навколо моделі.

6 типів подій

Тип	Коли запускається	Може заблокувати?
PreToolUse	Перед викликом tool-а	Так (exit 2)
PostToolUse	Після виклику tool-а	Ні (вже виконалось)
SessionStart	Старт сесії	Ні
Stop	Кінець відповіді моделі (end-of-turn)	Ні
Notification	Коли CC хоче повідомити користувача (наприклад, чекає підтвердження)	Ні
UserPromptSubmit	Перед обробкою кожного промта користувача	Так (заблокує промт)

Структура hook у settings.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "ruff format "${tool_input.file_path}""
      }
    ]
  }
}

Розбір:

• "PostToolUse" — тип події.
• "matcher" — regex по імені tool-а. "Edit" ловить тільки виклики Edit, "Bash" — тільки Bash, ".*" — всі. Можна "Edit|Write".
• "command" — сама shell-команда. Має доступ до плейсхолдерів ${tool_input.<поле>} — параметрів, з якими викликано tool.

Реальні рецепти

1. Auto-format Python після Edit

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "command": "case "${tool_input.file_path}" in *.py) ruff format "${tool_input.file_path}";; esac"
    }]
  }
}

Після кожного Edit/Write по .py-файлу — запускається ruff format. CC бачить уже відформатований код у наступному Read. Це знімає 80% перепалок «модель пише з 2-tab, а проект на 4-space».

2. Audit-лог Bash-команд

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "command": "echo "$(date -Iseconds) ${tool_input.command}" >> ~/.claude/bash-audit.log"
    }]
  }
}

Кожна Bash-команда, яку CC хоче виконати, записується в audit-log до виконання. Корисно для:

• Compliance (можна показати команді безпеки, що саме виконує агент).
• Debugging — згадати «що ж він тоді зробив».
• Постфактумного reviewing — підозрілий patern (наприклад, виконав 50 однакових команд) видно у логу.

3. Push-сповіщення у Telegram на завершення сесії

{
  "hooks": {
    "Stop": [{
      "command": "curl -s 'https://api.telegram.org/bot$TOKEN/sendMessage' -d 'chat_id=$CHAT_ID' -d 'text=CC session done'"
    }]
  }
}

На Stop (кінець відповіді моделі) — пуш у Telegram. Корисно для cron-запусків («Recurring jobs») — отримуєш сповіщення, що нічна задача завершилась успішно (або, якщо exit-code-aware, що впала).

4. Заборона rm -rf без явного підтвердження

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "command": "case "${tool_input.command}" in *'rm -rf'*) echo 'BLOCKED: rm -rf needs manual confirmation' >&2; exit 2;; esac"
    }]
  }
}

Якщо CC спробує виконати команду з rm -rf — hook повертає exit 2 і CC отримує stderr як reason для блокування. Модель бачить блок, шукає альтернативу.

Це не замінює permissions (спиця «Permissions і settings.json» циклу), а доповнює — permissions працює на рівні patterns, hook може мати багатшу логіку.

5. Перевірка комітів на secrets

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "command": "case "${tool_input.command}" in *'git commit'*) git diff --cached | grep -E 'API_KEY|SECRET|TOKEN' && { echo 'BLOCKED: possible secret in commit' >&2; exit 2; };; esac; exit 0"
    }]
  }
}

Перед git commit сканує staged-diff на регекс API_KEY|SECRET|TOKEN. Якщо знайдено — блокує. Не замінює gitleaks/trufflehog (ті точніше), але fail-fast захист.

6. SessionStart-банер «де ти зараз»

{
  "hooks": {
    "SessionStart": [{
      "command": "echo '== Branch:' $(git branch --show-current 2>/dev/null) '== Status:' $(git status --porcelain 2>/dev/null | wc -l) 'changes'"
    }]
  }
}

На старті сесії — короткий стан репо у консолі. Економить запит «де ми зараз». Особливо корисно, якщо часто перемикаєш гілки і повертаєшся через /resume.

Підводні камені

Як налагоджувати hook

1. Перевір синтаксис JSON: jq . ~/.claude/settings.json.
2. Подивись список активних hooks: slash /hooks.
3. Додай у hook tee -a ~/.claude/hooks-debug.log, щоб бачити, чи спрацював.
4. Запусти tool, який має тригерити hook. Подивись у лог. Якщо порожньо — matcher неправильний.
5. Якщо лог є, але hook не блокує (а має) — перевір exit code (повинно бути exit 2).

Cross-refs

• Де лежить hooks у JSON, поряд з permissions — «Permissions і settings.json».
• PreToolUse може блокувати виклики Agent — «Sub-агенти Claude Code».
• Stop-hook після cron-сесії — «Recurring jobs».