SSD Nodes Learn Hosting plans →
Gidsen Matt ConnorDoor Matt Connor

Hoe werken Claude Code hooks?

Ontdek hoe Claude Code hooks shell-commando's afdwingen buiten de model-instructies om. Leer welke events er zijn, hoe exit code 2 tool-aanroepen blokkeert en wat de risico's zijn.

Wat een Claude Code hook is

Claude Code hooks zijn shell-commando's die Claude Code zelfstandig uitvoert op vaste punten in zijn eigen levenscyclus. Dat is het fundamentele verschil tussen een hook en een regels-bestand. Een instructie in CLAUDE.md is advies, en het model weegt dit af tegen alle andere informatie in de context. Een hook is code en wordt uitgevoerd, ongeacht of het model het ermee eens is of niet. Als uw agent de formatter die u twee keer heeft opgegeven blijft overslaan, heeft u geen strengere instructie nodig. U heeft een hook nodig.

Het mechanisme is eenvoudig. U registreert een commando in een instellingenbestand onder een eventnaam. Wanneer dat event wordt geactiveerd, voert Claude Code uw commando uit en schrijft de eventdata naar de standaardinvoer (stdin) als JSON (JavaScript object notation). Uw commando leest die data, voert de taak uit en antwoordt met een exit-status. Exit 2 van een PreToolUse hook annuleert de tool-aanroep voordat deze wordt uitgevoerd. Alles wat uw script naar de standaardfout (stderr) schrijft, wordt aan het model teruggegeven als reden, tenzij de hook ook JSON bevat met een blokkeringsbesluit, waarvan de reden voorrang krijgt.

Eventnamen en veldnamen in deze tekst zijn afkomstig uit de Claude Code hooks reference, gecontroleerd op 12 november 2026. Dit oppervlak verandert snel, dus controleer de referentie voor uw eigen versie voordat u JSON kopieert uit een blogpost, inclusief deze. Print de uwe met claude --version.

Locatie van hook-configuratie

Een hook is een JSON-blok in een instellingenbestand. Er zijn zes locaties waar deze kan staan, waarbij de scope van het bestand gelijk is aan de scope van de hook.

  • ~/.claude/settings.json: elk project op uw machine, en niet op die van anderen.
  • .claude/settings.json: één project, vastgelegd in de repository, zodat iedereen die het project kloont de hook ontvangt.
  • .claude/settings.local.json: één project, alleen op uw machine.
  • Beheerde beleidsinstellingen: organisatiebreed, ingesteld door een beheerder.
  • hooks/hooks.json binnen een plugin, actief zolang de plugin is ingeschakeld.
  • Frontmatter van een skill of subagent. De hooks van een skill blijven actief voor de rest van de sessie zodra de skill is aangeroepen; de hooks van een subagent zijn actief zolang die subagent draait.

Hook-vermeldingen uit deze bestanden worden samengevoegd in plaats van elkaar te overschrijven. Een projectinstellingenbestand voegt zijn hooks toe aan die in uw gebruikersinstellingen in plaats van ze te vervangen, waardoor één gebeurtenis meerdere hooks uit verschillende bestanden kan bevatten. De instelling "disableAllHooks": true schakelt ze uit, met één uitzondering: hooks uit beheerde beleidsinstellingen blijven actief, tenzij die instelling ook in de beheerde instellingen wordt toegepast.

Voer /hooks uit binnen een sessie om elke momenteel geregistreerde hook weer te geven, gegroepeerd per gebeurtenis, inclusief het bronbestand en de matcher voor elk. Het menu is alleen-lezen; u wijzigt een hook dus door het instellingenbestand te bewerken. De file watcher verwerkt de wijziging doorgaans zonder dat een herstart nodig is.

Welke Claude Code hook-events bestaan er

