Format, lint and test as a hook, not as a plea in the prompt

In Claude Code

We have set up 2 hooks in .claude/settings.json which run the same script with different arguments on different events:

• PostToolUse, matched on Edit|Write, calls it with the format argument

• Stop calls it with the verify argument

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/scripts/hooks/check.sh format" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/scripts/hooks/check.sh verify" }
        ]
      }
    ]
  }
}

Both of these are set to use exit-2 mode which works really well for both of these scenarios. In the case of Stop, it is because using exit 2 we can tell Claude not to end the turn and instead hand it stderr as an instruction, which is where the transcript you've seen above comes from. In the case of PostToolUse, despite the fact that the write has already been performed, running exit 2 will still send stderr to Claude (as per the docs), which is perfect in case the formatting script has some problems.

On the other hand, it's important to note that exit 1 gets treated as a non-blocking error and the action continues, that's why you might have seen people complaining about hooks not working, using this value.

And finally, if your test suite is really slow, you can set "async": true which will run the hook in the background, giving Claude the output during the next turn. If you also set "asyncRewake": true, it will even wake Claude on exit 2 in case the session has been idle. Neither of these will be able to block anything or make any decisions though, they are all about reporting.

So if for example you were to use a permission rule in the if field which allows you to define such syntax, like "if": "Edit(*.ts)", then this hook would be executed only when the tool call matches that rule — an Edit on a .ts file — so a change to the README wouldn't start it at all.

But the problem is that as the formatter modifies the file after the tool has returned its result, which means that at the moment of writing the file's contents on disk are different than what Claude remembers writing. In the 2.1.220 binary there's even a dedicated guard against this case, and its message names the culprit: "File has been modified since read, either by the user or by a linter. Read it again before attempting to write it." But in our run Claude read the file back before proceeding with the edit and both steps were green, so the only penalty was an additional read, rather than losing the turn.

So just to sum up, we'd keep the PostToolUse hook to formatting and nothing more. Anything that restructures code the model is about to edit again is asking for that round trip on every single write.

In Codex CLI

The most important thing is that the events are not being changed from Claude Code, so you need to use the same event names as there. These hooks are located here: <your-repo>/.codex/hooks.json. You can also define [[hooks.PostToolUse]] tables directly in your .codex/config.toml, but you can have only one type of these per layer, otherwise Codex will merge them both and show a warning on startup.

For example, here's how you can wire a PostToolUse hook to run a code style check as well as a Stop hook with its own timeout to run the tests:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "apply_patch|Edit|Write",
        "hooks": [
          { "type": "command", "command": "\"$(git rev-parse --show-toplevel)\"/scripts/hooks/check.sh format" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "\"$(git rev-parse --show-toplevel)\"/scripts/hooks/check.sh verify", "timeout": 120 }
        ]
      }
    ]
  }
}

• The changes to files are represented as apply_patch, so it's the tool_name in the hook's payload, but you can also use this hook for Edit and Write events as well (which are aliases for it)

• If you're using a script in your hook, make sure to define its path based on the repository's root directory, not relative from .codex/hooks/, the docs say plainly that Codex can be started from a subdirectory

• The default exit-2 mode works at both of these events. The other route at Stop is decision: "block" with a reason, and that doesn't stop the run either — it tells Codex to create a new continuation prompt with your reason as its text, which behaves like a user prompt you typed yourself

• The timeout is in seconds and defaults to 600, so you can even set up long tests; still worth setting explicitly so you notice when it drifts

• Lastly, a non-managed command hook has to be reviewed and trusted before it runs. Codex stores this trust against the current hash of the hook, so any new or changed hook will require a review and will be skipped until you approve it via /hooks command. Also, if you don't trust the project-level .codex/ layer, only the user-level hooks will be loaded and you lose the repo's

In GitHub Copilot CLI

Locations for repo-level hook configs are JSON files in .github/hooks/, or hooks key inside .github/copilot/settings.json. For example, here's a config with a postToolUse command hook for the editing tools and an agentStop verify hook with increased timeout:

{
  "version": 1,
  "hooks": {
    "postToolUse": [
      {
        "type": "command",
        "matcher": "edit|create|str_replace_editor|apply_patch",
        "bash": "./scripts/hooks/check.sh format"
      }
    ],
    "agentStop": [
      {
        "type": "command",
        "bash": "./scripts/hooks/check.sh verify --report=block",
        "timeoutSec": 120
      }
    ]
  }
}

Under this config, there are two common mistakes people make:

• The first one is about the matchers. It's a regex compiled as ^(?:PATTERN)$ and tested against toolName, and under a camelCase event that's the runtime name — Copilot's editing tools are all lowercase: edit, create, str_replace_editor, apply_patch. Edit|Write is Claude's vocabulary; it applies on the PascalCase PreToolUse form, which switches to Claude's matcher semantics instead of the plain regex rule

• The second one is about the timeout. timeoutSec defaults to 30, which is not sufficient for an actual test suite, and the expiry behaviour is fail-open, so the check just silently stops existing

• In order for the agentStop hook to work as intended (blocking), you need to set --report=block in its config. It's important to understand that at postToolUse and agentStop the exit status won't do the job: returning 2 raises a warning for the human and the flow moves forward. The model needs to get feedback via JSON on stdout ({"decision": "block", "reason": "..."} in case of agentStop — if you decide it to block, you must provide a reason which will be used as prompt to start a new turn), and in the worst case, the CLI overrides the hook and ends the turn after 8 consecutive blocks, but the script already stands down earlier using stop_hook_active

• That's why for example postToolUse with the formatting step works fine with this default behaviour, because when the formatter fails it's information for the human, not the model

We also noticed today that repo-level hooks weren't being triggered in a fresh temp directory in -p mode; probably because of folder trust — the docs state that only admin policy hooks are always active despite of the folder trust status, which implies other types of hooks depend on it. So to sum up, run /env in the directory you actually work in and have a look at the output to see what hooks the session got; don't assume CI runners will just get them.

In Cursor

We can define our own hooks in the <project>/.cursor/hooks.json file, and Cursor gives the write moment its own event so we don't need a matcher on a general one. Like this:

{
  "version": 1,
  "hooks": {
    "afterFileEdit": [
      { "command": "./scripts/hooks/check.sh format", "timeout": 60 }
    ],
    "stop": [
      { "command": "./scripts/hooks/check.sh verify --report=followup", "timeout": 120, "loop_limit": 1 }
    ]
  }
}

Then we need to remember that the stop hook needs --report=followup. That will result in Cursor's stop not stopping anything but taking followup_message from stdout and posting it as the next message; exactly the same effect, just another route. The loop_limit set to 1 in the config above (the default is 5) means that it'll be run only once as it's enough if the check can either pass or ask for your help.

Remember though that the path is relative and depends on where you define the hook so if you create a project-level hooks file, it runs from the project root, if you do it in ~/.cursor/, it runs from ~/.cursor/ — very common mistake we see when people move their working hook from ~/.cursor/ to the repository.

But as we can see above, by default the failClosed option is set to false so even if the hook returns an error, it'll allow you to proceed. We'd say it's good to keep it this way (so that you don't get blocked because your formatter isn't installed for example) but it makes this pair a convention, rather than a security measure.

Also, in the 2026.07.23-e383d2b release of Cursor, the stop hook wasn't being called at all if you run the agent in print mode, as we've noticed. What we did:

• We attached plain logging to sessionStart, afterAgentResponse and stop

• We ran the agent with -p and --trust

• Only sessionStart wrote anything, so hooks were loaded and stop simply never fired

So verify your stop gate in an interactive session, and don't count on it covering cursor-agent -p runs or cloud agents, which skip a longer list of events again.

In Gemini CLI

Google uses different names for events, but there's no need to convert them by hand. There's a CLI subcommand, gemini hooks migrate --from-claude, that turns a .claude/settings.json into the equivalent .gemini/settings.json. Here's the output of that tool fed the Claude Code block from this lesson — vendor output, not our own creation, with its ten empty event arrays left out here.

