Skip to navigation

Hooks Server Results and Errors

View as MarkdownOpen in Claude

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:

OutcomeMeaning/v1/hooks/claude-code and /v1/hooks/codex/v1/hooks/nemo-relay
AllowThe call passed the tool policy and every per-tool rail200 with {}200 with {"decision": "allow"}
DenyThe call’s shape, the tool policy, or a per-tool rail blocked the call200 with permissionDecision: "deny" and the reason200 with {"decision": "deny", "reason": ...}
ErrorThe check could not finish, so the call’s safety is unknownA non-2xx statusA non-2xx status

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:

{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "NeMo Guardrails: tool call 'WebFetch' is a blocked tool"
}
}

A deny for NeMo Relay carries the reason without a prefix:

{"decision": "deny", "reason": "tool call 'WebFetch' is a blocked tool"}

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:

Blocked ByReason
tool_input is not a JSON objecttool call 'Bash' has arguments that aren't a JSON object
blocked_tools names the tooltool call 'WebFetch' is a blocked tool
blocked_tools lists an argument the call passestool call 'Bash' passes argument 'run_in_background', which is blocked
allowed_tools does not name the tool, and allow_unlisted_tools is falsetool call 'TodoWrite' is not an allowed tool
The tool’s allowed_tools entry does not list arguments the call passestool call 'search' passes 2 arguments its allowed_tools entry doesn't list
A per-tool railThe rail’s name, such as regex check tool 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:

{
"error": {
"message": "rail 'tool safety check tool call' failed: tool safety check tool call error: Connection error.",
"type": "server_error",
"param": null,
"code": "rail_failed"
}
}

The following table lists HTTP error statuses and their causes:

StatuscodeparamWhen
422nullnullThe body is not JSON, or is not a JSON object.
422nullhook_event_namehook_event_name is missing, or is not a string.
422unsupported_hook_eventhook_event_nameThe path does not handle the event, such as PostToolUse.
422nullThe fieldA required field is missing or invalid, such as an empty tool_name, or the NeMo Relay request carries a field the endpoint does not accept.
500rail_failednullA per-tool rail failed, including a rail’s model call.
500nullnullThe check failed for another reason, or the server hit an unexpected error.
503queue_fullnullThe server’s admission queue is full. The response carries Retry-After: 30.

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:

AgentDefault Error BehaviorConfiguration to Block the Call on Error
Claude CodeIs a non-blocking error, and the tool runsSet onFailure: "block" on the hook. Refer to Claude Code: Add the Hook.
CodexLets the tool run, unless the hook command exits 2; a hook that times out lets it run tooPass curl the -f option and a --max-time below the hook’s timeout, and end the command with || exit 2. Refer to Codex: Add the Hook.
NeMo RelayDepends on the plugin and the integrationThe plugin returns Err from the guardrail callback for a failed check. From Relay 0.10.1, the Claude Code and Codex integrations block the call on Err. The managed pi extension also blocks it. The standalone pi extension lets it run unless you set NEMO_RELAY_PI_FAIL=closed. Refer to Check NeMo Relay Tool Calls with the NVIDIA NeMo Guardrails Plugin: What Happens to a Call.

These instructions apply to PreToolUse only. Other events have different failure behavior. For example, Claude Code ignores onFailure on its Stop event.