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

Hook events, from trigger to message

PreToolUse can prevent a call from happening, PostToolUse can only react after the fact, and a hook's decision travels through precise JSON fields, never 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. This difference in timing determines what a hook can reasonably do at each event, and it explains why the same blocking mechanism does not behave the same way depending on the event that carries it.

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. An intended automatism, presented in the previous lesson as the mechanical translation of a rule one hoped would be followed, is always declared on one of these precise events, never on a general intention.

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

A hook of type command, http, or mcp_tool has six hundred seconds by default to respond. Three events lower this timeout to thirty seconds, UserPromptSubmit, PreModelSwitch, and PostModelSwitch, and just one reduces it to ten seconds, MessageDisplay. A hook of type prompt keeps a fixed timeout of thirty seconds, a hook of type agent a fixed timeout of sixty seconds, whatever event triggers it. SessionEnd works differently: the whole set of its hooks shares a budget of one and a half seconds, extendable up to sixty seconds only if a hook explicitly declares a longer timeout.

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. To add information without blocking anything, hookSpecificOutput.additionalContext inserts text that the model will read as though it came from elsewhere in the conversation.

{
  "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 documents two values, allow and deny. To hand the decision back to the usual permission flow rather than forcing it, a hook writes no third value into this field: it exits with code 0 without reporting a decision, and the call continues along its normal approval path, as though this particular hook had had nothing to say about it.