De hook-referentie bevat drieëndertig events, van SessionStart tot en met SessionEnd, die betrekking hebben op compactie, subagents, worktrees en configuratiebestanden. Serverwerk gebruikt er slechts een handvol.

  • PreToolUse: voordat een tool-aanroep wordt uitgevoerd, met uitzondering van EndConversation. Dit is het event dat acties kan blokkeren.
  • PostToolUse: nadat een tool-aanroep is geslaagd, met uitzondering van EndConversation. PostToolUseFailure wordt geactiveerd wanneer de aanroep faalt; een hook die elk resultaat moet zien, heeft dus beide nodig.
  • PermissionRequest: wanneer een tool-aanroep een toestemmingsbesluit vereist; dit is het moment waarop de goedkeuringsprompt zou verschijnen.
  • UserPromptSubmit: wanneer u een prompt indient, voordat Claude deze verwerkt. Plain-text stdout van een geslaagde hook wordt toegevoegd aan de context van het model.
  • SessionStart en SessionEnd: aan elk uiteinde van een sessie. SessionStart wordt ook geactiveerd na compactie, onder de matcher-waarde compact.
  • Stop: wanneer Claude klaar is met reageren. Dit gebeurt één keer per beurt, niet één keer per voltooide taak.

Bij events die matchers ondersteunen, kan een groep een matcher bevatten die bepaalt bij welke gebeurtenissen de hook wordt uitgevoerd. Bij tool-events filtert dit op toolnaam; zo wordt "Edit|Write" alleen geactiveerd bij bestandswijzigingen en verder nergens. Matchers zijn hoofdlettergevoelig. Een lege matcher wordt bij elke gebeurtenis geactiveerd. Tools van een MCP (model context protocol) server worden benoemd als mcp__<server>__<tool>, dus een matcher van "mcp__github__.*" vangt de tools van één specifieke server op en negeert de rest.

Stop-hooks bevatten een valkuil die u moet kennen voordat u er een schrijft. Een Stop-hook die blokkeert, stuurt het model terug naar het werk. Standaard overschrijdt Claude Code het volgende blok na acht opeenvolgende continuaties, waarbij de teller wordt gereset telkens wanneer Claude een tool aanroept. Lees het veld stop_hook_active uit de hook-input en sluit af met exit 0 wanneer dit true is, anders kan uw hook Claude blijven terugsturen naar het werk.

Wat een hook ontvangt via stdin

Wanneer Claude op het punt staat om npm test uit te voeren, leest een PreToolUse-hook op Bash het volgende via stdin:

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

De algemene invoervelden omvatten session_id, cwd, transcript_path en hook_event_name; permission_mode wordt niet bij elke gebeurtenis verzonden. De tool-events voegen tool_name, tool_input en tool_use_id toe. Andere gebeurtenissen bevatten hun eigen velden: UserPromptSubmit ontvangt de prompt-tekst, en SessionStart ontvangt een source van startup, resume, clear, compact of fork.

jq is de gebruikelijke manier om dit binnen een shell-script te lezen, en een minimale server-image bevat dit niet. Installeer het eerst met sudo apt install -y jq op Ubuntu en Debian.

Wat de exit-status doet met de lopende tool-aanroep

Er zijn drie mogelijke uitkomsten.

  • Exit 0 betekent succes. Alle geldige JSON-beslissingsvelden blijven van kracht, inclusief een blokkering of weigering. Bij PreToolUse is exit 0 zonder beslissing geen goedkeuring; de normale autorisatiestroom wordt dan gewoon uitgevoerd. Bij UserPromptSubmit, UserPromptExpansion, SessionStart en PostModelSwitch wordt platte tekst van stdout toegevoegd aan de context van het model. Bij de meeste andere gebeurtenissen gaat stdout alleen naar het debug-logboek.
  • Exit 2 blokkeert de actie bij gebeurtenissen die geblokkeerd kunnen worden, waaronder PreToolUse. De stderr-uitvoer wordt dan het bericht dat bij de blokkering hoort, tenzij de JSON-output een blokkeringsbeslissing bevat; de reden daarvan krijgt voorrang. Wie dat bericht leest, hangt af van de gebeurtenis. Bij PreToolUse en Stop ziet het model dit als de reden. Bij UserPromptSubmit en PreModelSwitch wordt het aan u getoond en niet toegevoegd aan de context van het model. Bij PostToolUse en PostToolUseFailure, die niet geblokkeerd kunnen worden, wordt de blokkering genegeerd, hoewel stderr het model nog steeds bereikt als feedback. Bij de meeste andere gebeurtenissen die niet geblokkeerd kunnen worden, wordt stderr alleen aan u getoond of genegeerd. Bij Stop, SubagentStop, TaskCompleted en de UserPromptSubmit-hook van een plugin wordt exit 2 met een lege stdout en een foutmelding over een ontbrekend bestand op stderr behandeld als een niet-blokkerende fout.
  • Elke andere exit-code met platte tekst of een lege stdout is doorgaans een niet-blokkerende fout. Het transcript toont een melding over een hook-fout met de eerste regel van stderr na de tekst Failed with non-blocking status code:. Geldige JSON kan nog steeds de uitkomst bepalen bij gebeurtenissen zoals PreToolUse, tenzij het falen van de hook de actie blokkeert. WorktreeCreate faalt bij elke exit-code die niet nul is, en WorktreeRemove faalt bij een exit-code die niet nul is als de directory daarna nog steeds bestaat.

