·
Paweł Łukasiewicz: programista blogger
Paweł Łukasiewicz · Senior .NET Developer
13 października 2026 · Claude Code, artykuł 12 z 16
Paweł Łukasiewicz: programista blogger
Paweł Łukasiewicz · Senior .NET Developer
13 października 2026 · Claude Code, artykuł 12 z 16
Wprowadzenie

Przez całą serię powtarzam jedną zasadę: CLAUDE.md to prośba. Agent zwykle się do niej stosuje, ale nie ma gwarancji, że po długiej sesji, po streszczeniu kontekstu albo przy niejasnym poleceniu nie pominie formatowania, testów czy zakazu edycji pliku. W artykule 08 poznałeś pierwszą twardą warstwę: reguły allow, ask i deny w settings.json. Są świetne, ale statyczne – opisują wzorce, a nie logikę.

Hooki to druga twarda warstwa. To komendy (najczęściej skrypty), które Claude Code uruchamia automatycznie w konkretnych momentach pracy agenta: przed wywołaniem narzędzia, po edycji pliku, gdy agent kończy odpowiedź, gdy czeka na Twoją decyzję. Hook nie prosi agenta, żeby sformatował kod – po prostu uruchamia formatter. Hook nie instruuje agenta, żeby nie ruszał migracji – blokuje edycję, zanim do niej dojdzie. Od „proszę, rób X” do „X zawsze się wykona”.

Jeśli czytałeś artykuł o hookach w serii Agentic Development, idea będzie Ci znajoma – tam pokazywałem ją na przykładzie GitHub Copilota. Mechanizm w Claude Code jest bogatszy: ma więcej zdarzeń, kilka typów hooków i pełną integrację z systemem uprawnień.

📋 Mapa tego artykułu
Chcę… Przejdź do
Zrozumieć, czym są hooki i kiedy się uruchamiająZdarzenia i konfiguracja
Wiedzieć, jak hook komunikuje się z Claude CodeAnatomia hooka
Dostać powiadomienie, gdy agent czekaPrzykład 1: powiadomienia
Formatować kod po każdej edycjiPrzykład 2: formatowanie
Zablokować edycję wrażliwych plików i komendPrzykłady 3 i 4: blokady
Nie pozwolić agentowi skończyć z czerwonymi testamiPrzykład 5: testy przed końcem pracy
Zobaczyć komplet hooków dla DevPulseHooki w DevPulse
Zdarzenia i konfiguracja

Hook to para: zdarzenie (kiedy) i akcja (co uruchomić). Claude Code udostępnia kilkadziesiąt zdarzeń – poniżej te, których będziesz używać najczęściej:

Zdarzenie Kiedy się uruchamia Typowe zastosowanie
SessionStart Start lub wznowienie sesji, także po streszczeniu kontekstu Dołożenie aktualnego kontekstu (branch, zamrożenie deployu)
UserPromptSubmit Po wysłaniu polecenia, zanim agent je przetworzy Walidacja polecenia, dodanie kontekstu
PreToolUse Przed wywołaniem narzędzia – może je zablokować Blokady plików i komend, walidacja argumentów
PermissionRequest Gdy narzędzie wymaga decyzji o uprawnieniach Automatyczne zatwierdzanie lub odrzucanie wybranych próśb
PostToolUse Po udanym wywołaniu narzędzia Formatowanie, lint, logowanie zmian
Notification Gdy Claude Code wysyła powiadomienie (np. czeka na zgodę albo na Ciebie) Powiadomienie na pulpicie, telefonie, Slacku
Stop / SubagentStop Gdy agent (lub subagent) kończy odpowiedź Sprawdzenie, czy praca jest naprawdę skończona (np. testy)
PreCompact / SessionEnd Przed streszczeniem kontekstu / na końcu sesji Zapis notatek, sprzątanie

Gdzie konfigurować hooki

Hooki definiujesz w tych samych plikach settings.json co uprawnienia, w kluczu hooks:

Lokalizacja Zakres
~/.claude/settings.json Ty, we wszystkich projektach – np. powiadomienia
.claude/settings.json Cały zespół – commitowane z repozytorium (formatowanie, blokady)
.claude/settings.local.json Ty, tylko w tym projekcie, poza gitem
Plugin (hooks/hooks.json), skill lub subagent (frontmatter) Gdy plugin jest włączony / gdy skill lub subagent działa (artykuły 11 i 13)

