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.
• PreToolUse fires before a tool runs and is the only event that can gate or block the call, either by exiting 2 or by printing a permissionDecision.
• Exit codes are the simple contract: 0 allows the call, 2 blocks it and returns stderr to the model, any other non-zero is logged and ignored.
• Stop fires when a turn ends and Notification fires when Claude needs input, so both are good places to send yourself an alert.
• Wire the Stop hook (or connect Pushary) to get a push notification on your phone the moment a run finishes.

The full event list is longer than three. The current hooks reference lists many more, including SessionStart, UserPromptSubmit, PostToolUseFailure, SubagentStop, PreCompact, and SessionEnd. Most of them are for logging or context injection. The handful below are the ones that change agent behavior.

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. Exit 2 is a blocking error: the tool call (or the stop, depending on the event) is blocked and stderr is fed back to the agent. Any other non-zero exit is a non-blocking error that gets logged and ignored.

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 decision values are allow (let it run), deny (block it), and ask (escalate to the user). There is also updatedInput, which rewrites the tool arguments before the tool runs. That deny path is real enforcement. The tool never runs. A hook that only logs can see the same command, but it can't stop it.

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.