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:
| Zdarzenie | Kiedy działa | Przykład użycia w firmie |
|---|---|---|
| SessionStart | start lub wznowienie sesji, także po kompaktowaniu kontekstu | przypomnienie zasad sprintu w kontekście |
| UserPromptSubmit | po wysłaniu polecenia, przed jego przetworzeniem | zatrzymanie polecenia z wklejonym kluczem API |
| PreToolUse | przed wywołaniem narzędzia, może je zablokować | blokada plików .env albo wypychania na main |
| PostToolUse | po udanym wywołaniu narzędzia | formatowanie pliku, wpis do dziennika |
| Notification | gdy Claude Code wysyła powiadomienie | informacja, że agent czeka na zgodę |
| Stop | gdy Claude kończy odpowiedź | sprawdzenie, czy testy przechodzą |
| ConfigChange | gdy w trakcie sesji zmieni się plik konfiguracji | zapis 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):
- 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ę.
- Formatowanie po edycji. PostToolUse z matcherem Edit|Write uruchamia formatter, na przykład Prettier, na zmienionym pliku.
- 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.
- 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ą.
| Mechanizm | Jak działa | Kiedy go używam |
|---|---|---|
| CLAUDE.md | instrukcja czytana na starcie sesji, model może ją pominąć | polecenia projektu, konwencje, pułapki |
| reguła deny | blokuje narzędzie według wzorca, bez skryptu | prosty zakaz, na przykład odczyt plików .env |
| hook | wł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:
- Hooks reference (Anthropic)
- Automate actions with hooks (Anthropic)
- Settings files and precedence (Anthropic)
- Configure permissions (Anthropic)
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.