Wszystkie skonfigurowane hooki, pogrupowane według zdarzeń, przejrzysz komendą /hooks. Zmiany w plikach ustawień Claude Code wczytuje w trakcie sesji, bez restartu. Nie musisz też pisać konfiguracji ręcznie – możesz opisać, czego chcesz, a agent sam przygotuje hook (pomaga w tym wbudowany skill /update-config).

Anatomia hooka

Najprostszy hook: po każdej edycji pliku dopisz jego ścieżkę do logu. Tak wygląda konfiguracja:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' >> ~/.claude/edited-files.log"
          }
        ]
      }
    ]
  }
}

Trzy elementy, które musisz znać

  • Matcher – filtr, np. nazwa narzędzia (Bash, Edit|Write, mcp__github__.*). Pusty matcher oznacza „zawsze”.
  • Wejście na stdin – Claude Code przekazuje skryptowi JSON z danymi zdarzenia: m.in. session_id, cwd, hook_event_name, a przy narzędziach tool_name i tool_input (dla Bash pole command, dla edycji file_path).
  • Wyjście – kod wyjścia i/lub JSON na stdout mówią Claude Code, co dalej.
Wynik hooka Co się dzieje
exit 0 Brak sprzeciwu – akcja idzie dalej zwykłą ścieżką uprawnień (exit 0 niczego nie zatwierdza)
exit 2 Blokada – treść ze stderr trafia do agenta jako wyjaśnienie, żeby mógł zmienić podejście
exit 0 + JSON Precyzyjna decyzja, np. w PreToolUse: permissionDecision = deny, ask lub allow z uzasadnieniem
inny kod wyjścia Błąd hooka, który zwykle nie blokuje akcji – zobaczysz go w transkrypcie
🔍 Hooki a uprawnienia

Decyzja deny z hooka obowiązuje w każdym trybie uprawnień – także w auto mode i bypassPermissions. W drugą stronę to nie działa: hook nie poluzuje ograniczeń ustawionych regułami deny i ask w settings.json. Gdy kilka hooków odpowiada na to samo zdarzenie, wszystkie się wykonują, a wygrywa najbardziej restrykcyjna decyzja.

⚠️ Przykłady w bashu, a Windows

Przykłady poniżej (jak w dokumentacji Claude Code) są pisane w bashu i używają jq do czytania JSON-a. Na Windows działają, gdy masz Git for Windows (Git Bash) i zainstalujesz jq (np. winget install jqlang.jq). Jeśli wolisz PowerShella, zapisz logikę w pliku .ps1 i wywołaj go w hooku jako pwsh -NoProfile -File .claude/hooks/nazwa.ps1 – JSON ze stdin odczytasz przez $input | ConvertFrom-Json. Przykład w PowerShellu pokazuję w sekcji o formatowaniu.

Przykład 1: powiadomienia, gdy agent czeka

Zdarzenie Notification odpala się, gdy Claude Code czeka na Twoją zgodę albo gdy agent skończył i od dłuższej chwili nic nie piszesz. Idealne, gdy w tle pracuje długie zadanie, a Ty robisz coś innego. Ten hook dodaj do ~/.claude/settings.json – dotyczy Ciebie, nie projektu.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code czeka na Ciebie', 'Claude Code')\""
          }
        ]
      }
    ]
  }
}

Na macOS w miejsce komendy wstaw osascript -e 'display notification "Claude Code czeka na Ciebie" with title "Claude Code"', a na Linuksie notify-send 'Claude Code' 'Claude Code czeka na Ciebie'. Chcesz powiadomienie na telefonie? Wystarczy curl -s -d 'Claude Code czeka na Ciebie' https://ntfy.sh/twoj-prywatny-kanal.

🔍 Tylko wybrane powiadomienia

Pusty matcher łapie wszystkie typy powiadomień. Żeby reagować tylko na prośby o zgodę, ustaw "matcher": "permission_prompt"; tylko na bezczynność po zakończeniu pracy – "idle_prompt".

