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ć.

Ostatnia aktualizacja
Autor:
Opublikowano
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.

Na tej stronie Dlaczego to ważneGdzie wchodzi hookKtóry mechanizm pasuje do regułyDwa hooki, tak jak zapisuje je przewodnikJak robi to każde narzędziePytania

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

  1. Reguła

    Never force push.

    Jedna linijka w CLAUDE.md, obok wszystkiego innego, co model przeczytał.

  2. Model

    Waży ją na tle zadania

    Słowami przewodnika: rada, którą model waży na tle całego pozostałego kontekstu.

  3. Polecenie

    git push --force

    Nic w tym torze nie sprawdza go przed uruchomieniem.

  4. 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

  1. Reguła

    block-destructive.sh

    Skrypt zarejestrowany dla PreToolUse z matcherem Bash.

  2. Polecenie

    git push --force

    Claude zaraz wywoła narzędzie Bash.

  3. 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.

  4. Na czym możesz polegać

    Zablokowane, o ile zapis pasuje do wzorca

    Przewodnik nazywa ten skrypt progiem zwalniającym: rm -r -f i find . -delete przechodzą przez jego wzorce, więc dołóż reguły permissions.deny i sandbox.

Umieść każdą regułę w najsłabszym mechanizmie, który wciąż ją egzekwuje. Dla wszystkiego, co nigdy nie może się wykonać, przewodnik dokłada obok hooka reguły permissions.deny i sandbox. Źródło: Przewodnik po hookach, Claude Code 2.1.283, 2026-10-03.

Gdzie wchodzi hook

Claude Code 2.1.283 wywołuje 33 zdarzenia hooków. Pięć hooków z przewodnika używa tych czterech.

Cztery zdarzenia hooków w Claude Code: kiedy się wywołują i co robi kod wyjścia 2.
ZdarzenieKiedy się wywołujeCo 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
Kod 1 nie jest bramką. Każdy kod inny niż 2 nie blokuje, chyba że decyzję podejmuje poprawny JSON na stdout: Claude Code pokazuje komunikat „hook error” i akcja idzie dalej. Wyjątkiem jest WorktreeCreate, gdzie każdy niezerowy kod przerywa tworzenie worktree.

Źródło: Przewodnik po hookach, Claude Code 2.1.283, 2026-10-03.

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.

Cztery sposoby przekazania reguły Claude Code: czy jest egzekwowana, do czego pasuje, przykład.
MechanizmEgzekwowany?Do czegoPrzykł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?”

Jeśli politykę da się wyrazić statyczną regułą, użyj reguły uprawnień: oficjalna dokumentacja hooków nazywa filtr if „best-effort” i do twardego allow i deny zaleca system uprawnień. Hooki to właściwe miejsce na wszystko, co sprawdza wynik. Źródło: Przewodnik po hookach, Claude Code 2.1.283, 2026-10-03.

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

.claude/hooks/block-destructive.sh (PreToolUse, matcher "Bash")
#!/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
.claude/hooks/tests-before-stop.sh (Stop)
#!/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}'
Pierwszy hook to próg zwalniający, a nie granica. 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 Toolkit

249,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.

Czy ta strona odpowiada na Twoje pytania?

Jedno kliknięcie, bez logowania.

wcale w pełni

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.