{
  "hooks": {
    "AfterTool": [
      {
        "matcher": "replace|write_file",
        "hooks": [
          { "command": "$GEMINI_PROJECT_DIR/scripts/hooks/check.sh format", "type": "command" }
        ]
      }
    ],
    "AfterAgent": [
      {
        "hooks": [
          { "command": "$GEMINI_PROJECT_DIR/scripts/hooks/check.sh verify", "type": "command" }
        ]
      }
    ]
  }
}

As you can see it's very similar, with a few differences. Google uses their own tool identifiers: replace and write_file, not Edit and Write — that's what the converter rewrote. And the default timeout is 60 000 milliseconds, which is 1 minute; every other harness on this page counts seconds.

AfterAgent is the stop event, and there the default exit-2 mode is what you want — it rejects the response and triggers an automatic retry turn, in which the model is shown the contents of stderr as the feedback prompt. It also passes stop_hook_active, so you don't need to modify your existing script guard.

But at AfterTool it doesn't work the same way: it hides the tool result and sends your stderr as the replacement, so the message about the successful write is lost. Which is fine for a formatter that only speaks when it's broken; if you want it to report on a successful write, use hookSpecificOutput.additionalContext — it appends instead.

Finally — it's always good to check which Google CLI you're on. The hooks reference carries a banner: "Unpaid tier and Google One users: Gemini CLI will be replaced by Antigravity CLI on June 18th." And that has already happened: a session on an individual account today failed before it started, throwing an IneligibleTierError pointing at Antigravity. Antigravity is an independent project with a single hooks.json in the customisation root — .agents/hooks.json. Its top-level keys are names of hooks, and under each hook name there are PreToolUse, PostToolUse, PreInvocation, PostInvocation and Stop arrays.

The example that comes with Antigravity is a lint-checker invoking a ./scripts/lint.sh shell script, so it's a well-trodden path; but what's important is that it uses the directory containing hooks.json as the working dir, so you need to adjust the path in this recipe.

In Kimi Code CLI

Hooks are defined in a flat TOML array under ~/.kimi-code/config.toml (or $KIMI_CODE_HOME, which is useful if you want to test a config without touching the real one). Every rule takes the form of a single table with the event as one of its fields, see below.

[[hooks]]
event = "PostToolUse"
matcher = "Edit|Write"
command = "./scripts/hooks/check.sh format"
timeout = 60

[[hooks]]
event = "Stop"
command = "./scripts/hooks/check.sh verify"
timeout = 120

So we get two rules: PostToolUse matched on Edit|Write running the format check, and Stop running the verification, each with its own time limit.

The timeouts are in seconds, between 1 and 600 inclusive, with a default value of 30 — which is too low for an actual test suite, so either set it or the stop gate will start hitting it as the suite grows. Hitting the timeout doesn't fail closed either, the check is just skipped.

You can block on only three events here:

• Stop — the obvious one, and the script's default exit-2 mode is exactly what it reads: the reason goes to standard error and gets appended so the model can continue its line of thought

• PreToolUse

• UserPromptSubmit

PostToolUse isn't one of them. The check still runs there, it just can't alter the flow of the turn — it's an observer, which is why the format hook still works, because it's a side effect. It doesn't make sense to place a linter there though.

After every change to the file, run kimi doctor. Each rule must contain only these four fields; add any other key and the entire config file becomes unreadable to the CLI. Mistype an event name and you'll get the list of all possible ones:

hooks[1].event: Invalid option: expected one of "PreToolUse"|"PostToolUse"|"PostToolUseFailure"|
"PermissionRequest"|"PermissionResult"|"UserPromptSubmit"|"Stop"|"StopFailure"|"Interrupt"|
"SessionStart"|"SessionEnd"|"SubagentStart"|"SubagentStop"|"PreCompact"|"PostCompact"|"Notification"

The problem is that the documentation gives one location and it's the user level, with no project-level equivalent — so we can commit the check script to the repository, but not the configuration. That means every member of the team needs to add these two tables to their own config file, and on a fresh machine there's no gate at all until somebody remembers. So we'd keep check.sh in the repository and make it as minimal as possible: it's the only half you can actually share.