Hooks: The Moment a Plugin Becomes Ambient

Hooks are the point at which a Claude Code plugin stops waiting for a named request and starts responding to the session’s events. This chapter explains the causal path from an emitted event through matching, hook execution, and a decision or message. The goal is to evaluate a hook by its scope, authority, failure behavior, and user visibility—especially when it can observe prompts or tool activity that the user did not separately send to a plugin command.

A skill can supply context when a task matches, and a command can make the user’s intent explicit. A hook is different because the runtime calls it at a lifecycle boundary: before or after a tool, when a prompt arrives, when a session starts, or when the agent is about to stop. That timing is useful for guardrails and automatic review. It is also why a hook deserves more careful inspection than a passive guide. Its main design question is not only “what does it know?” but “what events can cause it to run, and what can it change when it does?”

From event to decision

The hook-development guidance describes two broad hook styles. Prompt-based hooks use model reasoning to make a context-aware decision. A prompt can evaluate a tool input or a stopping condition in light of natural-language context. Command hooks run a deterministic command, often a shell script, for checks that should be fast and repeatable. The distinction is practical rather than absolute: prompt hooks are flexible at ambiguous edges, while command hooks are easier to make predictable and efficient for rules that can be expressed directly.

Both styles begin with an event. Claude Code can emit events for prompt submission, tool use before execution, tool results after execution, stopping, subagent stopping, session start, session end, compaction, and notifications. The plugin registers an event handler and can attach a matcher. A matcher may select one tool, several tools, all tools, a family of MCP tools, or a lifecycle event. A condition can add another gate, such as running a rule only when the Bash command resembles a commit or when a local settings file enables a feature.

The causal sequence is easier to understand when it is kept separate from the hook’s internal logic:

  1. The runtime emits an event with context such as the session, working directory, event name, tool name, input, result, user prompt, or stopping reason.
  2. Claude Code checks which plugin hook registrations match that event and any configured matcher or condition.
  3. A matching prompt or command hook receives the relevant input.
  4. The hook returns a structured result, a message, or an error.
  5. The runtime uses that result to continue, ask, allow, deny, modify, or block where the event supports such a decision.
stateDiagram-v2 [*] --> EventEmitted EventEmitted --> MatcherCheck MatcherCheck --> Skipped: no match MatcherCheck --> HookRunning: match and condition pass HookRunning --> Decision: prompt or command returns Decision --> Continue: allow or message Decision --> Block: deny, ask, or block HookRunning --> HookError: timeout or invalid output HookError --> Continue: non-blocking failure HookError --> Block: blocking failure Skipped --> [*] Continue --> [*] Block --> [*]

The diagram is a control-flow model, not a claim that every event supports every outcome. A pre-tool hook can make a permission decision or update supported input. A stop hook can approve or block completion.