Home / Extending: skills, MCP, subagents, hooks, plugins

Hooks: automating the lifecycle

A hook is an action the harness runs itself when a precise lifecycle event occurs. An instruction written in memory remains a preference the model may forget; a hook declared once runs on every occurrence, independently of what the model recalls at that moment.

A hook is an action the harness executes itself when a precise lifecycle event occurs, never a request the model interprets at the moment of acting. Writing to a memory file every time you commit, running the tests, remains a preference: the model may forget it after a long conversation or a compaction. A hook declared on the corresponding event runs on every occurrence, independently of what the model recalls at that moment.

The mechanism: an event, a command, a decision

A hook is declared in settings.json, or in a plugin's hooks.json file, tied to a lifecycle event and an action type: a shell command, an HTTP call, an MCP tool, a prompt, or an agent. When the event occurs, the harness runs that action and waits for a decision in return, before the question reaches the model.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "./verifier-avant-commande.sh" }
        ]
      }
    ]
  }
}

This declaration ties the PreToolUse event, restricted to calls of the Bash tool, to a script that runs before every proposed command. Each hook type carries its own default timeout, different depending on the event that triggers it: the next lesson details these timeouts event by event, along with the precise JSON fields a hook returns to block, allow, or enrich what the model sees.

Hook versus memory rule: what each actually guarantees

A memory rule depends on a model that rereads it and decides to apply it, within a context window that grows over the course of a session. A hook depends on the harness, which checks the event independently of what the conversation holds at that moment. The difference shows up most on a long session: an instruction repeated twenty times in a memory file can dilute within a loaded context, whereas a hook declared once continues to run identically on the thousandth call as on the first.

A hook that refuses must say what to do

A rule that has cost you once is mechanized as a PreToolUse hook. The refusal arrives before the effect, and its message names the alternative: with exit code 2, what the script writes to standard error is the text Claude receives, and it corrects its call instead of going in circles.

#!/bin/sh
# refuses and says what to do instead
echo "Refused: do not delete, move the file to archives/." >&2
exit 2

By default, a hook that fails lets the action through: a wrong path or a crashing script, and everything passes. For a security hook, declare "onFailure": "block" on a command or HTTP hook, which also blocks the action when the hook cannot start, times out or exits with an unexpected code. To see which hooks exist, type /hooks: a single list, grouped by event. To know whether one ran, start claude --debug, which logs the command, plugin, outcome and duration of each command hook on tool calls, prompts, SessionStart and Stop when it finishes. A <system-reminder> tag written in a hook's output is neutralized before it reaches Claude: a hook's output cannot pass itself off as a system instruction.