Przykład 2: formatowanie po każdej edycji

Najpopularniejszy hook w ogóle: po każdej edycji pliku uruchom formatter. Agent nie musi pamiętać o dotnet format ani o Prettierze – kod zawsze trafia na dysk w stylu projektu. Ten hook idzie do .claude/settings.json, bo dotyczy całego zespołu.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format.sh"
          }
        ]
      }
    ]
  }
}
#!/bin/bash
# .claude/hooks/format.sh – formatuje plik, który właśnie zmienił agent
FILE=$(jq -r '.tool_input.file_path // empty')
[ -z "$FILE" ] && exit 0

case "$FILE" in
  *.cs)
    dotnet format "$CLAUDE_PROJECT_DIR/src/DevPulse.sln" --include "$FILE" --verbosity quiet
    ;;
  *.ts|*.tsx)
    (cd "$CLAUDE_PROJECT_DIR/frontend" && npx prettier --write "$FILE")
    ;;
esac

exit 0   # formatowanie nie blokuje pracy agenta, nawet gdy się nie powiedzie
# Na macOS i Linuksie skrypt musi mieć prawo wykonania:
chmod +x .claude/hooks/format.sh

Ten sam hook w PowerShellu

# .claude/hooks/format.ps1
$data = $input | ConvertFrom-Json
$file = $data.tool_input.file_path
if (-not $file) { exit 0 }

$root = $env:CLAUDE_PROJECT_DIR
switch -Wildcard ($file) {
    "*.cs"  { dotnet format "$root/src/DevPulse.sln" --include $file --verbosity quiet }
    "*.ts"  { Push-Location "$root/frontend"; npx prettier --write $file; Pop-Location }
    "*.tsx" { Push-Location "$root/frontend"; npx prettier --write $file; Pop-Location }
}
exit 0

# W settings.json:
# "command": "pwsh -NoProfile -File .claude/hooks/format.ps1"
⚠️ dotnet format nie jest błyskawiczny

Na większym rozwiązaniu dotnet format potrafi trwać kilka sekund, a hook uruchamia się po każdej edycji. Jeśli to przeszkadza, przenieś formatowanie C# do hooka Stop (raz, gdy agent kończy odpowiedź) albo formatuj tylko pliki zmienione względem HEAD.

Przykłady 3 i 4: blokady plików i komend

Przykład 3: edycja migracji – nowe tak, istniejące nie

Reguła deny z artykułu 08 blokuje ścieżkę na sztywno. Ale co, jeśli agent może tworzyć nowe migracje EF Core, a nie może edytować tych, które już są w repozytorium? Taka logika to zadanie dla hooka PreToolUse:

#!/bin/bash
# .claude/hooks/protect-files.sh
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
FILE="${FILE//\\//}"   # ścieżki z Windows: backslash → slash
[ -z "$FILE" ] && exit 0

# 1. Konfiguracja produkcyjna i sekrety – nigdy
case "$FILE" in
  *appsettings.Production.json|*/.env|*/.env.*)
    echo "Blocked: $FILE to plik produkcyjny lub sekret. Poproś użytkownika o ręczną zmianę." >&2
    exit 2 ;;
esac

