Claude Code hooks explained: PreToolUse, PostToolUse, and Stop

Claude Code hooks are shell commands the agent runs at fixed points in its lifecycle. A hook reads a JSON event on stdin, does whatever you want, and can return JSON on stdout to change what happens next. The three you reach for most are PreToolUse (before a tool runs), PostToolUse (after it succeeds), and Stop (when Claude finishes a turn). PreToolUse is the one that can stop a tool call before it executes, and that is the mechanism Pushary runs on.

Key takeaways

• Hooks are shell commands Claude Code runs at fixed lifecycle events, reading a JSON event on stdin and signaling back with an exit code or JSON on stdout.
• There are 30 events. The full table below lists every one, when it fires, whether it can block, and its exact hookSpecificOutput fields.
• PreToolUse fires before a tool call executes and is the only event that can stop the call itself, by exiting 2 or by printing a permissionDecision of allow, deny, ask or defer.
• Exit 2 is not a universal block. It stops the tool on PreToolUse and the turn on Stop, but on SessionStart it blocks nothing, and on PermissionDenied the exit code is ignored entirely.
• Stop fires when a turn ends and Notification fires when Claude needs input, so both are good places to send yourself an alert.
• A Stop hook can send a notification, but it cannot collect an answer: the turn is already over. Pushary attaches to PreToolUse instead, so the tool call waits while the approve/deny decision happens on your phone, and every decision lands in an audit trail.
• If you are looking for onStart and onFinish, Claude Code does not use those names. The nearest equivalents are SessionStart and SessionEnd for a session, and Stop for the end of a single turn.

Every hook event

The list is far longer than three. Checked against the official hooks reference on 26 July 2026, there are 30 events. Most exist for logging or context injection; the ones that can actually stop something are marked below.

"Blocks" means the event can prevent the thing it fires on. The mechanism differs: some use hookSpecificOutput, some a top-level decision field, some just exit code 2.

The events below are the ones that change agent behavior, and the ones Pushary attaches to.

How a hook is wired

You register hooks in settings under a hook event, with an optional matcher to filter when they fire, and a command to run. A matcher of Bash means the hook only fires for the Bash tool. The command receives the event as JSON on stdin and signals its decision two ways: exit codes, or structured JSON on stdout.

Exit 0 means success, and Claude Code parses stdout for decision fields. Any exit other than 0 or 2 is a non-blocking error that gets logged and ignored.

Exit 2 is where people get caught out, because it is often described as "exit 2 blocks" as though that were universal. It is not. What exit 2 does depends on the event:

• On PreToolUse it blocks the tool call and feeds stderr back to the model.
• On UserPromptSubmit it blocks the prompt, on Stop it prevents the turn ending, on SubagentStop it prevents the subagent stopping, on PreCompact it blocks compaction.
• On SessionStart and SubagentStart it blocks nothing at all. It shows stderr as a hook error notice and the session or subagent carries on regardless.
• On Notification it is simply a non-blocking error shown to you.
• On PermissionDenied and StopFailure the exit code is ignored outright, because the outcome has already happened.

If you need a decision rather than a signal, prefer the JSON path. It says what you mean and it does not depend on remembering which event you are in.

PreToolUse

PreToolUse fires before a tool call executes. The event carries the tool name and its arguments, so your hook sees exactly what the agent is about to do:

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/current/dir",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "rm -rf /tmp/build" }
}

To gate the call, return hookSpecificOutput with a permissionDecision:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Destructive command blocked by hook"
  }
}

The permissionDecision values are allow (let it run), deny (block it), ask (escalate to the user), and defer (hand the decision back to the normal permission flow rather than settling it here). Alongside it, updatedInput rewrites the tool arguments before the tool runs, and additionalContext injects text the model sees.

That deny path is real enforcement. The tool never runs. A hook that only logs can see the same command, but it cannot stop it.

PermissionRequest

PermissionRequest fires when a permission dialog would appear, which makes it the second place a decision can be settled without you touching the keyboard. It answers through hookSpecificOutput.decision rather than permissionDecision, and the shape is different enough to be worth writing out:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": { "behavior": "deny", "message": "Denied by policy for Bash(rm -rf:*)" }
  }
}

behavior is allow or deny, and the decision object also accepts updatedInput and applyRules.

The ordering catches people out when both hooks are registered. PermissionRequest fires after PreToolUse, and only on the ask path: if PreToolUse already returned allow or deny, the dialog never happens and this event never fires. So a handler registered on both events will see the same tool twice whenever the decision was ask, and needs to skip the tools the earlier hook already owns or it will prompt you twice for one command.