Voor alles wat verder gaat dan blokkeren of niets doen, gebruikt u exit 0 en print u een JSON-object naar stdout. Een PreToolUse-hook beslist met permissionDecision:

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

"allow" slaat de interactieve prompt over waar autorisatieregels en de goedkeuringsvereisten van de tool dit toelaten, "deny" annuleert de aanroep en stuurt de reden naar het model, en "ask" vraagt om bevestiging. Kies één stijl per hook. Het combineren van exit 2 met een JSON-beslissing op stdout houdt de blokkering in stand, zelfs als de JSON "allow" aangeeft.

Wanneer meerdere hooks overeenkomen met één gebeurtenis, worden deze parallel uitgevoerd, waarbij prompt- en agent-hooks beperkt zijn tot twaalf gelijktijdige uitvoeringen. Een deny van de ene hook stopt de andere hooks niet; een logging-hook schrijft dus nog steeds zijn regel terwijl een guardrail-hook dezelfde aanroep weigert. Voor PreToolUse voegt Claude Code de antwoorden samen en hanteert de meest restrictieve, in de volgorde: weigeren, uitstellen, vragen, toestaan.

Voorbeeld 1: een destructief commando blokkeren voordat het wordt uitgevoerd

Sla dit op als .claude/hooks/block-destructive.sh in uw project:

#!/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

Maak het uitvoerbaar en registreer het vervolgens op PreToolUse in .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"
          }
        ]
      }
    ]
  }
}

Test het script handmatig voordat u het vertrouwt, omdat een hook die crasht op zijn eigen invoer normaal gesproken 'fail-open' is wanneer onFailure niet is ingesteld. Op Windows zonder Git Bash kan een falende shell-vormige PreToolUse of PermissionRequest commando-hook in plaats daarvan de tool-aanroep blokkeren:

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

U hoort de Blocked by policy:-regel op stderr te zien en een exit-code van 2. Voer een onschadelijk commando in, zoals ls -la, en u hoort geen uitvoer en een exit-code van 0 te zien. In een sessie verschijnt de geweigerde aanroep in het transcript met uw bericht als reden; het model leest dat bericht en past zich aan.

Eén eigenschap maakt dit de moeite waard: PreToolUse-hooks worden geactiveerd vóór de controle van de permissiemodus, in elke permissiemodus, dus een weigering blijft van kracht, zelfs onder bypassPermissions. Dat is wat een hook nuttig maakt naast Claude Code auto-modus en de bijbehorende permissie-instellingen, waar de prompts worden beperkt maar de hook nog steeds wordt geactiveerd.

Wees eerlijk over wat dit is. Patroonherkenning op een commandoreeks is een vangrail tegen een onvoorzichtige agent, en het is geen grens tegen een slimme agent, omdat hetzelfde commando kan worden geschreven in een vorm die uw grep nooit ziet. Harde regels horen thuis in het permissiesysteem en in het account waaronder het proces wordt uitgevoerd.

Voorbeeld 2: formatteren en linten na elke wijziging

