Przejdź do treści

Hooki w Claude Code: automatyczne polecenia, które pilnują zasad w zespole

Instrukcję w CLAUDE.md Claude może pominąć, a hook uruchomi się zawsze, gdy zajdzie dane zdarzenie. Dlatego hookami wymuszam w zespole to, co ma działać bez wyjątków: formatowanie, blokady wrażliwych plików i dziennik poleceń.

Autor: Szymon Łakomy. Aktualizacja:

Czym jest hook w Claude Code?

Hook to polecenie, które Claude Code uruchamia automatycznie przy wybranym zdarzeniu, więc działanie nie zależy od tego, czy model o nim pamięta. Hook dostaje opis zdarzenia w formacie JSON, na przykład nazwę narzędzia i ścieżkę pliku, a o dalszym przebiegu decyduje kod wyjścia:

  • Kod 0. Działanie idzie dalej.
  • Kod 2. Przy zdarzeniach, które na to pozwalają, działanie zostaje zablokowane, a komunikat z wyjścia błędów Claude dostaje jako powód.
  • Inny kod. To błąd hooka, który co do zasady nie zatrzymuje działania, więc kod 1 nie służy do blokady.

Poza poleceniami powłoki są też hooki HTTP, narzędzia MCP, ocena przez model i eksperymentalne hooki typu agent.

Jakie zdarzenia obsługują hooki?

Według dokumentacji hooki obsługują ponad 30 zdarzeń. W firmowych konfiguracjach najczęściej używam tych:

ZdarzenieKiedy działaPrzykład użycia w firmie
SessionStartstart lub wznowienie sesji, także po kompaktowaniu kontekstuprzypomnienie zasad sprintu w kontekście
UserPromptSubmitpo wysłaniu polecenia, przed jego przetworzeniemzatrzymanie polecenia z wklejonym kluczem API
PreToolUseprzed wywołaniem narzędzia, może je zablokowaćblokada plików .env albo wypychania na main
PostToolUsepo udanym wywołaniu narzędziaformatowanie pliku, wpis do dziennika
Notificationgdy Claude Code wysyła powiadomienieinformacja, że agent czeka na zgodę
Stopgdy Claude kończy odpowiedźsprawdzenie, czy testy przechodzą
ConfigChangegdy w trakcie sesji zmieni się plik konfiguracjizapis zmian ustawień do audytu

Według dokumentacji Claude Code, stan na 14 listopada 2026. PostToolUse nie cofnie działania, bo narzędzie już się wykonało.

Gdzie konfiguruje się hooki?

Hooki zapisuje się w kluczu hooks pliku ustawień, a miejsce zapisu decyduje o zasięgu (wpisy z różnych poziomów się sumują):

  • ~/.claude/settings.json: wszystkie projekty jednej osoby.
  • .claude/settings.json: plik w repozytorium, więc cały zespół ma te same blokady i formatowanie.
  • .claude/settings.local.json: osobiste testy, poza gitem.
  • Ustawienia zarządzane: polityka organizacji. Opcja allowManagedHooksOnly blokuje hooki użytkowników, projektów i pluginów, poza wymuszonymi.
  • Pluginy, skille i subagenci: hook może przyjść razem z nimi.

Polecenie /hooks pokazuje hooki i ich źródło. Matcher zawęża hook do narzędzi, na przykład Edit|Write, a pole if przyjmuje reguły uprawnień, na przykład Bash(git *). Powłokę hooków na Windows opisuję przy Claude Code na Windows.

Przykłady hooków dla zespołu programistów

W repozytoriach firm proponuję na start cztery hooki (przykłady hipotetyczne, opisane słownie):

  1. Ochrona plików .env. PreToolUse z matcherem Edit|Write kończy się kodem 2 przy ścieżce .env. Według dokumentacji plik da się jednak zmienić poleceniem powłoki, więc dokładam reguły deny, także na odczyt, i, gdy trzeba, piaskownicę.
  2. Formatowanie po edycji. PostToolUse z matcherem Edit|Write uruchamia formatter, na przykład Prettier, na zmienionym pliku.
  3. Zakaz wypychania na main. PreToolUse na Bash z polem if dla poleceń git blokuje wypchnięcie na main. Filtr if jest według dokumentacji przybliżony, więc twardą blokadę daje reguła deny.
  4. Dziennik poleceń. PostToolUse na Bash zapisuje czas i treść polecenia do pliku albo hookiem HTTP do usługi audytu. Na Windows dopasowuję też PowerShell.

