SSD Nodes Learn Hosting plans →
Przewodniki Matt ConnorAutor: Matt Connor

Jak działają hooki w Claude Code: przewodnik techniczny

Analiza mechanizmu działania hooków w Claude Code. Wyjaśnienie obsługi zdarzeń, roli kodu wyjścia 2 w PreToolUse oraz wpływu automatycznych skryptów na bezpieczeństwo pracy.

Czym jest hook Claude Code

Hooki Claude Code to polecenia powłoki, które Claude Code wykonuje samodzielnie w określonych punktach swojego cyklu życia. Na tym polega zasadnicza różnica między hookiem a plikiem reguł. Instrukcja w CLAUDE.md jest poradą, a model rozważa ją w kontekście wszystkich pozostałych wytycznych. Hook jest kodem i wykonuje się niezależnie od tego, czy model się z nim zgadza, czy nie. Jeśli agent stale pomija formater, o którym wspomniano dwukrotnie, nie potrzeba bardziej stanowczej instrukcji. Potrzebny jest hook.

Mechanizm ten jest prosty. W pliku ustawień rejestruje się polecenie pod nazwą zdarzenia. Gdy zdarzenie wystąpi, Claude Code uruchamia polecenie i zapisuje dane zdarzenia do standardowego wejścia (stdin) w formacie JSON (JavaScript object notation). Polecenie odczytuje te dane, wykonuje zadanie i zwraca status wyjścia. Status 2 z hooka PreToolUse anuluje wywołanie narzędzia przed jego uruchomieniem, a treść zapisana przez skrypt do standardowego wyjścia błędów (stderr) jest przekazywana modelowi jako uzasadnienie, chyba że hook wypisze również JSON zawierający decyzję o blokadzie, której uzasadnienie ma pierwszeństwo.

Nazwy zdarzeń i pól pochodzą z dokumentacji hooków Claude Code, zweryfikowanej 12 listopada 2026 r. Obszar ten zmienia się dynamicznie, dlatego przed skopiowaniem kodu JSON z jakiegokolwiek wpisu na blogu, w tym niniejszego, należy sprawdzić dokumentację dla własnej wersji. Własne ustawienia można wyświetlić za pomocą claude --version.

Gdzie znajduje się konfiguracja hooków

Hook to blok JSON w pliku ustawień. Może znajdować się w jednej z sześciu lokalizacji, a zakres pliku określa zakres działania hooka.

  • ~/.claude/settings.json: wszystkie projekty na danym komputerze i na żadnym innym.
  • .claude/settings.json: jeden projekt, zapisany w repozytorium, dzięki czemu każdy, kto je sklonuje, otrzyma ten hook.
  • .claude/settings.local.json: jeden projekt, tylko na danym komputerze.
  • Ustawienia zarządzanej polityki: obowiązujące w całej organizacji i konfigurowane przez administratora.
  • hooks/hooks.json wewnątrz pluginu, aktywne, gdy ten plugin jest włączony.
  • Frontmatter skilla lub subagenta. Hooki skilla pozostają aktywne do końca sesji po wywołaniu skilla, a hooki subagenta są aktywne podczas działania tego subagenta.

Wpisy hooków z tych plików są scalane, a nie wzajemnie zastępowane. Plik ustawień projektu dodaje swoje hooki do hooków z ustawień użytkownika, zamiast je zastępować. Dlatego jedno zdarzenie może zawierać kilka hooków z kilku plików. Ustawienie "disableAllHooks": true wyłącza te hooki, z jednym wyjątkiem: hooki z ustawień zarządzanej polityki nadal działają, chyba że to ustawienie zostanie zastosowane również w ustawieniach zarządzanych.

Uruchom /hooks w sesji, aby wyświetlić wszystkie aktualnie zarejestrowane hooki, pogrupowane według zdarzenia, wraz z plikiem źródłowym i matcherem każdego hooka. Menu jest tylko do odczytu, dlatego hooka należy zmieniać przez edycję pliku ustawień. Monitor zmian pliku zwykle wykrywa edycję bez konieczności ponownego uruchamiania.

Jakie zdarzenia hooków istnieją w Claude Code