PostToolUse met een Edit|Write matcher wordt uitgevoerd nadat een van deze tools voor het bewerken van bestanden succesvol is afgerond. Sla dit op als .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
          }
        ]
      }
    ]
  }
}

Vraag Claude om een slecht ingesprongen functie toe te voegen aan een Python-bestand en open vervolgens het bestand. Het wordt automatisch geformatteerd. Dat is uw controle dat de hook is uitgevoerd, aangezien een succesvolle hook niets toont in het gesprek.

De exit 2 hier maakt niets ongedaan. PostToolUse wordt geactiveerd nadat de tool al is uitgevoerd, dus de wijziging staat hoe dan ook op de schijf. Wat exit 2 u oplevert, is dat de ruff check-output het model bereikt als feedback, waardoor het de fout die het zojuist heeft geïntroduceerd herstelt in plaats van verder te gaan. Dat is het verschil tussen een lint-fout die u vindt tijdens het commit-proces en een fout die de agent in dezelfde beurt herstelt.

Twee matcher-limieten zijn hier van belang. Edit|Write ziet geen bestanden die zijn gewijzigd door een shell-commando, en Claude schrijft bestanden vaak genoeg via Bash om dat gat reëel te maken. Voor dekking per aanroep, match ook Bash en laat het script gewijzigde bestanden weergeven met git status --porcelain. Voor dekking per beurt, plaatst u de scan in een Stop-hook.

Voorbeeld 3: elke tool-aanroep loggen voor auditdoeleinden

Een lege matcher op PostToolUse wordt geactiveerd bij elke succesvolle tool-aanroep, behalve EndConversation. Het versturen van het record naar de system journal in plaats van naar een bestand in de home-directory zorgt er niet voor dat het buiten bereik van de eigen shell van de agent blijft: toegang is afhankelijk van de rechten van het account. Gebruikers kunnen hun eigen private journals lezen, en root en leden van systemd-journal, adm of wheel kunnen alle journal-bestanden inzien:

{
  "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"
          }
        ]
      }
    ]
  }
}

Lees het terug met journalctl -t claude-code -o cat | tail -n 5. Met de juiste rechten om de records te lezen, ziet u één JSON-regel per succesvolle tool-aanroep, behalve EndConversation, met de nieuwste onderaan. Als er niets verschijnt, controleer dan de journal-toegang en of de hook is uitgevoerd; de sectie over probleemoplossing hieronder behandelt de hook.

Voeg hetzelfde blok toe onder PostToolUseFailure om aanroepen vast te leggen die zijn mislukt, omdat PostToolUse alleen wordt geactiveerd bij succes en een mislukt commando doorgaans het meest interessant is. De reden voor logger in plaats van toevoegen aan een bestand in uw home-directory is eigenaarschap: een hook draait als dezelfde gebruiker als de shell van de agent, dus alles waaraan die gebruiker kan toevoegen, kan die gebruiker ook wissen. De journal wordt geschreven door systemd-journald; het beschermen ervan tegen verwijdering blijft afhankelijk van de privileges van het agent-account.

Hoe lang een hook mag draaien

GrafiekDefault hook timeout in seconds, by hook type and event
De gegevens achter deze grafiek
[
  {
    "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
  }
]

Een command hook krijgt standaard 600 seconden, wat gelijkstaat aan tien minuten. Sommige events beperken dit aanzienlijk. SessionEnd-hooks delen een budget van 1.5 seconden met elkaar; het opschonen aan het einde van een sessie moet dus snel gebeuren. Het instellen van een langere timeout voor een hook in uw configuratiebestanden verhoogt dit gedeelde budget tot maximaal 60 seconden.

Een synchrone command, HTTP of MCP tool hook die zijn time-out bereikt, wordt geannuleerd en levert normaal gesproken geen besluit op; bij PreModelSwitch blokkeert een time-out de switch. Bij een PreToolUse-guardrail zorgt een time-out er normaal gesproken voor dat de tool-aanroep doorgaat naar de normale autorisatiestroom, met de bovengenoemde uitzondering voor Windows wanneer onFailure niet is ingesteld. Houd guardrail-scripts om die reden kort. Sinds release 2.1.295 kunt u die standaardinstelling voor een command- of http-hook omkeren met "onFailure": "block". Dit verandert een time-out, een crash of een onverwachte exitcode in een blokkering, al heeft dit geen effect op Stop, SubagentStop, TaskCompleted, TeammateIdle of achtergrond-command hooks. Voor trage taken waar niemand op wacht, zoals het versturen van een logbestand, stelt u "async": true in; de hook draait dan op de achtergrond zonder de tool-aanroep op te houden.

