Co jsou hooky v Claude Code?

• Události. Reference jich uvádí přes třicet, od SessionStart a UserPromptSubmit po PreToolUse, PostToolUse a Stop. Když chcete vynutit pravidlo, začněte u PreToolUse, protože běží před voláním nástroje a může ho zablokovat.
• Matchery. U událostí, které se týkají nástrojů, se matcher porovnává s názvem nástroje: Bash, Edit|Write nebo regulární výraz jako mcp__.* pro všechny MCP nástroje.
• Handlery. Reference popisuje pět typů: shellový příkaz, HTTP endpoint, volání MCP nástroje, jednokolový prompt pro model Claude a experimentální agentní hook, který si před rozhodnutím může přečíst soubory. Všechny hooky našich agentů jsou příkazy.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "bash \"${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-push.sh\"", "timeout": 5 }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# Přečte volání nástroje ze stdin a odmítne push, který uvádí main.
cmd="$(jq -r '.tool_input.command // empty')"
if grep -Eq 'git[[:space:]]+push.*[[:space:]](main|master)([[:space:]]|$)' <<< "$cmd"; then
  echo "Push do větve main tu není povolený. Místo toho otevřete pull request." >&2
  exit 2
fi
exit 0

• Pravidla platí, i když se nikdo nedívá. Instrukce je jen žádost. Hook na PreToolUse, který skončí kódem 2, je rozhodnutí, které model žádnou argumentací neobejde. Nejvíc na tom záleží u dlouhých běhů bez dozoru, kde jednotlivé kroky nikdo nečte.
• Rutina přestane záviset na paměti. Hook může po každé úpravě naformátovat soubor, spustit linter, při startu session doplnit kontext nebo zalogovat každé volání nástroje. Několik takových příkladů ukazuje průvodce hooky od Anthropicu. Hook to udělá pokaždé, ne jen tehdy, když si model vzpomene.
• Pravidla jsou na jednom místě. Hook v projektovém .claude/settings.json nebo v pluginu se sdílí spolu s kódem. Celý tým i každý agent, který v repozitáři pracuje, dostane stejné pravidlo ze stejného souboru.

• Ve výchozím nastavení blokuje jen exit 2. Návratový kód 1, v Unixu obvyklý signál selhání, znamená neblokující chybu a akce proběhne. Reference to říká bez obalu: pokud má hook vynucovat pravidlo, použijte exit 2. Hlídač se špatnou cestou nebo se skriptem, který spadne, propustí všechno. Od Claude Code v2.1.295 můžete hooku nastavit "onFailure": "block" a akce se pak zablokuje. Pokryje to i skript, který se vůbec nespustí, což exit 2 uvnitř skriptu nezvládne.
• Při timeoutu volání projde. Výchozí timeout příkazového hooku je 600 sekund. Hook na PreToolUse, kterému vyprší čas, volání nástroje nezablokuje, pokud nemá onFailure nastavené na blokování. Hlídače proto pište tak, aby doběhly rychle, a timeout nastavujte explicitně. Naše hlídače běží s limity 5 až 20 sekund.
• Hooky běží s vašimi oprávněními. Anthropic sám varuje, že příkazové hooky „spouštějí shellové příkazy s plnými oprávněními vašeho uživatelského účtu“ (přeloženo z angličtiny). Claude Code v interaktivní session hooky nespustí, dokud složku neoznačíte jako důvěryhodnou. V session spuštěné přes claude -p nebo SDK ji naopak považuje za důvěryhodnou, takže hooky commitnuté v cizím repozitáři poběží bez dotazu. Než nad nějakým repozitářem spustíte Claude Code ze skriptu, projděte nastavení v jeho .claude/.
• Hook vidí volání, ne jeho účinek. Hlídač čte jen text příkazu a kontext, který dostane. Náš hlídač pushů rozhoduje o samotném git push bez argumentů podle větve, která je přepnutá v pracovním adresáři shellu. Naši agenti proto vždy uvádějí remote i větev. Pravidlo, které pracuje s textem, musí vědět, jaký text uvidí. Navíc ho porovnává doslova. Heslo o sandboxu pro AI agenta popisuje běh, který náš hlídač odmítl, protože se zakázaný příkaz objevil jen jako text v uvozovkách.
• Hook není bezpečnostní hranice. Hlavička našeho hlídače komentářů to říká na jednom řádku: „Hlídač nad vlastními voláními modelu, ne bezpečnostní hranice“ (přeloženo z angličtiny). Skripty, které běží mimo volání nástrojů modelu, přes něj nikdy neprojdou. Pokud chcete omezit, kam až proces dosáhne, použijte sandbox a přístupové údaje s omezeným rozsahem. Hooky slouží k tomu, aby se agent držel dohodnutých mantinelů. Doplňují AI guardrails a revizi s člověkem ve smyčce.

• Co je AGENTS.md? – soubor s instrukcemi, které hook dokáže vynutit, ne jen vyslovit.
• Co jsou AI agent skills? – postupy, které si agent načte podle potřeby a které mohou deklarovat vlastní hooky.
• Co je sandbox pro AI agenta? – hranice za běhu, která omezuje, kam až příkaz dosáhne, zatímco hook rozhoduje jen o tom, jestli se vůbec spustí.
• Co jsou AI guardrails? – širší rodina kontrol, do které hooky patří.
• Co je prompt injection? – útok, který obrátí instrukce agenta proti vám, a proč proti němu pomáhá pravidlo mimo model.
• Jak vyladit GitHub Copilota, když vám firma zakáže MCP – vlastní hooky GitHub Copilota, které se konfigurují v .github/hooks/.