Dokumentacja hooków wymienia trzydzieści trzy zdarzenia, od SessionStart do SessionEnd, obejmujące kompaktowanie, subagenty, drzewa robocze oraz pliki konfiguracyjne. W pracy serwerowej wykorzystuje się tylko część z nich.

  • PreToolUse: przed wykonaniem wywołania narzędzia, z wyjątkiem EndConversation. Jest to zdarzenie, które może blokować działanie.
  • PostToolUse: po pomyślnym zakończeniu wywołania narzędzia, z wyjątkiem EndConversation. PostToolUseFailure uruchamia się w przypadku niepowodzenia, więc hook wymagający monitorowania każdego wyniku musi obsługiwać oba te zdarzenia.
  • PermissionRequest: gdy wywołanie narzędzia wymaga decyzji o uprawnieniach; jest to moment, w którym pojawiłby się monit o zatwierdzenie.
  • UserPromptSubmit: po przesłaniu promptu, zanim Claude go przetworzy. Zwykły tekst stdout z pomyślnie wykonanego hooka jest dodawany do kontekstu modelu.
  • SessionStart oraz SessionEnd: na każdym z końców sesji. SessionStart uruchamia się również po kompaktowaniu, przy wartości dopasowania compact.
  • Stop: gdy Claude zakończy odpowiadanie. Dzieje się to raz na turę, a nie raz na ukończone zadanie.

W zdarzeniach obsługujących dopasowania (matchers), grupa może zawierać matcher, które decyduje o tym, które wystąpienia uruchomią hook. W przypadku zdarzeń narzędziowych filtrowanie odbywa się według nazwy narzędzia, więc "Edit|Write" uruchamia się tylko przy edycji plików. Dopasowania uwzględniają wielkość liter. Puste dopasowanie uruchamia hook przy każdym wystąpieniu. Narzędzia z serwera MCP (model context protocol) są nazywane mcp__<server>__<tool>, więc dopasowanie "mcp__github__.*" przechwytuje narzędzia jednego serwera, pozostawiając pozostałe bez zmian.

Hooki Stop zawierają pułapkę, o której warto wiedzieć przed przystąpieniem do pisania. Blokujący hook Stop odsyła model z powrotem do pracy, a domyślnie Claude Code nadpisuje kolejny blok po ośmiu kolejnych kontynuacjach, przy czym licznik resetuje się za każdym razem, gdy Claude wywołuje narzędzie. Należy odczytać pole stop_hook_active z danych wejściowych hooka i zakończyć działanie z kodem 0, gdy jest ono prawdziwe; w przeciwnym razie hook może w nieskończoność odsyłać Claude do pracy.

Dane wejściowe odbierane przez hook na stdin

Gdy Claude ma uruchomić npm test, hook PreToolUse na Bash odczytuje następujące dane ze standardowego wejścia (stdin):