Hooks, rules-bestanden, skills en MCP-servers

Vier zaken worden vaak met elkaar verward omdat ze alle vier het gedrag van een agent beïnvloeden. Slechts één daarvan is geen vrijblijvende suggestie.

Een rules-bestand (CLAUDE.md, of een bestand onder .claude/rules/) is tekst die in de context van het model wordt geladen. Het vormt het gedrag, maar dwingt niets af. In een lange conversatie, bij een grote diff en een nieuwe gebruikersaanvraag, kan één regel tekst verloren gaan. Dat is het gebruikelijke mechanisme achter agents die de instructies negeren die u heeft opgeschreven.

Een skill is een map met instructies en scripts die het model laadt wanneer het de skill relevant acht. Dat oordeel is het doel van een skill, maar ook de beperking: het model beslist nog steeds zelf. U ziet beide kanten in een skill zoals Ponytail, die een agent dwingt tot de kleinst mogelijke werkende wijziging, omdat het de aanpak van een volledige taak vormgeeft op een manier die geen enkele hook kan, en alleen zolang het model ervoor kiest deze te laden.

Een MCP (model context protocol) server geeft het model nieuwe tools om aan te roepen. Het verbreedt het bereik van de agent. Het dwingt de agent echter niet om ergens gebruik van te maken, en het is een afzonderlijk proces dat u moet beheren, wat een taak op zich is: zie het draaien van MCP-servers op een VPS.

Een hook is de enige van de vier die wordt uitgevoerd zonder dat het model daarvoor kiest. Gebruik een rules-bestand voor een voorkeur en een skill voor een procedure die het model moet volgen wanneer het deze toepast. Gebruik een hook voor de stap die elke keer moet plaatsvinden, of voor de actie die nooit mag gebeuren. De diepere vergelijking, inclusief wanneer een skill de voorkeur verdient boven een rules-bestand, vindt u in de vergelijking tussen skills, MCP en rules-bestanden.

Een plugin is eerder een verpakkingsvorm dan een vijfde mechanisme. Het bundelt hooks samen met skills in één installeerbare eenheid. Op die manier verspreidt een team dezelfde vangrail naar elke machine: zie hoe Claude Code plugins werken.

De beveiligingsbeslissing op een gedeelde VPS

Een hook is code die door de agent wordt geactiveerd en wordt uitgevoerd als de gebruiker die Claude Code heeft gestart. Het erft de bestandsrechten en omgeving van die gebruiker. Op een laptop is dit een workflow-vraagstuk. Op een VPS waar een agent onbeheerd draait, is het een beveiligingsvraagstuk met vier praktische onderdelen.

Een hook in een repository is code die u niet zelf heeft geschreven. .claude/settings.json wordt gecommit, dus het klonen van een repository en het starten van een sessie daarin kan hooks registreren die bij de repository horen. In een interactieve sessie schermt Claude Code project-hooks af achter het dialoogvenster voor werkruimtevertrouwen voor die map; het accepteren van vertrouwen is het moment waarop u besluit ze uit te voeren. Lees eerst het hooks-blok. Een claude -p- of SDK-sessie, de manier waarop een onbeheerde agent meestal draait, toont dat dialoogvenster nooit en behandelt de map als vertrouwd, waardoor de hooks van de repository zonder vragen worden uitgevoerd. Controleer de .claude/-bestanden voordat u er scripts tegenaan laat draaien, of voer uit met --settings '{"disableAllHooks": true}'.

Een hook ziet de volledige tool-invoer. Een audit-hook die tool_input logt, schrijft elk argument van elk commando naar een logbestand, inclusief elk token dat toevallig op een commandoregel stond. Dat logbestand vereist vervolgens dezelfde bescherming als het geheim zelf, wat onderdeel is van het bredere probleem van geheimen buiten het bereik van een AI-agent houden.

