Home / Extending: skills, MCP, subagents, hooks, plugins

Hook events, from trigger to message

PreToolUse runs before the tool and can prevent the call; PostToolUse runs afterwards and can only react, including by replacing the tool's result. A hook communicates its decision through a JSON object with precise fields and through its exit code, never through a sentence written to standard output.

A PreToolUse hook runs before the tool activates: its decision can prevent the call from happening. A PostToolUse hook runs afterwards, once the tool has already launched: its decision can no longer prevent anything, only react, including by replacing the tool's result with the updatedToolOutput field. This difference in timing determines what a hook can do at each event.

About thirty events, from startup to end of session

The official documentation lists around thirty lifecycle events, from SessionStart and UserPromptSubmit through to PreCompact, WorktreeCreate, or SessionEnd. Each covers a precise moment: a file changing, a model switch, a subagent starting or ending, a prompt being expanded. It extends the previous lesson: an automatism is always declared on one of these events, never on a general intention.

The timeout depends on the hook type, not just the event

A command, http, or mcp_tool hook has six hundred seconds by default, three events lower it to thirty seconds and MessageDisplay to ten. A prompt hook keeps thirty seconds, an agent hook sixty, whatever the event.

What actually reaches the model: JSON fields, not free text

A hook does not communicate its decision by writing a sentence to standard output. It returns a JSON object whose hookSpecificOutput.permissionDecision field carries the value allow or deny, accompanied by a permissionDecisionReason that explains the choice, and the hookEventName field repeats the exact name of the triggering event.

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Commande destructive detectee dans le motif teste"
  }
}

The script's exit code also matters, independently of the JSON: an exit code of 2 blocks the action even if the JSON body said allow. This rule has named exceptions, PermissionRequest, StopFailure outside a terminal sequence, PermissionDenied, and above all PostToolUse and PostToolUseFailure, where exit code 2 becomes non blocking and merely gets displayed to Claude via standard error: logical, since the tool has already finished running by the time this hook fires.

Deferring rather than deciding

The permissionDecision field accepts four values: allow skips the permission prompt, with documented exceptions, deny prevents the call, ask prompts the user to confirm, and defer ends the turn so the tool can be resumed later, only in non-interactive mode with -p. To hand the decision back to the usual permission flow rather than forcing it, a hook writes none of these values: it exits with code 0 without reporting a decision, and the call continues along its normal approval path.

Testing a hook through its standard input

A hook error lets the action through and is announced only by a notice in the transcript, easy to miss: a badly formed test returns a silence that looks like "the hook does not react". The hook reads a JSON on its standard input, so you can play it by hand, with a case it must refuse and a control it must let through. The following script and its two calls create their own data:

cat > garde.sh << 'EOF'
#!/bin/sh
ENTREE=$(cat)
case "$ENTREE" in
  *"npm publish"*) echo "Refused: run npm publish --dry-run first." >&2; exit 2 ;;
esac
exit 0
EOF
printf '%s' '{"tool_name":"Bash","tool_input":{"command":"npm publish"}}' | sh garde.sh; echo "code=$?"
printf '%s' '{"tool_name":"Bash","tool_input":{"command":"npm test"}}' | sh garde.sh; echo "code=$?"

Refused: run npm publish --dry-run first.
code=2
code=0

The first call proves the guard refuses, the second that its silence means "allowed" and not "broken". Write the JSON with printf '%s' between single quotes: a shell that collapses a backslash breaks the JSON with no visible error.

Does a broken guard let things through?

Since October 2026, a PreToolUse or PermissionRequest hook whose matching fails, or whose input cannot be serialized, blocks the call instead of being skipped. On Windows, a guard with no declared shell also blocks when Git for Windows is missing. A hook run by PowerShell that exited with code 2 did not block before the October fix: reread guards written earlier. For a security guard to block in every failure case, declare "onFailure": "block".