{
  "session_id": "abc123",
  "cwd": "/home/deploy/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

Typowe pola wejściowe obejmują session_id, cwd, transcript_path oraz hook_event_name; pole permission_mode nie jest przesyłane przy każdym zdarzeniu. Zdarzenia narzędzi dodają tool_name, tool_input oraz tool_use_id. Inne zdarzenia zawierają własne pola: UserPromptSubmit otrzymuje tekst prompt, a SessionStart otrzymuje source typu startup, resume, clear, compact lub fork.

jq jest standardowym narzędziem do odczytu tych danych w skryptach powłoki, a minimalny obraz serwera go nie zawiera. Należy je zainstalować za pomocą sudo apt install -y jq w systemach Ubuntu i Debian.

Wpływ kodu wyjścia na wywołanie narzędzia w trakcie działania

Istnieją trzy możliwe rezultaty.

  • Kod wyjścia 0 oznacza sukces, a wszelkie poprawne pola decyzji JSON pozostają wiążące, w tym blokada lub odmowa. W przypadku PreToolUse, kod wyjścia 0 bez decyzji nie oznacza zatwierdzenia, a standardowy proces uprawnień jest kontynuowany. W przypadku UserPromptSubmit, UserPromptExpansion, SessionStart oraz PostModelSwitch, zwykły tekst ze stdout jest dodawany do kontekstu modelu. W większości pozostałych zdarzeń stdout trafia wyłącznie do dziennika debugowania.
  • Kod wyjścia 2 blokuje działanie w zdarzeniach, które można zablokować, w tym PreToolUse, a stderr staje się komunikatem towarzyszącym blokadzie, chyba że wyjście JSON zawiera decyzję o blokadzie, której uzasadnienie ma pierwszeństwo. Adresat tego komunikatu zależy od zdarzenia. W przypadku PreToolUse oraz Stop model interpretuje go jako powód. W przypadku UserPromptSubmit oraz PreModelSwitch komunikat jest wyświetlany użytkownikowi i nie jest dodawany do kontekstu modelu. W przypadku PostToolUse oraz PostToolUseFailure, których nie można zablokować, blokada jest ignorowana, chociaż stderr nadal dociera do modelu jako informacja zwrotna. W większości innych zdarzeń, których nie można zablokować, stderr jest wyświetlany tylko użytkownikowi lub ignorowany. W przypadku Stop, SubagentStop, TaskCompleted oraz hooka UserPromptSubmit wtyczki, kod wyjścia 2 z pustym stdout i błędem braku pliku na stderr jest traktowany jako błąd nieblokujący.
  • Każdy inny kod wyjścia ze zwykłym tekstem lub pustym stdout jest zazwyczaj błędem nieblokującym. Transkrypcja pokazuje powiadomienie o błędzie hooka zawierające pierwszą linię stderr po tekście Failed with non-blocking status code:. Poprawny format JSON nadal może decydować o wyniku w zdarzeniach takich jak PreToolUse, chyba że awaria hooka blokuje działanie. WorktreeCreate kończy się niepowodzeniem przy każdym niezerowym kodzie wyjścia, a WorktreeRemove kończy się niepowodzeniem przy niezerowym kodzie wyjścia, jeśli katalog nadal istnieje po zakończeniu działania.

W przypadku operacji wykraczających poza blokowanie lub brak reakcji, należy użyć kodu wyjścia 0 i wypisać obiekt JSON na stdout. Hook PreToolUse podejmuje decyzję za pomocą permissionDecision:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database drops go through a migration, not through the agent."
  }
}

"allow" pomija interaktywny monit, jeśli pozwalają na to reguły uprawnień i wymagania dotyczące zatwierdzania narzędzia, "deny" anuluje wywołanie i wysyła powód do modelu, a "ask" wymaga potwierdzenia. Należy wybrać jeden styl dla każdego hooka. Łączenie kodu wyjścia 2 z decyzją JSON na stdout utrzymuje blokadę, nawet jeśli JSON wskazuje na "allow".

Gdy kilka hooków pasuje do jednego zdarzenia, są one uruchamiane równolegle, przy czym liczba jednocześnie działających hooków typu prompt i agent jest ograniczona do dwunastu. deny z jednego hooka nie zatrzymuje pozostałych, więc hook logujący nadal zapisze swoją linię, nawet jeśli hook zabezpieczający odrzuci to samo wywołanie. W przypadku PreToolUse, Claude Code scala odpowiedzi i zachowuje najbardziej restrykcyjną, zgodnie z kolejnością: odmowa, odroczenie, zapytanie, zezwolenie.

Przykład 1: blokowanie niszczycielskiego polecenia przed jego wykonaniem

Zapisz to jako .claude/hooks/block-destructive.sh w swoim projekcie:

#!/bin/bash
# Deny a Bash tool call whose command matches a banned pattern.
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

for pattern in 'rm -rf /' 'mkfs' 'dd if=' 'DROP TABLE'; do
  if printf '%s' "$COMMAND" | grep -qiF -- "$pattern"; then
    echo "Blocked by policy: the command matches '$pattern'. A human runs this one." >&2
    exit 2
  fi
done

exit 0

Nadaj uprawnienia do wykonywania, a następnie zarejestruj skrypt w PreToolUse w .claude/settings.json:

chmod +x .claude/hooks/block-destructive.sh
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-destructive.sh",
            "timeout": 10,
            "statusMessage": "Checking the command against policy"
          }
        ]
      }
    ]
  }
}

