Claude Code Hooks: Make the Rule Impossible to Skip

Every rule I wrote down got broken. Every rule I put in a hook never did.

That's not a philosophy. It's what happened when I went from a couple of agents to twenty, and it's the single thing that made the difference between a crew I had to watch and a crew I could leave alone.

A rule in a document is a rule until somebody is in a hurry

The first version of my setup was a good document. It said who owned what, who was allowed to deploy, how to report finished work, what never to touch.

Agents read it. Agents mostly followed it. Mostly is the problem.

An agent in the middle of a long task is exactly the wrong reader for a paragraph written three weeks earlier. It's deep in something, it has a reason, the reason is usually decent — and the rule loses. Not through defiance. Through context.

Humans do this too. The difference is a person feels the edge of what they were asked to do, and an agent doesn't. So the thing that holds a human crew together loosely has to hold an agent crew together structurally.

A rule in a document is a rule until somebody is in a hurry. A rule in a hook is a rule.

A hook is a rule the system enforces instead of the agent remembering

Claude Code lets you attach code to points in a session's life. Something is about to run, something just finished, a session is starting, a session is ending. Your code runs at that moment and can allow the thing, change it, or refuse it.

That's the whole mechanism, and the important word is refuse. The agent doesn't decide to comply. It never gets the chance not to.

graph TD
  A[Agent decides to do something] --> H{Hook runs first}
  H -- allowed --> D[It happens]
  H -- refused --> B[It never happens]
  B --> M[The agent is told why, in words it can act on]
  S[Session starts] --> I[Hook injects the state it must not miss]
  E[Session ends] --> C[Hook checks the work was saved]

The four moments do different jobs. Before a call, you can block. After a call, you can check. At the start, you can inject what the agent must not miss. At the end, you can catch what it forgot.

The four hooks doing the most work in my setup

These are the ones running right now, in a crew of twenty across three divisions.

One agent cannot wake another. A worker might decide its news is urgent enough to interrupt a boss. The block happens before the call runs. It isn't trusted to hold back — it can't, so the boss's attention stays a scarce, protected thing instead of a shared inbox.

Every session starts already knowing the state. A start hook injects the division's shared channel into context on every turn. The same trick works one level down — a second brain is how an agent arrives knowing your workspace instead of only your channel. Nobody has to remember to check anything, which matters because "remember to check" is the least reliable instruction you can give anyone, silicon or otherwise.

Two agents cannot overwrite each other. The shared channel is one file that many agents write to. A hook puts every post through a lock. Before that, two agents posting in the same second silently ate one another's messages — and a message that vanishes is worse than no channel at all, because everyone believes it arrived.

The session cannot end quietly on unsaved work. A stop hook checks for work that exists only on this machine and refuses to let the session close clean until it's pushed. That one has caught me — not an agent, me — more than once.

Constrain the format, not just the action

The subtler use, and the one I'd have skipped a year ago.

The shared channel my agents post to has a grammar: every post needs a type and a routing arrow saying who it's for. That's enforced. A post that arrives without them is rejected with a message explaining the shape, and the agent fixes it and posts again.

There's a hard length cap too — a few hundred characters, enforced the same way, with a line telling the writer to put the detail in a document and link it.

Neither of those is about safety. They're about the channel staying readable at twenty agents, because a shared channel that becomes a chat log is a channel everyone stops reading. Documented, those rules would have decayed in a week. Enforced, the format holds itself.

What this buys you

It isn't obedience. It's that you stop having to check.

The reason twenty agents don't produce twenty times the anxiety is that the things I'd have to worry about are things that cannot happen. A cloud agent can't deploy. A worker can't interrupt a boss. A post can't clobber another post. Work can't be lost to a closed session.

I don't verify any of that. There's nothing to verify — the failure isn't rare, it's unavailable.

That's the difference between supervising a crew and running one. Supervision doesn't grow. Structure does.

Write the rule, then ask where it lives

Here's the move, and it takes about ten minutes per rule.

Go find the rules you've written down for your agents. For each one, ask a single question: what happens if this gets ignored at the worst possible moment?

If the answer is "nothing much," leave it in the document. Documents are fine for preferences.

If the answer is expensive — something goes live that shouldn't, something gets deleted, something gets lost, you get woken up — that rule doesn't belong in a document. Move it into a hook and let the system be the thing that remembers.

Then write the refusal message carefully. The agent will read it at the moment it's blocked, and a good one turns a wall into an instruction.

Write it down for the rules that are preferences. Enforce the ones that are real rules.