How Pushary uses PreToolUse

Pushary connects to Claude Code as a PreToolUse hook. The agent is about to run a tool, the hook reads the event on stdin, and the handler resolves the tool and its arguments against your permission policy. If the policy says allow, the hook returns allow and the agent never stops. If it says ask, the hook sends a push notification with the command and waits for your answer, then returns allow or deny based on what you tapped.

Two details matter here. First, the policy matches on the arguments inside tool_input, not just tool_name, so git status and git push --force get different treatment from the same Bash tool. Second, a proven read-only set of commands is auto-approved by default, decided from 1,721 real production questions, so reads never interrupt you. More on both in the permission policy writeup. The Claude Code wiring is in the setup guide.

PostToolUse

PostToolUse fires after a tool call succeeds. It cannot stop the call, the work already ran, but it sees the result and can feed feedback back to the agent or replace the tool output. Use it for logging, formatting after an edit, or flagging a result the agent should reconsider. It runs the cleanup half of the loop, after PreToolUse has already let the call through.

Stop and UserPromptSubmit

Stop fires when Claude finishes responding. Returning a decision of block with a reason forces the agent to keep going instead of ending the turn, which is how you make a turn continue until tests pass or a phone-queued instruction is picked up.

UserPromptSubmit fires when you submit a prompt, before Claude reads it. Plain stdout from this hook is added to the prompt as context, and it carries the message text, which is how a running session can capture a real task title for the fleet board.

Putting it together

The hook contract is small: read JSON on stdin, decide with an exit code or a JSON object on stdout. Gate with PreToolUse. Watch with PostToolUse. Stop decides whether a turn actually ends. Pushary turns the PreToolUse decision into a push notification you answer from your phone, then logs every call to an audit trail. See the Claude Code notifications page, or wire up other agents over MCP.

Common questions

What are Claude Code hooks?

Claude Code hooks are shell commands the agent runs at fixed points in its lifecycle. A hook reads a JSON event on stdin, does whatever you want, and can return an exit code or JSON on stdout to change what happens next. The events you reach for most are PreToolUse (before a tool runs), PostToolUse (after it succeeds), and Stop (when Claude finishes a turn).

What exit code must a PreToolUse hook return to block a tool call?

Exit code 2. A PreToolUse hook that exits 2 blocks the tool call and feeds its stderr back to the model as the reason. Exit 0 allows the call. Any other non-zero exit is a non-blocking error that is logged and ignored. For structured control you can instead exit 0 and print hookSpecificOutput JSON on stdout with a permissionDecision of allow, deny, or ask.

How do I get notified when Claude Code finishes?

Use the Stop hook, which fires when Claude finishes responding. Wire that event to a command that sends you a notification. Pushary does this for you: it attaches to Claude Code and sends a push notification to your phone when a turn ends or when a PreToolUse decision needs your answer.

Which hook stops Claude from reading sensitive .env files, and what tool names does it match?

A PreToolUse hook, matched against the file-reading tools: Read, plus Grep and Glob if you want to stop the file being searched as well as opened. PreToolUse is the only event that fires before the call executes, so it is the only one that can prevent the read. PostToolUse cannot help, because by the time it fires the file has already been read. Match on the path inside tool_input rather than on tool_name alone, then return a permissionDecision of deny with a permissionDecisionReason.

What are the permissionDecision values for a PreToolUse hook?

allow, deny, ask, and defer. allow runs the tool, deny blocks it, ask escalates to the user, and defer hands the decision back to the normal permission flow instead of settling it in the hook. They go inside hookSpecificOutput alongside permissionDecisionReason, and optionally updatedInput to rewrite the tool arguments and additionalContext to inject text the model sees.

How many hook events does Claude Code have?

Thirty, as of 26 July 2026. Most are for logging or context injection. The ones that can block are PreToolUse, PermissionRequest, UserPromptSubmit, UserPromptExpansion, PostToolUse, PostToolUseFailure, PostToolBatch, SubagentStop, Stop, PreCompact, ConfigChange, TaskCreated, TaskCompleted, TeammateIdle, WorktreeCreate, Elicitation and ElicitationResult. The rest observe and cannot change the outcome.

What is hookSpecificOutput?

It is the object a hook prints on stdout to return a structured decision instead of relying on an exit code. It always carries hookEventName, and the rest of the fields depend on the event: permissionDecision and permissionDecisionReason on PreToolUse, a decision object with behavior on PermissionRequest, updatedToolOutput on PostToolUse, additionalContext on most of the observing events. Exit 0 alongside it, because a non-zero exit is interpreted before the JSON is.