Przetestuj skrypt ręcznie, zanim zaczniesz mu ufać, ponieważ hook, który zawodzi przy własnych danych wejściowych, zazwyczaj domyślnie zezwala na działanie, gdy onFailure nie jest ustawione. W systemie Windows bez Git Bash, nieudane polecenie typu shell-form PreToolUse lub PermissionRequest może zamiast tego zablokować wywołanie narzędzia:

echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /var/lib/postgresql"}}' \
  | .claude/hooks/block-destructive.sh
echo $?

Powinieneś zobaczyć linię Blocked by policy: na stderr oraz kod wyjścia 2. Podaj nieszkodliwe polecenie, takie jak ls -la; nie powinieneś zobaczyć żadnego wyjścia, a kod wyjścia powinien wynosić 0. W sesji odrzucone wywołanie pojawia się w transkrypcie wraz z Twoją wiadomością jako powodem, a model odczytuje tę wiadomość i dostosowuje swoje działanie.

Jedna właściwość sprawia, że warto to robić: hooki PreToolUse uruchamiają się przed sprawdzeniem trybu uprawnień, w każdym trybie uprawnień, więc odmowa obowiązuje nawet w trybie bypassPermissions. To właśnie czyni hook użytecznym w połączeniu z trybem automatycznym Claude Code i jego ustawieniami uprawnień, gdzie monity są ograniczone, ale hook nadal działa.

Bądź szczery co do tego, czym jest to rozwiązanie. Dopasowywanie wzorców w ciągu polecenia to bariera zabezpieczająca przed nieostrożnością agenta, a nie granica przed agentem działającym w sposób przemyślany, ponieważ to samo polecenie można zapisać w formie, której Twój grep nigdy nie zobaczy. Twarde reguły powinny znajdować się w systemie uprawnień oraz na koncie, na którym uruchomiony jest proces.

Przykład 2: formatowanie i lintowanie po każdej edycji

PostToolUse z matcherem Edit|Write uruchamia się po zakończeniu działania jednego z tych narzędzi do edycji plików. Zapisz to jako .claude/hooks/after-edit.sh:

#!/bin/bash
# Format the edited file, then report lint failures back to the model.
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
[ -z "$FILE" ] && exit 0

case "$FILE" in
  *.py)
    ruff format "$FILE" >/dev/null 2>&1
    if ! ruff check "$FILE" >&2; then
      exit 2
    fi
    ;;
  *.sh)
    if ! shellcheck "$FILE" >&2; then
      exit 2
    fi
    ;;
esac

exit 0
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/after-edit.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Poproś Claude o dodanie źle sformatowanej funkcji do pliku Python, a następnie otwórz ten plik. Zostanie on automatycznie sformatowany. Jest to potwierdzenie, że hook zadziałał, ponieważ pomyślne wykonanie hooka nie generuje żadnych komunikatów w konwersacji.

Kod wyjścia 2 w tym miejscu nie cofa żadnych zmian. PostToolUse uruchamia się po wykonaniu narzędzia, więc edycja jest już zapisana na dysku. Kod wyjścia 2 sprawia, że wynik ruff check trafia do modelu jako informacja zwrotna, dzięki czemu model naprawia błąd, który właśnie wprowadził, zamiast przechodzić dalej. Na tym polega różnica między błędem lintowania wykrytym podczas commitowania a błędem naprawionym przez agenta w tej samej turze.

W tym przypadku istotne są dwa ograniczenia matcherów. Edit|Write nie widzi plików zmienionych przez polecenie powłoki, a Claude często zapisuje pliki poprzez Bash, co sprawia, że ta luka jest realna. Aby uzyskać pokrycie dla każdego wywołania, dopasuj również Bash i spraw, aby skrypt wyświetlał zmienione pliki za pomocą git status --porcelain. Aby uzyskać pokrycie raz na turę, umieść skanowanie w hooku Stop.

Przykład 3: rejestrowanie każdego wywołania narzędzia do celów audytu

