Claude Code Hooks Examples: Which Mistakes Need a Hook, and How to Build One That Really Stops Them

2026-11-21来源 dev.toEnglish
Claude Code Hooks Examples: Which Mistakes Need a Hook, and How to Build One That Really Stops Them

Five Claude Code hooks that stop its worst mistakes.
I run seventy of them.

One of them took a mistake Claude made about a hundred times, and now blocks it before it ever reaches me.
Every one of those hooks exists because a written rule didn't work.

I made a video about it.
This article has what the video has no room for: the events a hook can stop and how each one says no, the real code behind the five hooks (translated into English), the settings.json entries, the commands to test a hook by breaking it on purpose, and a checklist for deciding what becomes a hook.

5 hooks, worst mistakes

The short version

  • A rule in CLAUDE.md is something the model reads. Reading is not the same as obeying, and long sessions bury the rule.
  • A hook is a script that Claude Code runs at a fixed moment: before a tool call, before a reply ends, when you send a message.
  • The script can say no. A PreToolUse hook denies the tool call. A Stop hook sends the reply back to be written again.
  • My five: long dashes in drafts, replies in the wrong language, posting to the wrong account, saying "fixed" without checking, and leaving the cursor in a password field.
  • Three steps decide what becomes a hook: find the real cause on the real thing, make it stop instead of warn, and break it on purpose to watch it fire.
  • A hook you never saw fire is a hook you don't actually have.
  • What to make, which topic, whether it is good: those stay with a person.

I have run my own company in Japan for 22 years.
Claude Code does a lot of my daily work: videos, posts, articles.
Everything about my hooks below comes from the files themselves. I read each one again for this article and ran the tests shown here.

Claude Code keeps making the same mistake

70 hooks, 127 written records

Behind my hooks there is a folder of written records of things that went wrong.
There were 127 when I made the video. Today there are 134.
Each record says what happened, why, and what now stops it.

Here is what "same mistake" actually means.

A long dash in an email draft

In July, Claude Code kept putting long dashes in my emails.
Those dashes make writing look like AI wrote it.

Sorry! x100

I told it not to.
It said sorry, fixed it, and used one again in the very next draft.
By my own count, I had pointed it out about a hundred times.

When I looked into why, the answer was simple.
The rule existed, but only in places that never saw my emails: a hook limited to file edits, and the instructions for one blog platform.
A rule that is not written where the work happens is not followed.

CLAUDE.md says reply in Japanese. The reply is in English.

Another one.
After a long work session, it would report back to me in English.
My rule says Japanese.
It was right there in the file.

Why Claude Code ignores rules in CLAUDE.md

A rule in a file is something the model reads.
Reading is not the same as obeying.

The longer the session, the more other text piles up on top of your rule: code, logs, tool results, English documentation.
The rule doesn't disappear.
It just gets quieter.

Writing it louder, in capital letters, helps for a while.
Then it slips again.

These are the two failures I saw, side by side:

The dash The language
The rule Never use long dashes Reply in Japanese
Where it was written A hook for file edits, and one platform's instructions CLAUDE.md
When it broke Email drafts, which the rule never covered The end of long sessions full of English code and API output
What Claude did when told Apologized, fixed it, did it again Apologized, switched back, did it again
What fixed it A hook on every path a draft can take A hook that reads the reply before I see it

What are Claude Code hooks

Hooks give you deterministic control

Claude's own team puts it in one line.
The description of the official video "Hooks in Claude Code" opens with: "Hooks give you deterministic control over Claude Code's behavior at key lifecycle events."

Before a tool call, before the reply ends, when you send a message

A hook is a small script that runs at a fixed moment.
Before Claude uses a tool.
Before it finishes a reply.
When I send a message.

The model can forget a rule.
A script can't.
If the check fails, the action stops, no matter how long the session is.