# 2. Migracje EF Core – tylko nowe pliki; istniejące (śledzone przez gita) są nietykalne
if [[ "$FILE" == */Migrations/* ]] && git -C "$CLAUDE_PROJECT_DIR" ls-files --error-unmatch "$FILE" >/dev/null 2>&1; then
  echo "Blocked: $FILE to istniejąca migracja. Zamiast edytować, utwórz nową migrację." >&2
  exit 2
fi

exit 0
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh" }
        ]
      }
    ]
  }
}

Gdy agent spróbuje zmienić istniejącą migrację, Claude Code zablokuje edycję, a treść ze stderr („to istniejąca migracja, utwórz nową”) trafi do agenta – więc zamiast utknąć, zmieni podejście.

Przykład 4: komendy, które zawsze wymagają Twojej decyzji

Hook może też zamiast blokady wymusić pytanie o zgodę – nawet w auto mode. Przykład: każda komenda dotnet ef database update i każdy git push do main wymaga Twojego potwierdzenia:

#!/bin/bash
# .claude/hooks/guard-commands.sh
CMD=$(jq -r '.tool_input.command // empty')

if echo "$CMD" | grep -Eq 'dotnet ef database update|git push.*\bmain\b'; then
  jq -n '{hookSpecificOutput: {
    hookEventName: "PreToolUse",
    permissionDecision: "ask",
    permissionDecisionReason: "Zmiana bazy danych lub push do main – wymaga decyzji człowieka."
  }}'
  exit 0
fi

exit 0

Zarejestruj go w PreToolUse z matcherem Bash. Zamiast "ask" możesz zwrócić "deny" – wtedy akcja zostanie odrzucona, a uzasadnienie trafi do agenta.

🔍 Reguła deny czy hook?

Jeśli da się to opisać wzorcem (konkretny plik, komenda zaczynająca się od…) – użyj reguły w settings.json: jest prostsza, szybsza i widoczna w /permissions. Hook wybierz, gdy potrzebujesz logiki: stanu gita, zawartości pliku, godziny, nazwy brancha, zapytania do zewnętrznego systemu.

Przykład 5: testy przed końcem pracy

Hook Stop uruchamia się za każdym razem, gdy agent kończy odpowiedź. Jeśli zablokuje zakończenie (exit 2), treść ze stderr wraca do agenta jako kolejne polecenie – agent pracuje dalej. Dzięki temu możesz wymusić zasadę „nie kończysz, dopóki testy jednostkowe są czerwone”:

#!/bin/bash
# .claude/hooks/require-green-tests.sh
INPUT=$(cat)

# Zabezpieczenie przed pętlą: jeśli agent już raz był zatrzymany przez ten hook, odpuść
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active // false')" = "true" ]; then
  exit 0
fi

cd "$CLAUDE_PROJECT_DIR"

# Testy tylko wtedy, gdy w tej sesji zmienił się kod C#
if git diff --quiet HEAD -- '*.cs'; then
  exit 0
fi

if ! OUTPUT=$(dotnet test ./tests/DevPulse.Tests --filter Category=Unit 2>&1); then
  echo "Testy jednostkowe nie przechodzą. Napraw je przed zakończeniem pracy:" >&2
  echo "$OUTPUT" | tail -40 >&2
  exit 2
fi

exit 0
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/require-green-tests.sh", "timeout": 300 }
        ]
      }
    ]
  }
}
⚠️ Stop to nie „koniec zadania”

Hook Stop odpala się po każdej odpowiedzi agenta – także po krótkiej odpowiedzi na pytanie. Dlatego warunek „czy zmienił się kod” i zabezpieczenie przed pętlą są obowiązkowe, a dla wolnych testów ustaw rozsądny timeout (w sekundach). Bez tego hook potrafi zablokować każdą rozmowę.

Hooki oparte na modelu

Poza hookami typu command Claude Code ma też hooki, w których decyzję podejmuje model: "type": "prompt" (jedno zapytanie do modelu, np. „czy wszystkie zadania z polecenia są skończone?”) i eksperymentalny "type": "agent" (subagent, który może czytać pliki i uruchamiać komendy, zanim zdecyduje). Są też hooki http, które wysyłają dane zdarzenia na Twój endpoint – np. do wspólnego audytu dla zespołu. Na start trzymaj się hooków command: są deterministyczne i najłatwiej je debugować.

Przykład 6: kontekst, który przetrwa streszczenie

Gdy kontekst się zapełnia, Claude Code streszcza rozmowę – i drobne, ale ważne ustalenia mogą zniknąć. Hook SessionStart z matcherem compact uruchamia się po każdym streszczeniu, a tekst wypisany na stdout trafia do kontekstu agenta:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"Przypomnienie: branch $(git branch --show-current). Nie modyfikuj Program.cs bez pytania. Przed końcem pracy uruchom testy jednostkowe.\""
          }
        ]
      }
    ]
  }
}
Bezpieczeństwo i debugowanie

  • Hook to kod z Twoimi uprawnieniami – uruchamia się automatycznie, bez pytania. Hooki z .claude/settings.json sklonowanego repozytorium działają dopiero po zaufaniu folderowi (workspace trust) – w cudzym repo najpierw przejrzyj .claude/settings.json i katalog .claude/hooks/.
  • Ścieżki przez $CLAUDE_PROJECT_DIR – hook może się uruchomić w podkatalogu; ta zmienna zawsze wskazuje katalog główny projektu.
  • Szybkie hooki – hook blokuje pracę agenta na czas swojego działania. Domyślny limit to 10 minut dla hooków command; ustawiaj własny timeout tam, gdzie wiesz, ile coś trwa.
  • Wyłącznik awaryjny – "disableAllHooks": true w ustawieniach wyłącza hooki (poza tymi z ustawień zarządzanych przez organizację).
  • Debugowanie – /hooks pokazuje, co jest skonfigurowane; Ctrl+O pokazuje szczegóły w transkrypcie; claude --debug=hooks zapisuje szczegółowy log dopasowań, kodów wyjścia i outputu hooków.
Hooki w DevPulse

Złóżmy wszystko w jeden plik. Tak wygląda .claude/settings.json projektu DevPulse z regułami uprawnień z artykułu 08 i hookami z tego artykułu (powiadomienia trzymaj w swoim ~/.claude/settings.json):

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(dotnet build *)",
      "Bash(dotnet test *)",
      "Bash(npm run lint)",
      "Bash(npm test *)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Bash(git push --force *)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh" }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/guard-commands.sh" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format.sh" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/require-green-tests.sh", "timeout": 300 }
        ]
      }
    ]
  }
}
.claude/
├── settings.json                  ← uprawnienia + hooki (commitowane)
└── hooks/
    ├── protect-files.sh           ← PreToolUse: konfiguracja produkcyjna, sekrety, istniejące migracje
    ├── guard-commands.sh          ← PreToolUse: ask dla database update i push do main
    ├── format.sh                  ← PostToolUse: dotnet format / prettier
    └── require-green-tests.sh     ← Stop: zielone testy jednostkowe przed końcem pracy

git add .claude/settings.json .claude/hooks/
git commit -m "chore(claude): add team hooks for formatting, file protection and tests"
🌟 Co zmienia ten zestaw w codziennej pracy

Przestajesz pisać w poleceniach „i pamiętaj o formatowaniu”, „nie ruszaj migracji”, „uruchom testy na koniec”. Te zasady przeniosły się z CLAUDE.md (prośba) do hooków (gwarancja) – działają tak samo w trybie Manual, w auto mode, w subagentach i w każdej z równoległych sesji z poprzedniego artykułu. CLAUDE.md zostaje miejscem na to, czego nie da się sprawdzić skryptem: architekturę, konwencje, kontekst biznesowy.

Podsumowanie

Hooki zamieniają dobre intencje w gwarancje. Kluczowe wnioski:

  • Trzy warstwy kontroli – CLAUDE.md (instrukcja), reguły allow/ask/deny (wzorce), hooki (logika); każda kolejna jest twardsza
  • Zdarzenia – PreToolUse może blokować, PostToolUse sprząta po edycji, Stop pilnuje końca pracy, Notification informuje, SessionStart dokłada kontekst
  • Komunikacja – JSON na stdin; exit 0 = brak sprzeciwu, exit 2 = blokada z wyjaśnieniem dla agenta, JSON na stdout = precyzyjna decyzja
  • Konfiguracja zespołowa – hooki w .claude/settings.json i skrypty w .claude/hooks/ commitujesz razem z kodem; osobiste (powiadomienia) w ~/.claude/settings.json
  • Ostrożnie z Stop – odpala się po każdej odpowiedzi; zawsze warunek, zabezpieczenie przed pętlą i timeout
  • Bezpieczeństwo – hook to kod z Twoimi uprawnieniami; w cudzych repozytoriach przejrzyj .claude/, zanim zaufasz folderowi

W następnym artykule kończymy Fazę 3: własne komendy, skille i pluginy – zamkniemy powtarzalne procedury DevPulse w komendach takich jak /devpulse-review i /new-endpoint, a potem spakujemy komendy, subagentów i hooki z tego artykułu w plugin, który cały zespół zainstaluje jedną komendą.

Do zobaczenia w artykule 13! 🚀