Een hook kan in de context van het model schrijven. Plat-tekst stdout van een succesvolle SessionStart- of UserPromptSubmit-hook wordt toegevoegd aan het gesprek. Een hook die tekst van buitenaf, een issue tracker of een logbestand pipe-t, voert onbetrouwbare tekst in bij het model alsof u het zelf heeft getypt. Een hook die een notitie doorstuurt van een andere Claude Code-sessie op dezelfde VPS doet hetzelfde, en de output van de ene agent is niet betrouwbaarder dan die van de issue tracker. Behandel die stdout als invoer in plaats van als uitvoer.

Privileges zijn de echte controle. Voer de agent uit als een toegewezen gebruiker zonder privileges met alleen de sudo-regels die nodig zijn. Een PreToolUse-deny is nuttig, maar is van nature een 'best effort'-maatregel: de referentie zegt hetzelfde over het if-filter en adviseert het permissiesysteem te gebruiken wanneer u een harde blokkade nodig heeft. De permissieregels en het account waaronder het proces draait, zijn de onderdelen die standhouden onder druk.

Eén eigenschap blijft behouden in elke permissiemodus. PreToolUse-hooks worden geactiveerd vóór de controle van de permissiemodus in elke permissiemodus, dus een hook die deny retourneert, blokkeert de tool zelfs onder bypassPermissions. Hooks kunnen de permissieregels aanscherpen. Ze kunnen deze niet versoepelen. De uitzondering is een mod. Op een machine zonder beheerde instellingen en zonder managed-mcp.json-bestand, in een sessie die niet is ingelogd via /login op een Team- of Enterprise-abonnement, kan een geïnstalleerde mod die tool.check afhandelt een aanroep goedkeuren die uw PreToolUse-hook heeft geblokkeerd. Met beheerde instellingen, een managed-mcp.json-bestand, of een Team- of Enterprise /login als sessie-referentie, blijft een aanroep die door een PreToolUse-hook is geblokkeerd standaard geblokkeerd, ongeacht uit welk instellingenbestand de hook komt. Een sessie die draait op een API-key of een langdurige CLAUDE_CODE_OAUTH_TOKEN, wat de manier is waarop veel servers het uitvoeren, telt als niet ingelogd, zelfs als er een login is opgeslagen. Controleer wat Claude Code mods kunnen wijzigen voordat u er een op een server installeert.

Waarom wordt mijn hook niet geactiveerd?