Claude Code passes the script a JSON object on standard input.
It includes transcript_path, the path of the session's transcript (a JSONL file), and for tool events it includes tool_name and tool_input.
The script answers with its exit code or with JSON on standard output.

These are the moments my hooks use, and how my scripts say no at each one:

Moment Event What my script reads How it says no
Before a tool call PreToolUse tool_input (the command, the file content, the draft) Prints {"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "..."}}. The tool does not run, and Claude sees the reason.
After a tool call PostToolUse tool_input Cannot undo the call. Prints additionalContext so Claude sees a warning right away.
Before the reply ends Stop The transcript, through transcript_path Exits with code 2 and the reason on standard error, or prints {"decision": "block", "reason": "..."}. Claude keeps working and has to answer the reason.
When I send a message UserPromptSubmit Nothing (mine ignores the input) Does not say no. What it prints is added to what Claude sees, so the reminder is never far away.

One field matters for every Stop hook: stop_hook_active.
It is true when Claude is already continuing because a Stop hook sent it back.
All of my Stop hooks return right away when they see it, so a hook can send a reply back once, but never in an endless loop.

I have 70 hook scripts in ~/.claude/hooks.
In ~/.claude/settings.json they make 77 entries, because some scripts run at more than one event, and a few entries are one line commands written straight into the file.
This is where those 77 entries sit today:

Event Entries
PreToolUse 48
Stop 14
PostToolUse 7
UserPromptSubmit 4
SessionStart 2
Notification 1
SessionEnd 1

Most of them are PreToolUse: they decide whether a tool call goes ahead.
That is the moment where saying no costs nothing, because nothing has happened yet.

Claude Code hooks examples: dashes and language

1. The dash hook

Draft, gate, "Dash found. Rewrite."

The dash hook reads every draft before it goes out.
One dash, and the draft is blocked with the reason.
Since then, every dash gets caught before I see it.

In my setup there are two parts:

Where the text goes Event What happens
An email draft, instructions handed to a sub agent, a page I publish PreToolUse Denied. The draft is not created until the dash is gone.
A file Claude writes or edits PostToolUse Claude is told right after the write, with the line to fix

Mine is a one line command inside settings.json.
This is the same logic as a script, with the message translated.
I wrote the four characters as UTF-8 bytes, so this article itself gets past my own hook:

#!/bin/bash # PreToolUse: refuse a draft that contains a long dash. # The four characters are written as UTF-8 bytes: em dash, en dash, horizontal bar, box line. body=$(jq -r '.tool_input | tostring') if printf '%s' "$body" | LC_ALL=en_US.UTF-8 grep -Fq \ -e $'\xe2\x80\x94' -e $'\xe2\x80\x93' -e $'\xe2\x80\x95' -e $'\xe2\x94\x80'; then printf '%s' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"BLOCKED: the draft contains a long dash. Rewrite it with a period, a comma, a colon, parentheses or a line break, then try again."}}' fi 

It turns the whole tool_input into one string, so it does not matter which field the text is in: content, new_string, an email body, or a prompt for a sub agent.

And the entry in ~/.claude/settings.json.
The matcher picks the tools by name. Names separated by | are matched exactly. Put the names of the tools your drafts go through:

{ "hooks": { "PreToolUse": [ { "matcher": "Write|Edit|MultiEdit|Task", "hooks": [ { "type": "command", "command": "bash \"$HOME/.claude/hooks/no-dash.sh\"" } ] } ] } } 

2. The language hook

The language hook checks every reply I get.
If it's in English, Claude has to write it again.

This one took three layers, added one at a time, each after the one before was not enough:

Layer Event What it does
A reminder UserPromptSubmit Adds two lines to every message I send: replies are in Japanese, and identifiers, commands, file names and product names can stay in English
The reply Stop Reads every text Claude wrote since my last message. If one is mostly English, the reply goes back
The line before a tool call PreToolUse Reads the short note Claude writes just before calling a tool. If it is English, the tool call is denied

The reminder came first, and it was not enough, because it is just another rule to read.
The Stop hook came next.
The third layer came after a day when the Stop hook caught English notes at least seven times: it only fired at the end of the turn, and by then the English notes had been on my screen for minutes.

The test for "mostly English" is the part worth copying.
Code, URLs, email addresses, paths and identifiers are removed first.
Then, if at least six English words are left and the Japanese characters are fewer than 30% of the English letters, it counts as English.

This is the Stop hook, with the messages translated:

#!/usr/bin/env python3 """Stop hook: if the reply in this turn is mostly English, make Claude write it again. My rule is "reply in Japanese". Claude Code passes the path of the transcript (a JSONL file) on stdin. This reads every text Claude wrote since my last message, removes code, URLs, paths and identifiers, and counts what is left. """ import json, os, re, sys JA = re.compile(r'[぀-ヿ㐀-鿿ヲ-゚]') # kana and kanji LATIN_WORD = re.compile(r'[A-Za-z]{2,}') def strip_code(text): text = re.sub(r'``` .*? ```', ' ', text, flags=re.S) text = re.sub(r'`[^`\n]*`', ' ', text) text = re.sub(r'https?://\S+', ' ', text) text = re.sub(r'\S+@\S+', ' ', text) text = re.sub(r'(?:[\w.-]+/)+[\w.-]+', ' ', text) # paths  text = re.sub(r'\b[\w-]*[_\d][\w-]*\b', ' ', text) # identifiers like sk_live_xxx  return text def is_english(text): body = strip_code(text) words = LATIN_WORD.findall(body) if len(words) < 6: return False latin = sum(len(w) for w in words) return len(JA.findall(body)) < latin * 0.3 def is_real_user(row): content = (row.get('message') or {}).get('content') return row.get('type') == 'user' and isinstance(content, str) and not content.lstrip().startswith('<') def main(): data = json.load(sys.stdin) if data.get('stop_hook_active'): # already sent back once in this turn  return path = data.get('transcript_path') if not path or not os.path.exists(path): return rows = [] with open(path, encoding='utf-8') as f: for line in f: try: rows.append(json.loads(line)) except ValueError: pass start = max([i for i, r in enumerate(rows) if is_real_user(r)], default=0) hits = [] for row in rows[start:]: if row.get('type') != 'assistant': continue for part in (row.get('message') or {}).get('content') or []: if isinstance(part, dict) and part.get('type') == 'text' and is_english(part.get('text', '')): hits.append(part['text'].strip().splitlines()[0][:80]) if hits: print(json.dumps({'decision': 'block', 'reason': 'Your reply is in English. Write it again in Japanese. ' 'Identifiers, commands, file names and product names can stay in English.\n' + '\n'.join(' ' + h for h in hits[:3])}, ensure_ascii=False)) main() 

is_real_user matters more than it looks.
In the transcript, tool results are also rows of type user, but their content is a list, not a string.
Without that check, "since my last message" would mean "since the last tool result", and most of the reply would never be read.

If your rule is a different language, change the two character classes.

One thing I learned the hard way about hooks that read the transcript: a long session's transcript grows to hundreds of megabytes.
A hook that runs before every tool call should read only the end of the file, not parse the whole thing every time.

Claude Code mistakes that cost more

1, 2, 3

Those are small.
Some mistakes cost more.
Here are three that turned into stops.

3. Posting to the wrong account

Account A, Account B, POST

Last month, a short video meant for one of my company's accounts was posted to my personal account instead.
Same phone, same app, and the app was still logged in as the other account.
It came down four minutes later, but it had gone out.

The posting steps in my notes said "switch accounts on one app" and said nothing about the other.
The tool that posts had no step that looked at which account was open.

Wrong name, no post

Now, before any post, a test opens the profile and reads the account name on the screen.
Wrong name, no post.

This one is not a settings.json hook.
It is a gate at the top of the script that drives the phone, which is where every post has to pass.
It works in two parts:

Part What it does
The check A UI test on the phone opens the app's profile tab, takes a screenshot, and passes only if the expected account name appears exactly, near the top of the screen. If the account switcher list is open, it fails, because that list shows every account's name.
The gate Every step that touches a social app needs the account name passed in. It refuses unless the check passed for the same phone, the same app and the same name, within the last 20 minutes. Switching accounts deletes the record, so the check has to run again.

The gate, simplified and translated:

#!/bin/bash # Run before any step that posts. ACCOUNT is the account this post is meant for. # The check writes the name it read on the profile screen into $STATE/<device>-<app>. STATE="$HOME/.post-gate"; F="$STATE/$DEVICE-$APP" if [ -z "${ACCOUNT:-}" ]; then echo "Stopped: say which account this post is for (ACCOUNT=...)"; exit 1; fi if [ ! -f "$F" ] || [ "$(cat "$F")" != "$ACCOUNT" ] || [ $(( $(date +%s) - $(stat -f %m "$F") )) -gt 1200 ]; then echo "Stopped: first confirm that $APP on $DEVICE is open as $ACCOUNT (within 20 minutes)"; exit 1 fi echo "OK: posting as $ACCOUNT" 

(stat -f %m is the macOS form. On Linux it is stat -c %Y.)

The lesson that carries over: the gate does not trust a name Claude says.
It trusts only a name that was read off the screen.

4. Saying "fixed" without checking

Test copy: pass. Real setup: error.

It told me a bug was fixed.
It had tested a copy under a different condition.
On my real setup, it wasn't fixed at all.

The bug only showed up while the app was unlocked.
Claude had tested on a copy of the profile while it was locked, said it had found the cause, and asked me to restart and try.
I did, more than once, and it failed each time.

Fixed! Confirmed: ____. Where did you confirm it?

Now, if a reply says fixed, a hook asks one question.
Where did you confirm it?
No confirmation line, no reply.

The reply needs one of two lines:

Line Meaning What else is allowed
Confirmed: ... Checked under the same conditions as the problem, and what was seen "Fixed" is fine
Unconfirmed: ... What could not be checked, and why "Fixed" and "should work" are not allowed. The reply has to say "I made a change (unconfirmed)"

A test on a copy, or under a different condition, counts as unconfirmed.

My hook matches Japanese phrases.
This is the same logic with English ones:

#!/usr/bin/env python3 """Stop hook: a reply that says "fixed" must say where it was confirmed. If the last reply claims a fix, it needs one of these lines: Confirmed: <what you checked, under the same conditions as the problem> Unconfirmed: <what you could not check, and why> A reply with an Unconfirmed line may not also say "fixed" or "should work". """ import json, os, re, sys CLAIM = re.compile(r"\b(fixed|solved|resolved|found the (?:root )?cause|should (?:now )?work)\b", re.I) ASSERT = re.compile(r"\b(fixed|solved|resolved|should (?:now )?work)\b", re.I) CONFIRMED = re.compile(r'^\s*Confirmed:\s*\S', re.M) UNCONFIRMED = re.compile(r'^\s*Unconfirmed:\s*\S', re.M) def last_reply(path): text = '' with open(path, encoding='utf-8') as f: for line in f: try: row = json.loads(line) except ValueError: continue if row.get('type') != 'assistant': continue parts = (row.get('message') or {}).get('content') or [] body = ''.join(p.get('text', '') for p in parts if isinstance(p, dict) and p.get('type') == 'text') if body.strip(): text = body return text def main(): data = json.load(sys.stdin) if data.get('stop_hook_active'): return path = data.get('transcript_path') if not path or not os.path.exists(path): return text = last_reply(path) claims 

原文:https://www.a8q9.cn/en/article/claude-code-hooks-examples-which-mistakes-need-a-hook-and-how-to-build-one-that--02f1da.html

相关文章