Anthropic: hooks

Source: Automate actions with hooks

Checked: 13 July 2026. The guide is introductory; the separate hooks reference is authoritative for complete event schemas.

Evidence type: product documentation containing event semantics, examples, limitations, and explicit safety recommendations.

Role of hooks

Hooks run at lifecycle points so a behaviour occurs deterministically rather than depending on the model to remember it. Anthropic positions command hooks for hard mechanics and prompt or agent hooks for judgements that cannot be expressed deterministically.

Documented uses include user notifications, post-edit formatting, pre-edit protected-file checks, post-compaction context restoration, configuration auditing, directory-dependent environment reload, and narrowly scoped approval automation.

A hook is configured as an event, optional matcher, and one or more handlers. A minimal project-level formatter illustrates the boundary:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/scripts/format-edited-file.sh"
          }
        ]
      }
    ]
  }
}

The script receives the event payload on stdin and must derive the edited path from that payload.

Execution semantics

• Events cover session, prompt, tool, permission, configuration, file, worktree, subagent, task, notification, and stop lifecycles.
• Every matching hook runs in parallel; identical commands are deduplicated.
• Hook input is JSON on stdin. Output uses stdout, stderr, exit codes, or structured JSON depending on event and decision type.
• Matchers filter at event or tool-name level. An additional tool-argument filter uses permission-rule syntax but is best-effort and can fail open.
• Project, personal, local, managed, plugin, skill, and agent scopes provide different ownership and sharing boundaries.

The general command contract is exit zero for success, exit two for a blocking decision where the event supports blocking, and another non-zero status for a non-blocking error. Structured JSON is required to alter tool input, supply additional context, or express a richer decision. Diagnostic text must not be mixed into JSON stdout.

These semantics create design constraints. Two hooks must not race to rewrite the same tool input because the last finisher wins nondeterministically. PostToolUse can report or remediate but cannot undo the action. A stop event means the model finished a response, not necessarily that the user’s overall task is complete.

Permission relationship

Event placement matters. A protected-file check belongs in PreToolUse and must inspect tool_input.file_path for Write and Edit; formatting belongs in PostToolUse after the write; restoring compacted context belongs in SessionStart with the compact matcher. These examples are not interchangeable lifecycle slots.

Pre-use hooks run before permission-mode evaluation. A denial still blocks in bypass mode, allowing centrally managed policy to tighten behaviour. An allow cannot override a settings deny rule. Anthropic explicitly recommends the permission system rather than a best-effort argument filter for hard allow or deny enforcement.

Approval hooks must use extremely narrow matchers. An empty permission matcher could approve writes and shell commands unintentionally. Non-interactive mode does not emit the same permission-request event, so automated policy must use a pre-use event instead.

Command, prompt, agent, and HTTP hooks

• Command hooks are the production default for deterministic checks.
• Prompt hooks send the event and a decision prompt to a model for a yes/no result. Their result can continue work, deny a tool, or end a turn depending on the event.
• Agent hooks can inspect files and run tools before deciding, but Anthropic marks them experimental and recommends command hooks for production.
• HTTP hooks send the event to a service. Status codes alone do not express decisions; the response body must use the structured hook output. Only explicitly allowed environment variables are interpolated into headers.

Prompt hooks suit bounded yes/no judgement over the event. Agent hooks can inspect files and call tools before deciding, increasing capability, latency, cost, and attack surface. HTTP hooks add network availability, authentication, data-handling, retry, and service-version dependencies to the local lifecycle.

Reliability and debugging

Hooks have type- and event-specific timeouts. Scripts should be executable, use absolute or project-relative paths, parse JSON robustly, keep stdout clean when JSON is expected, and emit diagnostics on stderr. Non-interactive shell profile output can corrupt JSON. Anthropic recommends direct testing with sample input, the hook browser, transcript summaries, and detailed debug logs.

Stop hooks need loop protection; Claude eventually overrides repeated blocking without progress. A hook should inspect the active-stop signal and allow a clean terminal state.

Standards implications

• Use hooks for narrow deterministic lifecycle rules and scripts as their implementation boundary.
• Specify event, matcher, input schema, output schema, timeout, failure mode, idempotency, and ownership for every shared hook.
• Use permissions, not hook filters, for security boundaries.
• Ban competing input rewrites and broad automatic approval matchers.
• Treat model- and HTTP-backed hooks as higher-risk, higher-cost integrations.