Hook, CLAUDE.md czy reguła deny: co wybrać?

Do zakazów wybieram regułę deny albo hook, bo CLAUDE.md jest dla modelu kontekstem, a nie wymuszoną konfiguracją.

MechanizmJak działaKiedy go używam
CLAUDE.mdinstrukcja czytana na starcie sesji, model może ją pominąćpolecenia projektu, konwencje, pułapki
reguła denyblokuje narzędzie według wzorca, bez skryptuprosty zakaz, na przykład odczyt plików .env
hookwłasny skrypt przy zdarzeniu, może blokować, poprawiać i zapisywaćwarunek wymagający logiki, formatowanie, dziennik

Odmowa z hooka PreToolUse działa w każdym trybie uprawnień, ale zgoda z hooka nie omija reguł deny. Sam plik instrukcji opisuję w poradniku jak napisać CLAUDE.md.

Czy hooki są bezpieczne?

Hook jest tak bezpieczny jak jego skrypt: według dokumentacji hooki poleceń działają z pełnymi uprawnieniami użytkownika i mogą zmienić, usunąć lub odczytać każdy jego plik. Każdy hook czytam i testuję przed dodaniem.

  • Zaufanie do folderu. Sesja interaktywna wstrzymuje hooki do akceptacji zaufania, ale tryb -p i Agent SDK uznają folder za zaufany. Przed skryptem na cudzym repozytorium przeglądam więc katalog .claude albo ustawiam disableAllHooks.
  • Code review. Hook z .claude/settings.json trafia do każdego, kto sklonuje repozytorium, więc przechodzi przegląd jak kod.
  • Higiena skryptów. Zmienne w cudzysłowach, sprawdzanie wejścia, odrzucanie ścieżek z dwiema kropkami i pełne ścieżki do skryptów.

Ryzyka agentów opisuję na stronie bezpieczeństwo agentów AI. Konfigurację hooków rozliczam według stawki 150 do 200 zł netto za godzinę, a wdrożenie opisuje strona Claude Code w firmie.

Źródła

Opis opieram na poniższych źródłach. Przepisy, dokumentacja producentów i warunki usług się zmieniają, więc szczegóły warto sprawdzić u źródła:

Najczęstsze pytania

Jak dodać hook w Claude Code?

Hook dodajesz w kluczu hooks pliku ustawień: nazwa zdarzenia, opcjonalny matcher i polecenie do uruchomienia. Dla zespołu wpisujesz go w .claude/settings.json w repozytorium, dla siebie w ~/.claude/settings.json. Poleceniem /hooks sprawdzisz, czy Claude Code go widzi.

Dlaczego hook w Claude Code nie blokuje działania?

Najpierw sprawdź kod wyjścia: blokuje kod 2, a kod 1 oznacza tylko błąd hooka. Inne przyczyny to matcher niepasujący do nazwy narzędzia (wielkość liter ma znaczenie) albo zdarzenie, które nie blokuje, na przykład PostToolUse.

Czy hooki w Claude Code działają na Windows?

Tak. Hook poleceń domyślnie uruchamia się w Git Bash, a gdy Git for Windows nie jest zainstalowany, w PowerShell. Dla pojedynczego hooka można też wskazać PowerShell wprost polem shell.

Czym hook różni się od reguły deny w Claude Code?

Reguła deny blokuje narzędzie według wzorca, bez skryptu. Hook uruchamia własną logikę: sprawdzi gałąź, sformatuje plik albo zapisze dziennik. Prosty zakaz ustawiam regułą deny, a hook dokładam, gdy trzeba sprawdzić warunek.

Powiązane strony

Chcesz ustawić hooki dla swojego zespołu?

Napisz, czego Claude Code ma pilnować w Waszym repozytorium. Zaproponuję hooki, reguły uprawnień i sposób ich przeglądu.