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 takeawaysCopy Anchor Link

• 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 33 events. The full table below lists every one, when it fires, whether it can block, and its exact hookSpecificOutput fields.
• PreToolUse fires before every tool call executes and is the main place to stop one, by exiting 2 or by printing a permissionDecision of allow, deny, ask or defer. PermissionRequest can also deny, but only when a permission dialog would appear.
• 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 eventCopy Anchor Link

The list is far longer than three. Checked against the official hooks reference on 29 September 2026, there are 33 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 wiredCopy Anchor Link

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.

PreToolUseCopy Anchor Link

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 (end the run so the tool call can be resumed later, honored only in non-interactive -p mode). 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.

PermissionRequestCopy Anchor Link

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 PreToolUseCopy Anchor Link

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.

There is a second case with no hook to attach to, and it catches people out. If you are shipping an agent inside your own product, there is no settings.json on the machine that matters, because the agent runs on your server and the person who should approve is your customer. Hooks cannot help you there. You call the approval directly instead: decisions.ask() blocks your agent until that specific user answers on their phone, and enroll(externalId) maps your own user id to their device. Same fail-closed behaviour as the hook path, no CLI involved. That is what human-in-the-loop for AI agents covers, with adapters for LangGraph, the Vercel AI SDK and the rest, and the Partner plan is the version you embed for end users who have no idea Pushary exists.

PostToolUseCopy Anchor Link

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 UserPromptSubmitCopy Anchor Link

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.

Hooks in the Claude Agent SDKCopy Anchor Link

The Claude Agent SDK runs the same agent loop as Claude Code and uses the same event names. The TypeScript SDK exports them as HOOK_EVENTS, and in version 0.3.284, current on 29 September 2026, that list has the same 33 names as the table above. The Python SDK supports 10 of them: PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, SubagentStart, SubagentStop, PreCompact, PermissionRequest and Notification. The difference is where a hook lives. In the SDK it is a function in your code, passed in the hooks option of query(), not a shell command in settings.json.

Each event takes a list of matchers. A matcher has an optional matcher pattern, a list of callbacks and an optional timeout in seconds. A callback receives the same input a command hook reads on stdin, and it returns the same JSON a command hook prints:

import { query, type HookCallback } from "@anthropic-ai/claude-agent-sdk"

const blockEnvReads: HookCallback = async (input) => {
  if (input.hook_event_name !== "PreToolUse") return {}
  const { file_path } = input.tool_input as { file_path?: string }
  if (!file_path?.endsWith(".env")) return {}
  return {
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Reading .env files is blocked",
    },
  }
}

for await (const message of query({
  prompt: "Summarise the config in this repo",
  options: { hooks: { PreToolUse: [{ matcher: "Read", hooks: [blockEnvReads] }] } },
})) {
  if (message.type === "result") console.log(message.subtype)
}

The permissionDecision values are the same four: allow, deny, ask and defer. In the SDK, defer ends the query so you can resume it later. updatedInput and additionalContext work the same way too.

A hook is the right place for a fixed rule. When a person should decide, the SDK has a separate callback for that, canUseTool, which runs when a tool call needs permission. @pushary/claude-agent-sdk implements it: the question goes to your user's phone, and Approve or Deny comes back as the permission result. That package is for agents you ship to your own users, on the Partner plan.

Putting it togetherCopy Anchor Link

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.

If you would rather not wire it yourselfCopy Anchor Link

Hooks are a shell contract, so anything that reaches your phone from one is something you either build or buy. Claude Code notifications is the buy side written out in full: what arrives on the phone, what you can answer from the lock screen, and what it costs. The honest comparisons are worth reading before you pick either way: Pushary vs Happy and Pushary vs Omnara cover the tools that mirror a whole session to your phone, Pushary vs HumanLayer covers approval APIs you call from your own code, and Pushary vs ntfy covers the free route where you keep the hook and add a push channel. All comparisons has the rest.

Common questionsCopy Anchor Link

What are Claude Code hooks?Copy Anchor Link

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?Copy Anchor Link

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.

Which hook event fires when Claude Code finishes a turn?Copy Anchor Link

Stop. It fires when Claude finishes responding, which is the end of a single turn rather than the end of the session. SubagentStop is the subagent equivalent, and SessionEnd fires when the session itself ends. Stop is also one of the events that can block: returning a decision of block with a reason forces the agent to keep going instead of ending the turn.

Getting that event to reach you away from the machine is a separate problem from the hook contract, and the Claude Code notifications page covers it. If a Stop or Notification hook is wired and no alert shows up, or it fires on every reply, Claude Code notifications not working walks through the causes.

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

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 fires before every tool call, so it is the one that reliably prevents the read. PermissionRequest also fires before the call, but only when a permission dialog would appear. 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?Copy Anchor Link

allow, deny, ask, and defer. allow runs the tool, deny blocks it, ask escalates to the user, and defer ends the run so the tool call can be resumed later. Claude Code honors defer only in non-interactive -p mode and ignores it in an interactive session. 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?Copy Anchor Link

Thirty-three, as of 29 September 2026. Three were added since our 26 July check: PreModelSwitch, PostModelSwitch and DirectoryAdded. Most events are for logging or context injection. The ones that can block are PreToolUse, PermissionRequest, UserPromptSubmit, UserPromptExpansion, PostToolBatch, SubagentStop, Stop, PreCompact, PreModelSwitch, ConfigChange, TaskCreated, TaskCompleted, TeammateIdle, WorktreeCreate, WorktreeRemove, Elicitation and ElicitationResult. The rest observe and cannot change the outcome.

How do you use PreToolUse hooks in the Claude Agent SDK?Copy Anchor Link

Pass a function in the hooks option of query(), under PreToolUse, with an optional matcher such as Bash or Read. The function receives the same input a Claude Code command hook reads on stdin, including tool_name and tool_input, and returns the same hookSpecificOutput, so a permissionDecision of deny blocks the call. The TypeScript SDK accepts all 33 event names; the Python SDK accepts 10 of them. To ask a person rather than apply a fixed rule, use the SDK's canUseTool callback, which runs when a tool call needs permission. The example above shows the full shape.

What is hookSpecificOutput?Copy Anchor Link

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.