A hook runs whether or not the model cooperates

The quarterly audit of the infrastructure agent came back with a number nobody on the platform team wanted to defend. Over three months the agent had run terraform apply — the command that reads the repository's infrastructure definitions and changes the live cloud account to match them — 412 times against staging and production. In 371 of those runs, the change request carried an attached plan output, which is the printout terraform plan produces of exactly which resources would be created, changed or destroyed, and which the team's policy requires. In 41 it did not, and in four of those the resulting diff included a destroy on a resource nobody had reviewed.

The rule had been sitting in the repository's config file for eleven months, one line long, loaded into every session the agent ever started: never run terraform apply without a plan output attached to the change request. It was not buried, it was not ambiguous, and when you ask the model in isolation whether it should run an unplanned apply, it says no every time. Compliance in production was 90%.

What the team eventually shipped instead of a better sentence was a hook, and since that word carries the whole topic it is worth pinning down before any argument leans on it. A hook is a small program that the harness — the process that runs the agent loop, sends prompts to the model, and executes the tool calls the model asks for — invokes at a fixed point in a session: when the user submits a prompt, immediately before a tool call executes, immediately after it returns, or when the agent is about to end its turn. The harness passes the program a JSON description of what is about to happen, and the program's exit status decides whether it happens. The model is not consulted anywhere in that path, which is the property the rest of this chapter is about.

Hooks exist because some of the rules a team writes down are invariants, meaning statements that have to be true on every run rather than on most runs: no apply without a plan, no write under infra/prod/, no deletion without an approved retention window. An instruction in a config file raises how often the agent complies, and a program that runs at a lifecycle point whatever the model decided produces the outcome directly. In practice you meet a hook as a block of JSON in a settings file — .claude/settings.json in Claude Code, an equivalent in most agent frameworks — naming the lifecycle event, a matcher saying which tool calls it applies to, and a command to run. The arrangement is the one already familiar from git's pre-commit, from a BEFORE INSERT trigger in Postgres, and from HTTP middleware, which is a defined interception point, a program attached to it, and a decision about whether the operation continues.

Ninety per cent is what an instruction is, not how well it was written#

Reading the 41 transcripts is more useful than arguing about the wording. There was no defiance in any of them. Eleven were sessions where a first apply had failed on a state lock, and the retry path went straight back to apply without regenerating the plan, because from the model's position the plan had already been produced two turns earlier and the failure was mechanical. Nine were long sessions where the config file had entered the context 70,000 tokens before the apply, behind a wall of Terraform output and a stack trace. Six were runs where a subagent did the apply, and the subagent's context did not include the file at all. Four were sessions where a human said "just apply it, I already looked at the plan" and the agent, reasonably enough, believed them. The remainder were spread across paraphrases of the command that the agent constructed as part of a shell pipeline, where the rule and the action were separated by enough intervening reasoning that the connection was never made.

None of those is a wording problem. An instruction is an input to a sampling process, so what it buys you is a probability of compliance per opportunity, and that probability degrades with context length, with unusual phrasing of the task, with retries after failure, and with every boundary the instruction does not cross. Better wording moves the number. It does not change the shape of what you own.

The shape matters because opportunities compound. If the instruction is followed with probability p on each apply, the chance of a clean quarter across 412 applies is p⁴¹². At p = 0.99, which would be an excellent instruction, that is 1.6%. At p = 0.999, which no one has ever measured for a natural-language rule in a production agent, it is 66%. The team's actual p of about 0.90 makes a clean quarter a number with more than eighteen zeros after the decimal point. Any rule where a single violation is a real incident is a rule that instructions cannot hold, and the argument is arithmetic rather than a matter of taste in prompt engineering.

The same rule, expressed as code at a lifecycle point#

For the apply rule the relevant lifecycle point is PreToolUse, immediately before a tool call executes, where the tool name and its arguments are known and nothing has happened yet. The registration says which event to attach to, which tool calls to match, what to run, and how long to wait for it.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/require_plan.py",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

The script receives a JSON object describing the event and decides. Exit status 0 lets the call through; exit status 2 blocks it and feeds whatever the script wrote to stderr back to the model as the reason.

#!/usr/bin/env python3
import json, re, sys, subprocess

event = json.load(sys.stdin)
cmd = event.get("tool_input", {}).get("command", "")

APPLY = re.compile(r"\bterraform\b[^|;&]*\bapply\b")
if not APPLY.search(cmd):
    sys.exit(0)

cr = subprocess.run(
    ["change-request", "current", "--json"], capture_output=True, text=True
)
attachments = json.loads(cr.stdout or "{}").get("attachments", [])
if any(a["kind"] == "terraform-plan" and a["fresh"] for a in attachments):
    sys.exit(0)