Pusty dopasowywacz w PostToolUse uruchamia się przy każdym udanym wywołaniu narzędzia z wyjątkiem EndConversation. Przesyłanie rekordu do dziennika systemowego zamiast do pliku w katalogu domowym nie chroni go przed dostępem z poziomu powłoki agenta: dostęp zależy od uprawnień konta. Użytkownicy mogą odczytywać swoje prywatne dzienniki, a root oraz członkowie grup systemd-journal, adm lub wheel mogą odczytywać wszystkie pliki dziennika:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{time: now|todate, session: .session_id, cwd: .cwd, tool: .tool_name, input: .tool_input}' | logger -t claude-code -p local0.info"
          }
        ]
      }
    ]
  }
}

Odczytaj dane za pomocą journalctl -t claude-code -o cat | tail -n 5. Przy posiadaniu uprawnień do odczytu rekordów, powinna być widoczna jedna linia JSON na każde udane wywołanie narzędzia poza EndConversation, z najnowszymi wpisami na końcu. Jeśli nic się nie pojawia, sprawdź dostęp do dziennika oraz czy skrypt typu hook został uruchomiony; sekcja rozwiązywania problemów poniżej omawia działanie hooków.

Dodaj ten sam blok pod PostToolUseFailure, aby przechwytywać nieudane wywołania, ponieważ PostToolUse uruchamia się tylko w przypadku sukcesu, a nieudana komenda jest zazwyczaj tą istotną. Powodem użycia logger zamiast dopisywania do pliku w katalogu domowym jest kwestia własności: hook działa jako ten sam użytkownik co powłoka agenta, więc wszystko, do czego użytkownik może dopisywać, może również wyczyścić. Dziennik jest zapisywany przez systemd-journald; ochrona przed usunięciem nadal zależy od uprawnień konta agenta.

Czas wykonywania hooka

WykresDefault hook timeout in seconds, by hook type and event
Dane, na których opiera się ten wykres
[
  {
    "label": "command, http or mcp_tool hook",
    "default_timeout_seconds": 600
  },
  {
    "label": "agent hook",
    "default_timeout_seconds": 60
  },
  {
    "label": "prompt hook",
    "default_timeout_seconds": 30
  },
  {
    "label": "command, http or mcp_tool on UserPromptSubmit, PreModelSwitch or PostModelSwitch",
    "default_timeout_seconds": 30
  },
  {
    "label": "command, http or mcp_tool on MessageDisplay",
    "default_timeout_seconds": 10
  },
  {
    "label": "any hook on SessionEnd",
    "default_timeout_seconds": 1.5
  }
]

Domyślnie hook polecenia otrzymuje 600 sekund, co odpowiada dziesięciu minutom. Niektóre zdarzenia znacząco skracają ten czas. Hooki SessionEnd współdzielą budżet 1.5 sekundy, więc czyszczenie sesji musi przebiegać szybko. Ustawienie wyższej wartości timeout dla hooka w plikach konfiguracyjnych zwiększa ten współdzielony budżet do maksymalnie 60 sekund.

Synchroniczne polecenie, hook HTTP lub narzędzie MCP, które przekroczy limit czasu, zostaje anulowane i zazwyczaj nie podejmuje decyzji. W przypadku PreModelSwitch przekroczenie limitu czasu blokuje przełączenie. Dla mechanizmu kontrolnego PreToolUse przekroczenie limitu czasu zazwyczaj pozwala na kontynuację wywołania narzędzia w ramach standardowego przepływu uprawnień, z wyjątkiem systemu Windows w sytuacji, gdy onFailure nie jest ustawione. Z tego powodu skrypty kontrolne powinny być krótkie. Od wersji 2.1.295 można odwrócić to domyślne zachowanie dla hooka command lub http za pomocą "onFailure": "block", co powoduje, że przekroczenie limitu czasu, awaria lub nieoczekiwany kod wyjścia skutkują blokadą. Nie ma to jednak wpływu na Stop, SubagentStop, TaskCompleted, TeammateIdle ani hooki poleceń działające w tle. W przypadku zadań długotrwałych, na które nikt nie oczekuje, takich jak wysyłanie logów, należy ustawić "async": true, aby hook działał w tle bez wstrzymywania wywołania narzędzia.

Hooki, pliki reguł, umiejętności i serwery MCP

Cztery elementy są często ze sobą mylone, ponieważ każdy z nich zmienia sposób działania agenta. Tylko jeden z nich przestaje być sugestią.

