Hooki Claude Code: dlaczego istnieje każdy z moich 95 hooków
Zbudowałem 95 hooków dla Claude Code. Każdy z nich istnieje, ponieważ najpierw coś poszło nie tak. Git-safety-guardian istnieje, ponieważ Claude wymusił push do gałęzi main. Recursion-guard istnieje, ponieważ subagent zrodził nieskończoną liczbę potomków. Blog-quality-gate istnieje, ponieważ opublikowałem wpis z 7 zdaniami w stronie biernej i wiszącym przypisem.1
Hooki Claude Code to polecenia powłoki wykonywane w określonych punktach cyklu życia (start sesji, przed/po użyciu narzędzia, przesłanie promptu, zakończenie odpowiedzi), stanowiące deterministyczne zabezpieczenia nakładane na probabilistyczne zachowanie LLM. Hooki odbierają JSON na stdin i zwracają decyzje (blokuj, zezwól lub modyfikuj) przez stdout i kody wyjścia. Egzekwują zasady takie jak blokowanie wymuszonych pushów do main, zapobieganie rekurencyjnemu powielaniu agentów, wstrzykiwanie kontekstu w każdej sesji oraz kontrolę jakości wyjścia, której sam LLM nie jest w stanie zagwarantować.
TL;DR
Hooki Claude Code wykonują polecenia powłoki w określonych punktach cyklu życia podczas programowania wspieranego przez AI. Zapewniają deterministyczne gwarancje (blokowanie niebezpiecznych poleceń git, wstrzykiwanie kontekstu, egzekwowanie jakości) na szczycie systemu probabilistycznego (LLM). Po zbudowaniu 95 hooków w ramach mojej infrastruktury stwierdziłem, że najlepsze hooki powstają z incydentów, a nie z planowania. Ten wpis obejmuje architekturę, historie powstania moich najbardziej krytycznych hooków oraz wzorce, których nauczyłem się podczas 9 miesięcy rozwijania hooków.
Zaktualizowano 21 października 2026 r. Poprawiłem poniższe przykłady PreToolUse, które teraz używają hookSpecificOutput.permissionDecision, zdania o kodach wyjścia oraz przykład konfiguracji, który teraz odpowiada aktualnemu schematowi ustawień. Pola najwyższego poziomu decision i reason, które wcześniej pokazywały przykłady, są dla tego zdarzenia przestarzałe. Poprawkę zainicjowało zgłoszenie od czytelnika.
Architektura
Claude Code udostępnia 26 zdarzeń cyklu życia, w których hooki mogą przechwytywać, modyfikować lub blokować zachowanie (stan na v2.1.116, kwiecień 2026).2 Moje hooki celują w sześć najpowszechniejszych z nich:
Zdarzenia sesji
| Zdarzenie | Kiedy się uruchamia | Moje hooki |
|---|---|---|
| SessionStart | Rozpoczyna się nowa sesja | session-start.sh: wstrzykuje datę, waliduje venv, inicjalizuje stan rekurencji |
| SessionEnd | Sesja kończy się | Czyszczenie plików tymczasowych |
Zdarzenia wykonania narzędzi
| Zdarzenie | Kiedy się uruchamia | Moje hooki |
|---|---|---|
| PreToolUse | Przed wykonaniem dowolnego narzędzia | git-safety-guardian.sh, recursion-guard.sh, credentials-check.sh |
| PostToolUse | Po zakończeniu narzędzia | post-deliberation.sh, log-bash.sh |
Zdarzenia odpowiedzi
| Zdarzenie | Kiedy się uruchamia | Moje hooki |
|---|---|---|
| UserPromptSubmit | Użytkownik wysyła prompt | Wstrzykiwacze kontekstu (data, gałąź, informacje o modelu) |
| Stop | Claude kończy odpowiadać | deliberation-pride-check.sh, reviewer-stop-gate.sh |
Każdy hook typu command odbiera JSON na stdin i odpowiada przez kod wyjścia, stdout i stderr. Hook PreToolUse blokuje wywołanie, wypisując poniższy JSON i kończąc działanie z kodem 0:
{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Force push to main is prohibited"}}
Może też nie zgłosić żadnej decyzji: nic nie wypisuje, kończy działanie z kodem 0, a wywołanie przechodzi przez zwykły proces uprawnień; milczenie nie oznacza zatwierdzenia. Kod wyjścia 2 również blokuje, a uzasadnieniem jest stderr hooka, chyba że hook wypisał też JSON z decyzją blokującą, której uzasadnienie ma wtedy pierwszeństwo. Forma najwyższego poziomu {"decision": "block", "reason": "..."}, której hooki PreToolUse używały wcześniej, jest dla tego zdarzenia przestarzała: Claude Code mapuje dawne wartości "block" i "approve" na "deny" i "allow", dlatego nowe hooki należy pisać z użyciem hookSpecificOutput. Inne zdarzenia, w tym PostToolUse i Stop, nadal używają pól najwyższego poziomu decision i reason jako swojego aktualnego formatu.3
W tym wpisie PreToolUse:Bash i PreToolUse:Task to moje etykiety dla grupy matchera PreToolUse ustawionej na narzędzie Bash oraz na narzędzie subagentów, które w chwili publikacji tego wpisu nazywało się Task, a od v2.1.63 nazywa się Agent.9 Nie są to klucze ustawień; sekcja o konfiguracji pokazuje rzeczywistą strukturę.7
Historie powstania: hooki, które mają największe znaczenie
Hook 1: git-safety-guardian.sh (PreToolUse:Bash)
Incydent: Podczas jednej z wczesnych sesji Claude Code poprosiłem agenta o „uporządkowanie historii git”. Agent wykonał git push --force origin main. Wymuszony push nadpisał trzy dni commitów na współdzielonej gałęzi. Odzyskałem dane z lokalnej kopii zapasowej, ale 4-godzinny proces odzyskiwania przekonał mnie, że probabilistyczny osąd nigdy nie powinien kontrolować destrukcyjnych operacji git.
Hook:
#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
# Only check git commands
echo "$COMMAND" | grep -qE '\bgit\b' || exit 0
# Block force push to main/master
if echo "$COMMAND" | grep -qiE 'git\s+push\s+.*--force.*\b(main|master)\b'; then
cat << EOF
{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Force push to main/master blocked by safety hook"}}
EOF
fi
Wniosek: Hook nie próbuje zrozumieć intencji. Dopasowuje wzorzec do ciągu polecenia. Prosty, deterministyczny, niemożliwy do obejścia przez sprytne promptowanie. Agent nadal może wymusić push do gałęzi funkcyjnych (czasem uzasadniony), ale main/master są trwale chronione.4
Uratowane przez cały okres działania: 8 przechwyconych prób wymuszonego pusha w ciągu 9 miesięcy.
Hook 2: recursion-guard.sh (PreToolUse:Task)
Incydent: Podczas budowania systemu deliberacji uruchomiłem sesję, która zrodziła 3 subagenty eksploracyjne. Każdy z subagentów, nie mając limitów powielania, zrodził własne subagenty. Rekurencja pochłonęła API tokenów w tempie 10-krotnie większym niż normalne. Zabiłem sesję ręcznie po zauważeniu przyspieszającego spalania tokenów.
Hook:
#!/bin/bash
CONFIG_FILE="${HOME}/.claude/configs/recursion-limits.json"
STATE_FILE="${HOME}/.claude/state/recursion-depth.json"
MAX_DEPTH=2
MAX_CHILDREN=5
DELIB_SPAWN_BUDGET=2
DELIB_MAX_AGENTS=12
# Validate integers safely (((VAR++)) crashes with set -e when VAR=0)
is_positive_int() {
[[ "$1" =~ ^[0-9]+$ ]] && [[ "$1" -gt 0 ]]
}
Kluczowa decyzja projektowa: Agenci dziedziczą budżet powielania po rodzicu, zamiast zwiększać głębokość. Agent root z budżetem=12 może rozdzielić ten budżet w ramach dowolnego kształtu drzewa. Limity oparte na głębokości są zbyt sztywne (uniemożliwiają głębokie, ale wąskie łańcuchy, które są całkowicie bezpieczne).5
Blokady przez cały okres działania: 23 próby niekontrolowanego powielania.
Hook 3: blog-quality-gate.sh (Stop)
Incydent: Opublikowałem wpis na blogu z 7 zdaniami w stronie biernej, przypisem odwołanym w tekście, ale brakującym w sekcji odniesień, oraz zdaniem „was implemented by the team” jako linią otwierającą. Wpis wyglądał dopracowanie w moim edytorze, ale nie przeszedł podstawowych kontroli jakości, które wychwyciłby każdy ludzki recenzent.
Hook: Uruchamia mój 12-modułowy linter blogowy na każdym zmodyfikowanym pliku treści bloga. Sprawdza stronę bierną, wiszące przypisy, brakujące meta-opisy, nieotagowane bloki kodu oraz integralność cytowań. Każde znalezisko jest konkretne: „Linia 47: wykryto stronę bierną w ‘was implemented by the team.’ Sugestia: ‘the team implemented.’”
Analogia z ludzkim feedbackiem: Hook krytykuje pracę, a nie operatora. Mówi „linia 47 zawiera stronę bierną”, a nie „piszesz źle”. Ta sama zasada, która czyni ludzki feedback konstruktywnym, czyni zautomatyzowany feedback użytecznym.
Wzorzec stojący za 95 hookami
Architektura oparta na konfiguracji
Moje hooki ewoluowały od zakodowanych na sztywno wartości do zachowań sterowanych konfiguracją:
~/.claude/configs/
├── recursion-limits.json # Depth, spawn budgets, timeouts
├── deliberation-config.json # Consensus thresholds per task type
├── consensus-profiles.json # security=85%, docs=50%
├── circuit-breaker.json # Failure mode configurations
└── file-scope-rules.json # Path-scoped hook application
Przeniesienie progów do konfiguracji JSON oznaczało, że mogłem dostrajać zachowanie bez edytowania skryptów bash. Gdy potrzebowałem konsensusu związanego z bezpieczeństwem na poziomie 85%, a dokumentacji na 50%, zmiana konfiguracji zajęła 30 sekund. Zmiana kodu wymagałaby edytowania, testowania i ponownego wdrożenia.6
Wzorzec warstwowania cyklu życia
Moje 95 hooków tworzy siatkę bezpieczeństwa z czterema warstwami:
Warstwa 1: Prewencja (PreToolUse): Powstrzymuj złe rzeczy, zanim się wydarzą. git-safety-guardian, credentials-check, recursion-guard.
Warstwa 2: Kontekst (UserPromptSubmit, SessionStart): Wstrzykuj informacje, których agent potrzebuje. Data, gałąź, kontekst projektu, wpisy pamięci, zasady filozofii.
Warstwa 3: Walidacja (PostToolUse): Weryfikuj, czy zakończone działania spełniają standardy. Sprawdzanie konsensusu po deliberacji, logowanie wyjścia.
Warstwa 4: Jakość (Stop): Bramkowanie końcowego wyjścia. Pride check, quality gate, reviewer stop gate. Ta warstwa realizuje monitorowanie metapoznawcze, w którym agent ocenia jakość własnego rozumowania, a nie tylko wyjścia.
Każda warstwa jest niezależna. Jeśli hook PreToolUse zawiedzie po cichu, hook Stop nadal wychwyci problemy z jakością. Obrona w głąb, zastosowana do zachowania agenta AI.
Konfiguracja
Hooki znajdują się w .claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "~/.claude/hooks/git-safety-guardian.sh", "timeout": 5 }
]
},
{
"matcher": "Agent",
"hooks": [
{ "type": "command", "command": "~/.claude/hooks/recursion-guard.sh" }
]
}
]
}
}
Konfiguracja ma trzy poziomy: zdarzenie, grupę matchera, która filtruje, przy jakich wywołaniach narzędzi hook się uruchamia, oraz handlery wykonywane po dopasowaniu. timeout podaje się w sekundach; domyślnie wynosi 600 dla hooka typu command w większości zdarzeń, w tym w PreToolUse. PreToolUse:Task, etykieta z sekcji o architekturze, to tutaj druga grupa: grupa PreToolUse z matcherem Agent. Hooki asynchroniczne ("async": true) działają w tle bez blokowania, co oznacza również, że niczego nie mogą zablokować ani o niczym zdecydować.7
Hierarchia zasięgu
- Poziom użytkownika (
~/.claude/settings.json): ma zastosowanie do wszystkich projektów. Moje 95 hooków znajduje się tutaj. - Poziom projektu (
.claude/settings.json): dodaje hooki specyficzne dla projektu. - Frontmatter Skill/Subagent: ograniczony do cyklu życia konkretnego komponentu.8
Co zrobiłbym inaczej
Zacząć od 3 hooków, a nie 25. Mój pierwszy miesiąc dał 25 hooków, z których wiele dodawało kontekst, który agent już posiadał. Narzut związany z ładowaniem 25 hooków przy każdym wywołaniu narzędzia był mierzalny. Ostatecznie przyciąłem zestaw do hooków przynoszących realną wartość (zapobiegających realnym incydentom, wychwytujących realne problemy z jakością).
Oparcie na konfiguracji od pierwszego dnia. Spędziłem dwa tygodnie na refaktoryzacji zakodowanych na sztywno progów do konfiguracji JSON. Ta refaktoryzacja byłaby darmowa, gdybym zaczął od konfiguracji.
Wczesna infrastruktura testowa. Pierwsze 20 hooków nie miało testów. Gdy dodałem zestaw testowy (48 testów integracyjnych bash), znalazłem 3 hooki, które po cichu zawodziły w przypadkach brzegowych. Testy powinny były trafić razem z hookiem #1.
Kluczowe wnioski
Dla deweloperów zaczynających z hookami: - Warto zacząć od trzech hooków: bezpieczeństwo git (PreToolUse:Bash), wstrzykiwanie kontekstu (UserPromptSubmit) oraz bramka jakości (Stop); kolejne należy dodawać dopiero wtedy, gdy pojawią się incydenty, które to uzasadniają - Warto zastosować framework momentu decyzji: architektura hooków jest nieodwracalna (95 hooków od niej zależy), więc należy zainwestować w model cyklu życia przed napisaniem hooków
Dla zespołów standaryzujących hooki: - Należy standaryzować hooki na poziomie użytkownika, aby każdy członek zespołu otrzymał te same zabezpieczenia - Warto śledzić metryki hooków (zablokowane operacje, przechwycone incydenty), aby uzasadnić koszt utrzymania - Należy co miesiąc przeglądać logi hooków, aby zidentyfikować nowe wzorce warte zautomatyzowania
FAQ
Czym są hooki Claude Code?
Hooki to skrypty powłoki wykonywane w określonych punktach cyklu życia podczas sesji Claude Code. Uruchamiają się deterministycznie w konkretnych momentach: przed wykonaniem narzędzia (PreToolUse), po jego zakończeniu (PostToolUse), gdy użytkownik wysyła prompt (UserPromptSubmit), gdy sesja się rozpoczyna (SessionStart) oraz gdy Claude kończy odpowiadać (Stop). Hooki odbierają JSON na stdin z pełnym kontekstem (nazwa narzędzia, dane wejściowe, ID sesji) i mogą blokować operacje, wstrzykiwać kontekst lub egzekwować bramki jakości. Dostarczają deterministyczne gwarancje nakładane na probabilistyczny LLM.
Ile hooków może uruchomić Claude Code i czy wiąże się to z kosztem wydajnościowym?
Nie ma twardego limitu liczby hooków. Uruchamiam 95 hooków w 6 z 26 dostępnych zdarzeń cyklu życia (stan na v2.1.116, kwiecień 2026), z łącznym narzutem około 200 ms na zdarzenie. Praktycznym limitem jest latencja: każdy hook dodaje czas wykonania przed lub po wywołaniach narzędzi. Kluczową optymalizacją jest użycie dispatcherów (jeden na zdarzenie, uruchamiający hooki sekwencyjnie z buforowanego stdin) zamiast niezależnych hooków, z których każdy czyta stdin osobno. Równoczesne zapisy z niezależnych hooków powodowały korupcję JSON w mojej wczesnej konfiguracji; dispatchery całkowicie wyeliminowały ten tryb awarii.
Na jakich zdarzeniach uruchamiają się hooki Claude Code?
Claude Code udostępnia 26 zdarzeń cyklu życia dla hooków według stanu na v2.1.116 (kwiecień 2026). Sześć najpowszechniejszych, w które celują moje hooki, to: SessionStart (rozpoczyna się nowa sesja), SessionEnd (sesja kończy się), PreToolUse (przed wykonaniem dowolnego narzędzia), PostToolUse (po zakończeniu narzędzia), UserPromptSubmit (użytkownik wysyła prompt) oraz Stop (Claude kończy odpowiadać). Inne to SubagentStart, PermissionRequest, PermissionDenied, TaskCreated, CwdChanged, FileChanged, PreCompact i więcej. PreToolUse i PostToolUse można dalej ograniczać matcherem na nazwę narzędzia, na przykład Bash lub Agent; PreToolUse:Bash i PreToolUse:Task to stosowany w tym wpisie skrót dla takich grup. Każde zdarzenie odbiera JSON na stdin z odpowiednim kontekstem.
Czy hooki Claude Code mogą blokować wywołania narzędzi?
Tak. Hook PreToolUse, który wypisuje {"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "explanation"}} na stdout i kończy działanie z kodem 0, uniemożliwia wykonanie wywołania narzędzia; kod wyjścia 2 również je blokuje, a uzasadnieniem jest wtedy stderr, chyba że hook wypisał też JSON z decyzją blokującą. Starsza forma najwyższego poziomu {"decision": "block", "reason": "explanation"} jest dla PreToolUse przestarzała; Claude Code mapuje ją na "deny", a inne zdarzenia, takie jak PostToolUse i Stop, nadal używają jej jako swojego aktualnego formatu. To główny mechanizm dla hooków bezpieczeństwa: mój git-safety-guardian blokuje wymuszone pushe do main, mój credentials-check blokuje odczyty plików .env, a mój recursion-guard blokuje nadmierne powielanie agentów. Blokada jest deterministyczna i nie można jej obejść przez promptowanie. Hook, który kończy działanie z kodem 0 i niczego nie wypisuje, nie ma żadnej decyzji do zgłoszenia, więc operacja przechodzi przez zwykły proces uprawnień.
Jaka jest różnica między hookami PreToolUse i PostToolUse?
PreToolUse uruchamia się przed wykonaniem narzędzia i może zablokować operację całkowicie. Stosuje się go do bramek bezpieczeństwa: blokowania niebezpiecznych poleceń, sprawdzania poświadczeń, egzekwowania budżetów powielania. PostToolUse uruchamia się po zakończeniu narzędzia i może zapewnić informację zwrotną lub wyzwolić działania następcze. Stosuje się go do walidacji: sprawdzania jakości wyjścia, logowania aktywności, weryfikowania konsensusu. Razem tworzą pierwszą i trzecią warstwę czterowarstwowej siatki bezpieczeństwa: prewencja (PreToolUse), wstrzykiwanie kontekstu (UserPromptSubmit), walidacja (PostToolUse) oraz bramkowanie jakości (Stop).
Odniesienia
-
Infrastruktura hooków autora. 95 hooków w 6 z 26 dostępnych zdarzeń cyklu życia (v2.1.116, kwiecień 2026), opracowana przez 9 miesięcy (2025-2026). ↩
-
Anthropic, „Claude Code Hooks Reference,” 2026. 26 typów zdarzeń cyklu życia według stanu na v2.1.116 (kwiecień 2026). ↩
-
Anthropic, „Hooks reference,” dokumentacja Claude Code, pobrano 21 października 2026 r. Kontrola decyzji PreToolUse: „PreToolUse previously used top-level
decisionandreasonfields, but these are deprecated for this event. UsehookSpecificOutput.permissionDecisionandhookSpecificOutput.permissionDecisionReasoninstead. The deprecated values"approve"and"block"map to"allow"and"deny"respectively. Other events like PostToolUse and Stop continue to use top-leveldecisionandreasonas their current format.” Kod wyjścia 2 w PreToolUse: „Blocks the tool call”; „The message that comes with the block is your hook’s stderr.” Kod wyjścia 0: „Exit code 0 with no output means the hook has no decision to report, so the tool call continues through the normal permission flow. The hook can deny the call, but staying silent doesn’t approve it.” Kod wyjścia 2 z JSON: „If your hook also printed JSON that makes a blocking decision, Claude Code uses that decision’s reason instead.” ↩ -
Skrypt git-safety-guardian.sh autora. 8 przechwyconych prób wymuszonego pusha śledzonych w
~/.claude/state/. ↩ -
Skrypt recursion-guard.sh autora. Model dziedziczenia budżetu udokumentowany w
~/.claude/configs/recursion-limits.json. ↩ -
Architektura autora oparta na konfiguracji. 14 plików konfiguracyjnych JSON kodujących wszystkie progi i reguły hooków. ↩
-
Anthropic, „Hooks reference,” dokumentacja Claude Code, pobrano 21 października 2026 r. Konfiguracja: „The configuration has three levels of nesting”, wymienione jako „Choose a hook event to respond to, like PreToolUse or Stop”, „Add a matcher group to filter when it fires, like “only for the Bash tool”” oraz „Define one or more hook handlers to run when matched”. Wspólne pola:
typeto „command”, „http”, „mcp_tool”, „prompt” lub „agent”;timeoutto „Seconds before canceling. Claude Code doesn’t enforce it on a command hook you run with async: true. Defaults: 600 for command, http, and mcp_tool; 30 for prompt; 60 for agent. Claude Code lowers the command, http, and mcp_tool default to 30 on UserPromptSubmit, PreModelSwitch, and PostModelSwitch, and to 10 on MessageDisplay.” Poleasynchooka typu command: „If true, runs in the background without blocking.” Hooki w tle: „Async hooks can’t block or control Claude’s behavior: response fields like decision, permissionDecision, and continue have no effect, because the action they would have controlled has already completed.” Matcher PreToolUse: „Matches on any tool name except EndConversation: built-in tools such as Bash, PowerShell, Edit, Write, Read, Glob, Grep, Agent, Workflow, WebFetch, WebSearch, AskUserQuestion, and ExitPlanMode, and any MCP tool names.” ↩↩ -
Anthropic, „Claude Code Documentation,” 2025. Hierarchia zasięgu hooków. ↩
-
Anthropic, „Create custom subagents,” dokumentacja Claude Code, pobrano 21 października 2026 r.: „In version 2.1.63, the Task tool was renamed to Agent. Existing
Task(...)references in settings and agent definitions still work as aliases.” ↩