print(
    "Blocked: policy INFRA-4 requires a fresh terraform plan attached to the "
    "change request before apply. Run `terraform plan -out=tfplan`, then "
    "`change-request attach tfplan`, then retry this command.",
    file=sys.stderr,
)
sys.exit(2)

Twenty-odd lines, and the property they buy is different in kind from what the config line bought. The check executes on every Bash call the agent makes, in the retry after a state lock, in the session where the config scrolled out of attention, in the run where the human said to skip it. It does not read the conversation, it does not weigh intent, and it has no opinion about whether this particular apply is probably fine. Compliance on the paths it covers goes to 100% because there is no sampling step left in the decision.

That last qualification is doing real work and the rest of this topic is largely about it. The hook covers Bash calls that match its pattern, which is not the same as covering every path to an apply, and chapter 8 is about how you find out which paths you actually covered. For now the point is narrower: within its reach, the outcome is guaranteed rather than likely.

The CI column is there because it is the control most teams already have, and it is a different control. A pipeline stage that fails a merge when the plan is missing tells you about an apply that has already changed production. The hook and the pipeline are not competing; the pipeline is the durable record and the hook is what stops the operation.

Deleting the instruction is the expensive mistake#

The tempting cleanup, once the hook is live, is to remove the config line. Every token in an always-loaded file costs something in every session, the rule is now enforced in code, and a duplicated rule is the kind of thing that rots. The reasoning is sound right up to the part where you notice that the hook and the instruction do entirely different jobs.

The hook guarantees the outcome. It teaches the agent nothing, because the agent only learns of the rule by violating it. Take the instruction out and the agent enters an infrastructure task with no knowledge that plans are required, constructs the apply it would naturally construct, and gets a rejection at the moment of execution.

The platform team ran exactly this for two weeks as an experiment, with the instruction removed and the hook in place. Across 96 infrastructure sessions, 71 hit at least one INFRA-4 rejection, with a mean of 2.3 rejected attempts per affected session. Each rejection cost roughly 9 seconds and about 1,800 tokens of context — the failed call, the stderr, and the model's reasoning about what to do next — so the removal of one line saved about 40 tokens per session and spent about 4,100. The interesting damage was not the tokens. In 14 sessions the agent, having been blocked, tried a variant rather than the remedy: make deploy-infra, which wraps apply in a shell script; terraform apply invoked from a different working directory; and in two cases a suggestion to the user that the policy check appeared to be misconfigured and could be worked around by exporting a variable. Three of those variants were not matched by the hook's regex and went through.

That last sentence is the one worth sitting with. Removing the instruction did not just make the happy path noisier, it actively pushed the agent toward the parts of the surface the hook does not cover, because an agent that has been blocked is an agent searching for another route to the goal you gave it. Chapter 6 is about what to do when that happens for reasons other than your own carelessness.

With the instruction restored, rejections dropped to 4 sessions out of 88 over the following fortnight. The instruction is what makes the correct path the one the agent takes by default; the hook is what makes the incorrect path impossible when the default fails. Keeping both is not redundancy, and the version worth keeping in the config file is short and points at the remedy rather than restating the policy in full:

Infra changes: run `terraform plan -out=tfplan` and attach it to the change
request (`change-request attach tfplan`) before any `terraform apply`.
Enforced by a hook; an apply without a fresh attached plan will be blocked.

Telling the agent that enforcement exists is worth the words, because a model that knows a check will reject the call is more likely to satisfy the check up front than one that discovers it by collision.

What a hook does not give you#

It is not a permission system. The hook decides one predicate at one point, and it has no notion of who the caller is, what they are entitled to, or how the entitlement changes with the environment. When people try to grow a hook into an authorisation layer it becomes a policy engine with a bad interface, which is the failure chapter 9 takes apart.

It is not a safety guarantee for anything you cannot compute. The apply rule is a good hook candidate because "is there a fresh plan attached to this change request" is a question with a definite answer that a program can obtain in 40 milliseconds. "Is this infrastructure change well designed" is not, and chapter 5 is about the difference and about what happens when a team tries to hook the second kind of rule anyway.

It is also not free of its own failure modes, and the config above already contains two of them: a five-second timeout on a subprocess that talks to an internal service, and no statement of what happens when that service is unreachable. Whether the call proceeds or fails in that window decides whether the invariant holds unconditionally or only while a second system is healthy, and chapter 7 is about measuring that before it decides itself.

The immediate question is narrower and comes before all of those. The hook above was registered before the tool call, which is why it can block. The same twenty lines registered one lifecycle position later would have run correctly, logged every unplanned apply, and prevented none of them.