Plik reguł (CLAUDE.md lub plik w .claude/rules/) to tekst ładowany do kontekstu modelu. Kształtuje on zachowanie, ale niczego nie wymusza. W obliczu długiej konwersacji, dużego diffa i nowego żądania użytkownika, pojedyncza linijka może zostać zignorowana. Jest to zwykły mechanizm stojący za agentami ignorującymi zapisane instrukcje.

Umiejętność (skill) to folder z instrukcjami i skryptami, które model ładuje, gdy uzna je za istotne. Ta ocena jest istotą umiejętności, ale stanowi też jej ograniczenie: decyzja nadal należy do modelu. Obie strony tego zagadnienia widać w umiejętności takiej jak Ponytail, która nakierowuje agenta na najmniejszą działającą zmianę, ponieważ kształtuje ona podejście do całego zadania w sposób, w jaki nie zrobiłby tego żaden hook, i dzieje się to tylko wtedy, gdy model zdecyduje się ją załadować.

Serwer MCP (model context protocol) dostarcza modelowi nowe narzędzia do wywołania. Rozszerza on zakres dostępnych dla agenta zasobów. Nie zmusza jednak agenta do korzystania z czegokolwiek i jest osobnym procesem, który należy obsługiwać, co stanowi odrębne zadanie: zobacz uruchamianie serwerów MCP na VPS.

Hook jest jedynym z tych czterech elementów, który uruchamia się bez decyzji modelu. Plików reguł używaj do preferencji, a umiejętności do procedur, których model powinien przestrzegać w odpowiednich sytuacjach. Hooka używaj do kroków, które muszą wystąpić za każdym razem, lub do rzeczy, które nigdy nie mogą się wydarzyć. Głębokie porównanie, w tym sytuacje, w których umiejętność przewyższa plik reguł, znajduje się w porównaniu umiejętności, MCP i plików reguł.

Wtyczka (plugin) to raczej sposób pakowania niż piąty mechanizm. Łączy ona hooki wraz z umiejętnościami w jedną instalowalną jednostkę, dzięki czemu zespół może dostarczać te same zabezpieczenia na każdą maszynę: zobacz jak działają wtyczki Claude Code.

Kwestie bezpieczeństwa na współdzielonym serwerze VPS

Hook to kod wyzwalany przez agenta, który działa z uprawnieniami użytkownika uruchamiającego Claude Code. Dziedziczy on uprawnienia do plików i środowisko tego użytkownika. Na laptopie jest to kwestia przepływu pracy. Na serwerze VPS, gdzie agent działa bez nadzoru, jest to kwestia bezpieczeństwa składająca się z czterech praktycznych aspektów.

Hook w repozytorium to kod, którego nie napisałeś. Plik .claude/settings.json jest zatwierdzany w repozytorium, więc sklonowanie go i rozpoczęcie sesji wewnątrz może zarejestrować hooki dołączone do repozytorium. W sesji interaktywnej Claude Code blokuje hooki projektowe za oknem dialogowym zaufania do obszaru roboczego dla danego folderu, co oznacza, że zaakceptowanie zaufania jest momentem decyzji o ich uruchomieniu. Najpierw należy zapoznać się z blokiem hooks. Sesja claude -p lub SDK, w której zazwyczaj działa agent bez nadzoru, nigdy nie wyświetla tego okna i traktuje folder jako zaufany, więc hooki repozytorium uruchamiają się bez pytania. Przed użyciem skryptów należy przejrzeć pliki .claude/ lub uruchomić sesję z flagą --settings '{"disableAllHooks": true}'.

Hook widzi pełne dane wejściowe narzędzia. Hook audytowy, który loguje tool_input, zapisuje każdy argument każdego polecenia do dziennika, w tym każdy token, który znalazł się w wierszu poleceń. Taki dziennik wymaga takiej samej ochrony jak sam sekret, co stanowi część szerszego problemu utrzymywania sekretów poza zasięgiem agenta AI.

