Czym są hooki?
Hooki to skrypty lub handlery, które agent kodujący uruchamia w stałych zdarzeniach swojej pętli, na przykład przed wywołaniem narzędzia albo na końcu tury, niezależnie od decyzji modelu. W zdarzeniach, które mogą blokować, hook zatrzymuje akcję, czego linijka w CLAUDE.md nie zrobi. Claude Code 2.1.283 dokumentuje 33 zdarzenia hooków, Codex 0.157.1 dokumentuje 12, a hooki Cursora też potrafią blokować.
- Po angielsku
- Hooks
- Pierwsze wdrożenie
- Poziom 4, darmowy przewodnik
- Szukane też jako
- hooki agenta, hooks, Claude Code hooks, lifecycle hooks
249,99 zł jednorazowo za 12 miesięcy dostępu. Nic się samo nie odnawia. Zwrot w ciągu 30 dni przy pierwszym zakupie.
Dlaczego to ważne.
Linijka w CLAUDE.md to rada, którą model waży na tle całego pozostałego kontekstu. Hook to kod uruchamiany przy każdym pasującym zdarzeniu, więc kontrola, która ma się wykonać zawsze, na przykład testy przed „gotowe”, należy do hooka. Hook jest bramką tylko wtedy, gdy kończy się kodem 2 albo zwraca odmowę w JSON-ie: kod 1, awaria albo literówka w ścieżce skryptu przepuszczają akcję.
Jedna reguła, zapisana na dwa sposoby
Ta sama reguła, „nigdy nie rób force push”: jako linijka w CLAUDE.md i jako hook PreToolUse na narzędziu Bash.
- Rada, którą model waży
- Kod, który się wykonuje
- Na czym możesz polegać
W CLAUDE.md Doradcza
-
Reguła
Never force push.Jedna linijka w
CLAUDE.md, obok wszystkiego innego, co model przeczytał. -
Model
Waży ją na tle zadania
Słowami przewodnika: rada, którą model waży na tle całego pozostałego kontekstu.
-
Polecenie
git push --forceNic w tym torze nie sprawdza go przed uruchomieniem.
-
Na czym możesz polegać
Na osądzie modelu
Przewodnik wychodzi od
CLAUDE.md, którego reguły agent i tak złamał.
Jako hook PreToolUse Egzekwowana
-
Reguła
block-destructive.shSkrypt zarejestrowany dla
PreToolUsez matcheremBash. -
Polecenie
git push --forceClaude zaraz wywoła narzędzie Bash.
-
Hook je czyta
Dopasowuje wzorzec force push
Odpowiada powodem odmowy,
Force push is blocked. Push a new commit instead., który trafia do Claude jako następna instrukcja. -
Na czym możesz polegać
Zablokowane, o ile zapis pasuje do wzorca
Przewodnik nazywa ten skrypt progiem zwalniającym:
rm -r -fifind . -deleteprzechodzą przez jego wzorce, więc dołóż regułypermissions.denyi sandbox.
Gdzie wchodzi hook
Claude Code 2.1.283 wywołuje 33 zdarzenia hooków. Pięć hooków z przewodnika używa tych czterech.
| Zdarzenie | Kiedy się wywołuje | Co robi kod wyjścia 2 |
|---|---|---|
SessionStart | Start, wznowienie, wyczyszczenie lub kompakcja sesji | Nie blokuje. Zwykły tekst na stdout przy kodzie 0 trafia do kontekstu Claude |
PreToolUse | Przed każdym wywołaniem narzędzia | Blokuje wywołanie; stderr trafia do Claude jako powód |
PostToolUse | Po udanym wywołaniu narzędzia | Nie cofnie wywołania. Pokazuje stderr Claude, który to poprawia |
Stop i SubagentStop | Claude lub subagent kończy odpowiedź | Każe pracować dalej |
WorktreeCreate, gdzie każdy niezerowy kod przerywa tworzenie worktree.Który mechanizm pasuje do reguły
Umieść każdą regułę w najsłabszym mechanizmie, który wciąż ją egzekwuje. Silniejsze kosztują więcej opóźnień i utrzymania, a hooki promptowe kosztują też tokeny.
| Mechanizm | Egzekwowany? | Do czego | Przykład |
|---|---|---|---|
CLAUDE.md | Nie, doradczy | Konwencje i kontekst, które model powinien znać | „Używamy pnpm, nie npm.” |
Reguła uprawnień (permissions.deny) | Tak, stały wzorzec | Stała lista narzędzi, poleceń lub ścieżek | Deny Bash(curl *), deny Edit(.env) |
Hook poleceniowy (command) | Tak, obliczany | Kontrole wymagające logiki, treści pliku lub stanu repozytorium | Lint edytowanego pliku; blokada DROP TABLE w każdej postaci |
| Hook promptowy lub agentowy | Tak, oceniany przez model | Kontrole wymagające osądu, a nie dopasowania wzorca | „Czy końcowa wiadomość podaje polecenie testowe, które uruchomiono?” |
Dwa hooki, tak jak zapisuje je przewodnik
Hook PreToolUse, który blokuje trzy destrukcyjne warianty polecenia, i hook Stop, który nie pozwala skończyć, dopóki testy nie przechodzą. Oba są zarejestrowane w .claude/settings.json i uruchamiają się przy każdym pasującym zdarzeniu.
Źródło: Przewodnik po hookach, Claude Code 2.1.283, 2026-10-03. Otwórz przewodnik
#!/usr/bin/env bash # .claude/hooks/block-destructive.sh (PreToolUse, matcher "Bash") set -euo pipefail # Fail closed: without jq this gate cannot read the command, so block. command -v jq >/dev/null || { echo "jq is missing; install it before running Bash." >&2; exit 2; } cmd=$(jq -r '.tool_input.command // empty') deny() { jq -nc --arg r "$1" '{hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: $r}}' exit 0 } shopt -s nocasematch rm_rf='(^|[;&|[:space:]])rm[[:space:]]+-[a-z]*(rf|fr)' sql_drop='(drop|truncate)[[:space:]]+(table|database|schema)' force_push='git[[:space:]]+push.*(--force|[[:space:]]-f([[:space:]]|$))' [[ $cmd =~ $rm_rf ]] && deny "rm -rf is blocked. Delete the specific files by path." [[ $cmd =~ $sql_drop ]] && deny "Destructive SQL is blocked. Write a migration and stop for review." [[ $cmd =~ $force_push ]] && deny "Force push is blocked. Push a new commit instead." exit 0
#!/usr/bin/env bash # .claude/hooks/tests-before-stop.sh (Stop) set -uo pipefail retrying=$(jq -r '.stop_hook_active') # Nothing changed in the working tree: nothing to verify. [[ -z $(git status --porcelain) ]] && exit 0 if out=$(npm test --silent 2>&1); then exit 0; fi tail_out=$(tail -n 40 <<<"$out") if [[ $retrying == "true" ]]; then jq -nc '{systemMessage: "Tests still fail after one retry. Stopping for a human."}' exit 0 fi jq -nc --arg r "The test suite fails. Fix it before you finish. Last 40 lines: $tail_out" '{decision: "block", reason: $r}'
rm -r -f, rm --recursive --force i find . -delete przechodzą przez te wzorce. Dopasowanie wzorców łapie typowe zapisy, ale nie wszystkie, więc wszystko, co nigdy nie może się wykonać, zablokuj dodatkowo regułami permissions.deny i sandboxem.Pełny przewodnik jest w cenie Toolkitu.
Kup Toolkit249,99 zł jednorazowo za 12 miesięcy dostępu. Nic się samo nie odnawia. Zwrot w ciągu 30 dni przy pierwszym zakupie.
Jak robi to każde narzędzie.
Cursor, Claude Code i Codex nazywają to po swojemu. Każda notatka ma datę sprawdzenia.
Cursor
Hooki to uruchamiane procesy, które wymieniają JSON przez stdio i mogą obserwować, blokować albo zmieniać zachowanie. Strona o hookach Cursora wymienia zdarzenia takie jak preToolUse, beforeShellExecution i afterFileEdit (sprawdzone 2026-10-12); pliku konfiguracji nie sprawdzono ponownie.
Przewodnik po hookach w wielu narzędziach (dokumentacja Cursora), 2026-08-28
Claude Code
33 zdarzenia hooków w 2.1.283; handlerem może być polecenie powłoki, endpoint HTTP, narzędzie MCP, prompt albo agent. Kod wyjścia 2 blokuje wywołanie w PreToolUse.
Hooki z różnych lokalizacji się sumują: ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, ustawienia zarządzane, pluginy oraz frontmatter skilla lub subagenta, i żadna nie zastępuje innej. Otwórz /hooks w sesji, żeby zobaczyć, które hooki się załadowały i z którego pliku.
Przewodnik po hookach, Claude Code 2.1.283, 2026-10-03
Codex
12 zdarzeń hooków; hook działa dopiero po utrwaleniu zaufania.
Nowy runner CI nie ma jeszcze żadnego zaufania, więc sprawdź, czy wynik hooka pojawia się w logu zadania. --dangerously-bypass-hook-trust pomija tę kontrolę i nadaje się tylko do automatyzacji, która sama weryfikuje źródło hooka.
Macierz funkcji, Codex 0.157.1, 2026-09-26
Najczęstsze pytania.
Do czego służą hooki?
Powtarza się pięć zadań: blokowanie destrukcyjnych poleceń powłoki, ochrona ścieżek, których agent nie może edytować, formatowanie i lint każdej edycji, odmowa zakończenia pracy przy czerwonych testach oraz dodawanie na starcie sesji kontekstu na żywo, takiego jak branch i wynik ostatniego CI. Pierwsze cztery to bramki; piąte tylko dodaje kontekst.
Który kod wyjścia blokuje akcję?
Kod wyjścia 2, w zdarzeniach, które mogą blokować. Każdy inny kod, łącznie z 1, nie blokuje, chyba że decyzję podejmuje poprawny JSON na stdout: Claude Code pokazuje komunikat o błędzie hooka i akcja idzie dalej. Wyjątkiem jest WorktreeCreate, gdzie każdy niezerowy kod przerywa tworzenie worktree.
Czy Codex i Cursor mają hooki?
Tak, z innymi zdarzeniami i innym formatem odpowiedzi. Codex dokumentuje 12 zdarzeń i uruchamia hook projektu dopiero po tym, jak mu zaufasz w /hooks. Hooki Cursora wymieniają JSON przez stdio i mogą blokować; strona o hookach Cursora wymienia zdarzenia takie jak preToolUse, beforeShellExecution i afterFileEdit (sprawdzone 2026-10-12), więc zanim przeniesiesz skrypt, sprawdź pełną listę.
Czy jeden hook wystarczy, żeby zatrzymać rm -rf?
Nie. Hook PreToolUse oparty na wzorcach to próg zwalniający: rm -r -f, rm --recursive --force i find . -delete przechodzą przez jego wzorce. Wszystko, co nigdy nie może się wykonać, zablokuj dodatkowo regułami permissions.deny i sandboxem.
Czytaj dalej.
Przewodniki, które idą głębiej, oraz hasła i porównania obok tego.
W dokumentacji
Powiązane hasła
Czy ta strona odpowiada na Twoje pytania?
Jedno kliknięcie, bez logowania.
Czego tu szukasz?
Co Cię powstrzymuje?
Jak się to czyta?
Dzięki. Jeśli zostawiasz e-mail, odpisze Ci Michał.
Odpowiada na Twoje pytania?
Każde to jedno kliknięcie. Zamknij, kiedy chcesz.
bez logowania
Czytaj przewodniki w tych samych słowach.
Otwórz wszystkie przewodniki z Toolkitem. Każde hasło jest tu zdefiniowane raz, a przewodniki używają go tak samo.
249,99 zł jednorazowo za 12 miesięcy dostępu. Nic się samo nie odnawia. Zwrot w ciągu 30 dni przy pierwszym zakupie.
Odpisuje Michał, nie automat. Adres służy tylko tej odpowiedzi.