Failing loudly: surfacing a refusal the model will act on

In Claude Code

There are two ways you can do it in Claude Code, they're slightly different in terms of how they work:

• exit code 2 — the standard output and any JSON inside is ignored and the text from stderr is "fed back to Claude as an error message" (simple, and enough when the wording is the only thing you need to get right) like this for example:

print("Migrations are generated, not hand-edited. Change the model and re-run the generator.",
      file=sys.stderr)
sys.exit(2)

• exit code 0 and a decision object (JSON) in the standard output, which is read by Claude only when the exit code is 0 (like this for example):

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Migrations are generated, not hand-edited. Change the model and re-run the generator."
  },
  "systemMessage": "Blocked by .claude/hooks/no-hand-edited-migrations.py"
}

This way it returns both the hook-specific part (the permissionDecision field with the migrations message) and systemMessage with the path to the file that contains the hook. The permissionDecision field can contain allow, deny, ask or defer values, so if you put ask there, it will mean that the user should make a decision in such scenario. The systemMessage is info that is displayed to the user (the stopReason field is connected with continue: false and is documented as "not shown to Claude"), so these two are not being seen by the model, only additionalContext is (for PreToolUse and a few other events) which can be used to provide the model with some info without denying the action.

The thing is, these two ways are not equivalent in terms of what the model sees:

• exit code 2 — Claude will see the following: PreToolUse:Bash hook error: [<hook command>]: <reason>. In our run on version 2.1.220 the model saw the entire hook command prefixed to the reason

• exit code 0 — in this scenario Claude will see only what's inside the permissionDecisionReason field, so not the hook command

In Codex CLI

In terms of the Codex CLI, the hooks are not experimental, you can see them as stable already when running the codex features list command. The main way to refuse an action is by returning status code 2 with some message printed to stderr; it's the most bulletproof solution. For instance:

print("Migrations are generated, not hand-edited. Change the model and re-run the generator.",
      file=sys.stderr)
sys.exit(2)

Another way is to return from the hook with 0 and a JSON with structured information on stdout, instead of a simple message on stderr. The reference lists permissionDecision (allow, deny or ask) with permissionDecisionReason for the reason, the older decision: "block" paired with reason, additionalContext as a piece of information you can pass to the model without blocking it, and systemMessage, which is a message visible to the user as a warning in the interface. If you reject an action using the PreToolUse or PostToolUse hook, the message from these hooks becomes the reason of the halt and appears in the continuation prompt (the model sees it), but not on the user's side.

Generally, these are the hooks that can refuse:

• PreToolUse

• UserPromptSubmit

• PreCompact

• PostToolUse

• PostCompact

• Stop

• SubagentStop

And these ones can't:

• SessionStart

• SessionEnd

• SubagentStart

• PermissionRequest

(any rejection in these is ignored)

If you return from a hook successfully with 0, everything on stdout will be attached as the developer context to the model, so don't forget to remove logs if you accidentally left them in some guard script during implementation of the hook. There's an exception for Stop and SubagentStop hooks though — in this case the thing that's on stdout is being ignored.

In GitHub Copilot CLI

We kind of inherit patterns from the other harnesses, and that's exactly what drops the denial reason in GitHub Copilot CLI: the standard error never carries it to the model. It's "surfaced to the user but the run continues", so the model can't access it anyway. In other words, for the model to know why we've denied sth, we need to pass it through the standard output in a JSON object — there's a field called permissionDecisionReason which is required when the decision is deny.

For example, here's what a denial looks like:

{
  "permissionDecision": "deny",
  "permissionDecisionReason": "Migrations are generated, not hand-edited. Change the model and re-run the generator."
}

So a hook that writes a careful explanation to stderr and exits 2 does block the call — exit code 2 is treated as a deny by preToolUse and permissionRequest, and it overrides an allow in the standard output — but the model still doesn't know why. That's this lesson's failure mode available by default.

We need to define some things per event:

• permissionRequest — behavior of allow / deny, plus message (that's what gets passed back to the LLM on deny)

• agentStop / subagentStop — decision: "block" with reason (the reason is a part of the prompt for the next turn, so you might want to word it as an instruction rather than a complaint)

The gotcha: preToolUse is the one event that fails closed on a non-zero exit, so a guard that crashes denies the call and has no JSON left to explain itself with. But timeouts fail open on every event (including preToolUse), so a hook that hangs doesn't really enforce anything.

In Cursor

Cursor uses the human-vs-model dichotomy in the field names themselves, so it's kinda hard to mess things up here. The hook returns a JSON object in these four cases:

• beforeShellExecution

• beforeReadFile

• beforeMCPExecution

• preToolUse

It will signal the engine the action is not to be done, and you can provide your own messages for both the user (to display it) and the model (to consume it). So, a denial payload would look like this:

{
  "permission": "deny",
  "user_message": "Blocked by .cursor/hooks/no-hand-edited-migrations.sh",
  "agent_message": "Migrations are generated, not hand-edited. Change the model and re-run the generator."
}

You can decide if the action is to be allowed/forbidden or ask the user about it. It's being done using the permission property, you can assign it either allow, deny or ask. The two messages are for the user and the model respectively; the former one "displays to the end-user in the UI" and only the latter one "is fed back to the AI model when an action is denied".

If you were to set up a hook for the stop or subagentStop events you can use the followup_message property instead, which will be submitted as the next user input. There's a little "gotcha", though — by default the loop_limit property is set to 5, so if your hook keeps feeding followup messages back, anything past the fifth one is capped. Set it to null if you want to remove the cap.

The last thing is that the failClosed property of these guards is set to false by default. What it means is that if any of these hooks throws an error, the action is still being done. And if it happens before the hook emitted anything, the action isn't even being refused with a reason. So make sure to set failClosed: true for any guard you actually rely on.

In Gemini CLI

There are 2 ways of communicating decisions in the Gemini CLI — an exit code of 0 and JSON being printed to stdout (as per docs, it's "preferred for all logic"), or 2 which is the rough way and anything printed on stderr is the rejection message. For example:

{
  "decision": "deny",
  "reason": "Migrations are generated, not hand-edited. Change the model and re-run the generator.",
  "systemMessage": "Blocked by .gemini/hooks/no-hand-edited-migrations.sh"
}

— this is how you communicate a decision not to perform an action in Gemini, it includes a reason field which is a string and a systemMessage field with a name of the hook file.

The destination of the reason field changes for different hook events, and the docs are more explicit about it than most other tools:

• BeforeTool — the reason "is sent to the agent as a tool error, allowing it to respond or retry". Given that, it makes sense for the reason to say when it's pointless to try again.

• AfterTool — the reason "replaces the tool result sent back to the model".

• AfterAgent — the reason is "sent to the agent as a new prompt to request a correction".

Another channel is the systemMessage field, "displayed immediately to the user in the terminal". So they will see it straight away.

It's worth keeping in mind that the docs say "your script must not print any plain text to stdout other than the final JSON", so any debug log you left in the guard script is printing into the same channel your decision has to arrive on.

If you're using the consumer edition, you get the Antigravity CLI which is a different tool and has its own config file hooks.json located in the customisation directory (in the workspace — .agents/ — or ~/.gemini/config/) with slightly different options for the PreToolUse hook: allow, deny, ask, force_ask. The reason field is also optional and described as "the explanation shown to the agent or user for the decision".

But in Antigravity there's only one reason field so it's not possible to distinguish between the scenarios when it's used for communicating with the agent or the user.

In Kimi Code CLI

In Kimi Code your hook exits with status code 2 if it decides to deny the action, and writes the reason to stderr.

You can also return a deny payload in the form of JSON, which is exactly the shape Claude Code uses:

{
  "hookSpecificOutput": {
    "permissionDecision": "deny",
    "permissionDecisionReason": "Please use rg instead of grep"
  }
}

Moonshot uses this one: "Please use rg instead of grep", which we really like because it's pointing the model at what to do instead, in contrast to a second example from Moonshot docs: "Dangerous command detected, blocked" — such a message is not what we should aim for.

In terms of Kimi Code there are only three events that can be used to actually block an action, these are: PreToolUse, Stop and UserPromptSubmit; in other events (especially PostToolUse) the deny payload won't stop anything even if you write a really passionate message.

You can use Kimi Code hooks for alerting and some light interception but as written in the docs they "should not be used as the sole security barrier" — for anything genuinely high-risk they send you to permission approvals and manual confirmation instead.

The gotcha: setting up non-2 exit codes in a deny logic will not work as they will fall through to allow, also if you do something like throwing an error from a guard it'll just allow too without saying anything. Also be careful using the config file (config.toml) as it's very rigid, any unrecognised key will cause an error which means that entire config won't be loaded. For example if you were to add reason = "no grep here" to one of the [[hooks]] rules in the config file, you'd get hooks[0]: Unrecognized key: "reason" from kimi doctor config <path> and no hooks loaded at all. Run the validator after every edit — the reason belongs in the script's output, never in the rule.