Hook może zapisywać dane w kontekście modelu. Zwykły tekst stdout z pomyślnego hooka SessionStart lub UserPromptSubmit jest dodawany do konwersacji. Hook, który przesyła tekst z zewnątrz, systemu śledzenia zgłoszeń lub pliku dziennika, przekazuje modelowi niezaufany tekst, tak jakby został on wpisany przez użytkownika. Hook przekazujący notatkę z innej sesji Claude Code na tym samym serwerze VPS robi to samo, a dane wyjściowe jednego agenta nie są bardziej godne zaufania niż dane z systemu śledzenia zgłoszeń. Należy traktować stdout jako dane wejściowe, a nie jako dane wyjściowe.

Uprawnienia to realna kontrola. Agent powinien działać jako dedykowany użytkownik bez uprawnień, z dostępem tylko do niezbędnych reguł sudo. Warto stosować blokadę PreToolUse, jednak z założenia jest to mechanizm "najlepszego wysiłku": dokumentacja mówi to samo o filtrze if i zaleca korzystanie z systemowych uprawnień w przypadku konieczności wymuszenia twardej blokady. Reguły uprawnień i konto, na którym działa proces, to elementy, które zachowują skuteczność pod obciążeniem.

Jedna właściwość obowiązuje w każdym trybie uprawnień. Hooki PreToolUse uruchamiają się przed sprawdzeniem trybu uprawnień, więc hook zwracający deny blokuje narzędzie nawet w trybie bypassPermissions. Hooki mogą zaostrzać reguły uprawnień, ale nie mogą ich łagodzić. Wyjątkiem jest mod. Na maszynie bez zarządzanych ustawień i bez pliku managed-mcp.json, w sesji niebędącej zalogowaną przez /login do planu Team lub Enterprise, zainstalowany mod obsługujący tool.check może zatwierdzić wywołanie, które zablokował hook PreToolUse. W przypadku zarządzanych ustawień, pliku managed-mcp.json lub poświadczeń sesji /login w planie Team lub Enterprise, wywołanie zablokowane przez hook PreToolUse pozostaje domyślnie zablokowane, niezależnie od tego, z którego pliku ustawień pochodzi hook. Sesja działająca na kluczu API lub długotrwałym CLAUDE_CODE_OAUTH_TOKEN, co jest typowe dla wielu serwerów, jest liczona jako niezalogowana, nawet jeśli dane logowania są zapisane. Przed instalacją na serwerze należy sprawdzić, co mogą zmieniać mody Claude Code.

Dlaczego mój hook nie działa?

