Hooks Server Results and Errors
Every check the Guardrails hooks server (nemoguardrails hooks-server) runs ends in one of three outcomes: allow, deny, or error.
This page lists what each agent path returns for each outcome, the deny reasons, and the error responses.
Outcomes
The following table describes the response for each outcome:
For Claude Code and Codex, an allow carries no permission decision.
The hooks server never returns permissionDecision: "allow", which in Claude Code would skip the permission prompt.
The agent’s own permission rules still apply after an allow.
A deny for Claude Code and Codex has the following shape, with the reason prefixed with NeMo Guardrails: , so the agent’s model knows what blocked the call:
A deny for NeMo Relay carries the reason without a prefix:
The responses carry no other fields. Codex marks a hook whose output has a field it does not know as failed, and runs the tool.
Deny Reasons
The reason says what blocked the call:
A reason never quotes an argument’s value, or the name of an argument that only the agent chose. For the tool policy, refer to Run the Hooks Server: The Tool Policy.
Errors
A check that cannot finish is an error, not a deny. That happens when a per-tool rail fails instead of deciding, for example when a tool safety check cannot reach its judge model. The tool policy never fails, so a call it denies is a deny even when the tool’s rails would fail. A tool’s per-tool rails run in the order listed, and the first to block or to fail decides, so list a rail that can fail after the rails that cannot.
Every error response uses the OpenAI error envelope, the same as the Guardrails API server’s:
The following table lists HTTP error statuses and their causes:
The message names each failing field as body.<field>: <reason>, for example body.tool_use_id: Field required.
The agents do not read the error body; it is for logs and for people.
Retrying a check does not execute the agent’s tool, but it can repeat model or service calls made by the rails.
After a 503, wait for the number of seconds in Retry-After first.
Register the hooks server on PreToolUse only.
Any other event returns 422 unsupported_hook_event, and a hook that blocks on failure then blocks the action that event guards.
Block a Call When a Check Fails
The hooks server answers an error with a non-2xx status, and the agent decides what happens to the call.
Whether an error blocks the call or lets it run is set in the agent’s hook configuration, not by the hooks server.
The same setting decides what happens when the hooks server is down, restarting, or too slow to answer.
The following table describes how to block tool calls when a check fails:
These instructions apply to PreToolUse only.
Other events have different failure behavior. For example, Claude Code ignores onFailure on its Stop event.