Doorloop deze stappen in de aangegeven volgorde. Elke stap benoemt het symptoom dat u zult waarnemen.

  • Voer /hooks uit en controleer of de hook verschijnt onder de verwachte gebeurtenis. Als een hook ontbreekt in het menu, duidt dit meestal op een JSON-syntaxfout in het instellingenbestand, aangezien extra komma's en commentaar niet zijn toegestaan, of het bestand bevindt zich niet op een van de zes bovengenoemde locaties.
  • Vergelijk de matcher exact met de naam van de tool. Matchers zijn hoofdlettergevoelig; "bash" komt dus nooit overeen met de tool Bash.
  • Voer het script handmatig uit met voorbeeldinvoer, zoals in voorbeeld 1 hierboven. Een onverwachte exitcode wijst op een bug in uw script; controleer ook de stdout, aangezien geldige JSON nog steeds een beslissing kan opleveren voor gebeurtenissen zoals PreToolUse.
  • Een melding met de tekst jq: command not found betekent dat jq ontbreekt op die machine. Een command not found voor uw eigen script betekent dat het pad niet kon worden opgelost; gebruik daarom ${CLAUDE_PROJECT_DIR} of een absoluut pad. Als het script helemaal niet wordt uitgevoerd, is het waarschijnlijk niet uitvoerbaar.
  • De hook print geldige JSON, maar er gebeurt niets. Op macOS en Linux wordt een shell-hook uitgevoerd via sh -c in een niet-interactieve shell, maar sommige configuraties laden alsnog uw profiel, zoals BASH_ENV dat verwijst naar ~/.bashrc. Als dat profiel een banner print, wordt deze banner vóór uw JSON geplaatst. De stdout begint dan niet langer met {, waardoor Claude Code de gehele output als platte tekst leest en de beslissing negeert. Omdat de hook met exitcode 0 is afgesloten, toont het transcript geen foutmelding. Bij de meeste gebeurtenissen gaat die tekst alleen naar het debug-log, terwijl deze bij UserPromptSubmit, UserPromptExpansion, SessionStart en PostModelSwitch wordt toegevoegd aan de context van het model, inclusief de banner. Verpak eventuele echo in uw profiel zodat deze alleen worden uitgevoerd in interactieve shells.
  • Komt u er nog steeds niet uit: start de sessie met claude --debug-file /tmp/claude.log en voer tail -f /tmp/claude.log uit in een tweede terminal. Het debug-log registreert welke hooks overeenkwamen, welke exitcode elk daarvan teruggaf, en alles wat ze naar stdout en stderr schreven.

FAQ

Wat is het verschil tussen een Claude Code hook en een CLAUDE.md instructie?

Een CLAUDE.md instructie is tekst in de context van het model, waardoor deze moet concurreren met de conversatie en het huidige verzoek; het model kan de instructie hiertegen afwegen. Een hook is een shell-commando dat Claude Code op een vast punt in de levenscyclus uitvoert. Dit wordt bij elke gebeurtenis uitgevoerd, ongeacht wat het model besluit. Gebruik een instructie voor een voorkeur. Gebruik een hook voor een stap die altijd moet plaatsvinden of een actie die nooit mag gebeuren.

Hoe voorkom ik dat Claude Code een specifiek shell-commando uitvoert?

Registreer een PreToolUse hook met een Bash matcher die het commando uit .tool_input.command leest, een reden naar stderr schrijft en afsluit met exitcode 2. Claude Code annuleert de aanroep en toont de reden aan het model. Dit gebeurt vóór de controle van de permission-mode, waardoor de weigering zelfs in bypassPermissions-modus standhoudt. Patroonherkenning op een commandostring is een vangrail en geen beveiligingsgrens, omdat hetzelfde commando kan worden geschreven in een vorm die het patroon mist. Ondersteun dit daarom met toegangsregels en een account zonder bevoorrechte rechten.

Mijn hook print geldige JSON, maar er gebeurt niets. Hoe komt dit?

Controleer uw shell-profiel op tekst die vóór de JSON wordt geprint. Op macOS en Linux wordt een hook zonder args-veld uitgevoerd via sh -c. In configuraties die nog steeds uw profiel inladen, zoals BASH_ENV dat verwijst naar ~/.bashrc, plaatst een profiel dat een banner print deze op stdout vóór uw JSON. Omdat de output niet langer begint met {, behandelt Claude Code alles als platte tekst en negeert het de beslissing. Omdat de hook afsloot met 0, toont het transcript geen foutmelding. Beveilig elke echo in uw profiel met een test voor een interactieve shell en bevestig de oplossing door het debug-logboek uit claude --debug-file /tmp/claude.log te lezen.

Is het veilig om Claude Code hooks op een gedeelde server uit te voeren?

Hooks worden uitgevoerd als de gebruiker die Claude Code heeft gestart, met de bestandsrechten van die gebruiker. Een hook kan dus alles wat dat account kan. Twee gewoontes dekken het grootste deel van het risico: voer de agent uit als een toegewezen, niet-bevoorrecht account met een beperkt sudo-beleid, en lees het hooks-blok van elke repository voordat u het dialoogvenster voor workspace-vertrouwen accepteert of claude -p erin uitvoert. Project-hooks worden namelijk meegeleverd in .claude/settings.json en de -p-modus toont dat dialoogvenster nooit. Stel "disableAllHooks": true in uw instellingenbestand in om hooks uit te schakelen, behalve voor beheerde hooks die de instelling op beheerd niveau vereisen; een projectinstelling van false kan een gebruikersinstelling van true overschrijven.

Was dit artikel nuttig?