Należy postępować zgodnie z poniższą kolejnością. Każdy krok wskazuje na objaw, który faktycznie występuje.

  • Uruchom /hooks i sprawdź, czy hook pojawia się pod oczekiwanym zdarzeniem. Brak hooka w menu zazwyczaj oznacza błąd składni JSON w pliku ustawień, ponieważ przecinki na końcu listy oraz komentarze są niedozwolone, lub plik nie znajduje się w jednej z sześciu wymienionych powyżej lokalizacji.
  • Porównaj matcher z nazwą narzędzia. Matchery rozróżniają wielkość liter, więc "bash" nigdy nie dopasuje się do narzędzia Bash.
  • Uruchom skrypt ręcznie z przykładowymi danymi wejściowymi, zgodnie z przykładem 1 powyżej. Nieoczekiwany kod wyjścia oznacza błąd w skrypcie; sprawdź również jego stdout, ponieważ poprawny JSON może nadal dostarczać decyzję dla zdarzeń takich jak PreToolUse.
  • Powiadomienie o treści jq: command not found oznacza, że jq nie znajduje się na danej maszynie. Błąd command not found dla własnego skryptu oznacza, że ścieżka nie została rozwiązana, więc należy użyć ${CLAUDE_PROJECT_DIR} lub ścieżki bezwzględnej. Jeśli skrypt w ogóle się nie uruchamia, prawdopodobnie nie posiada uprawnień do wykonywania.
  • Hook wypisuje poprawny JSON, ale nic się nie dzieje. W systemach macOS i Linux hook w formie powłoki uruchamiany jest przez sh -c w nieinteraktywnej powłoce, jednak niektóre konfiguracje nadal wczytują profil użytkownika, na przykład gdy BASH_ENV wskazuje na ~/.bashrc. Jeśli ten profil wypisuje baner, zostaje on dołączony przed kodem JSON. Stdout nie zaczyna się już od {, więc Claude Code odczytuje całość jako zwykły tekst i ignoruje decyzję. Ponieważ hook zakończył się kodem 0, w transkrypcji nie widać błędu. W przypadku większości zdarzeń tekst ten trafia tylko do dziennika debugowania, natomiast przy UserPromptSubmit, UserPromptExpansion, SessionStart oraz PostModelSwitch jest on dodawany do kontekstu modelu, wliczając w to baner. Owiń wszelkie polecenia echo w swoim profilu tak, aby uruchamiały się tylko w powłokach interaktywnych.
  • Nadal występuje problem: rozpocznij sesję za pomocą claude --debug-file /tmp/claude.log i uruchom tail -f /tmp/claude.log w drugim terminalu. Dziennik debugowania rejestruje, które hooki zostały dopasowane, jaki kod wyjścia zwrócił każdy z nich oraz wszystko, co wypisały na stdout i stderr.

FAQ

Jaka jest różnica między hookiem Claude Code a instrukcją w CLAUDE.md?

Instrukcja CLAUDE.md to tekst w kontekście modelu, więc konkuruje o uwagę z konwersacją oraz bieżącym żądaniem, a model może ją ważyć w relacji do nich. Hook to polecenie powłoki, które Claude Code uruchamia w określonym punkcie cyklu życia, więc wykonuje się ono przy każdym wystąpieniu zdarzenia, niezależnie od decyzji modelu. Instrukcji należy używać do preferencji. Hooka należy używać do kroków, które muszą zawsze wystąpić, lub działań, które nigdy nie mogą mieć miejsca.

Jak uniemożliwić Claude Code uruchomienie konkretnego polecenia powłoki?

Zarejestruj hook PreToolUse z dopasowaniem Bash, które odczytuje polecenie z .tool_input.command, zapisuje powód w stderr i kończy działanie kodem 2. Claude Code anuluje wywołanie i wyświetla modelowi podany powód. Dzieje się to przed sprawdzeniem trybu uprawnień, więc blokada działa nawet w trybie bypassPermissions. Dopasowywanie wzorców w ciągu polecenia stanowi zabezpieczenie, a nie granicę bezpieczeństwa, ponieważ to samo polecenie można zapisać w formie, której wzorzec nie wychwyci. Należy zatem wspierać to regułami uprawnień oraz kontem o ograniczonych przywilejach.

Mój hook wypisuje poprawny JSON, ale nic się nie dzieje. Dlaczego?

Sprawdź profil powłoki pod kątem tekstu wypisywanego przed JSON-em. W systemach macOS i Linux hook bez pola args uruchamia się przez sh -c. W konfiguracjach, które nadal wczytują profil, takich jak BASH_ENV wskazujący na ~/.bashrc, profil wypisujący baner umieszcza go na stdout przed JSON-em. Ponieważ wyjście nie zaczyna się już od {, Claude Code traktuje całość jako zwykły tekst i ignoruje decyzję, a ponieważ hook zakończył się kodem 0, w transkrypcji nie widać błędu. Zabezpiecz wszelkie echo w profilu testem powłoki interaktywnej, a następnie potwierdź poprawkę, odczytując dziennik debugowania z claude --debug-file /tmp/claude.log.

Czy uruchamianie hooków Claude Code na współdzielonym serwerze jest bezpieczne?

Hooki działają jako użytkownik, który uruchomił Claude Code, z uprawnieniami plików tego użytkownika, więc hook może wykonać wszystko, co może to konto. Dwa nawyki pokrywają większość ryzyka: uruchamiaj agenta jako dedykowane konto o ograniczonych uprawnieniach z wąską polityką sudo oraz czytaj blok hooks każdego repozytorium przed zaakceptowaniem okna dialogowego zaufania do obszaru roboczego lub uruchomieniem w nim claude -p. Hooki projektowe są dostarczane wewnątrz .claude/settings.json, a tryb -p nigdy nie wyświetla tego okna dialogowego. Ustaw "disableAllHooks": true w pliku ustawień, aby wyłączyć hooki, z wyjątkiem hooków zarządzanych, które wymagają tego ustawienia na poziomie zarządzanym; ustawienie projektu false może nadpisać ustawienie użytkownika true.

Czy ten artykuł był przydatny?