Skip to navigation

Check NeMo Relay Tool Calls with the Hooks Server

View as MarkdownOpen in Claude

NeMo Relay plugins can register a tool conditional-execution guardrail, which Relay runs before each tool call it manages, with the tool’s name and arguments. A plugin can forward that check to the Guardrails hooks server (nemoguardrails hooks-server) at /v1/hooks/nemo-relay, so the hooks server’s tool policy and per-tool rails decide whether the call runs. This page describes the endpoint such a plugin calls. To install the plugin that calls this endpoint, refer to Check NeMo Relay Tool Calls with the NVIDIA NeMo Guardrails Plugin.

For how Relay runs these guardrails, refer to conditional execution in the NeMo Relay documentation.

Prerequisites

Before you connect your plugin, meet the following prerequisites:

  • NeMo Relay 0.10.1 or later. In 0.10.0, an error from the guardrail let a Claude Code tool call run.

  • A running hooks server. To start one with the NeMo Relay example configuration, run the following command from a clone of the repository:

    nemoguardrails hooks-server --config examples/configs/agent_hooks/nemo_relay

    The example checks an application tool, search: its tool policy allows only search with a query argument, and a per-tool rail blocks a search whose query is empty, missing, or not a string.

Request

Send POST /v1/hooks/nemo-relay with the three values the guardrail receives:

FieldTypeDescription
hook_event_namestringAlways NemoRelayToolConditionalExecutionGuardrail.
tool_namestringThe tool’s name, as Relay passes it to the guardrail. Not empty.
tool_inputAny JSON valueThe tool’s arguments, as Relay passes them to the guardrail. A value that is not a JSON object is denied.

The endpoint rejects any other field with HTTP 422.

curl -s http://localhost:8100/v1/hooks/nemo-relay \
-H "Content-Type: application/json" \
-d '{"hook_event_name": "NemoRelayToolConditionalExecutionGuardrail", "tool_name": "search", "tool_input": {"query": ""}}'

Response

An allowed call returns the following:

{"decision": "allow"}

A denied call returns the reason, without a prefix:

{"decision": "deny", "reason": "regex check tool call"}

The reason is the tool policy’s own reason, such as tool call 'search' passes 1 argument its allowed_tools entry doesn't list, or the name of the per-tool rail that blocked the call.

A check that cannot finish returns a non-2xx status with an error body. For every outcome and error, refer to Hooks Server Results and Errors. For the endpoint’s full reference, refer to Hooks Server API: Check a NeMo Relay Tool Call.

Map the Response to the Guardrail Result

The plugin returns the hooks server’s answer as the guardrail callback’s result:

Hooks Server ResponseGuardrail Callback ResultRelay Behavior
200 with "decision": "allow"Ok(None)Runs the tool
200 with "decision": "deny"Ok(Some(reason))Rejects the call with the reason
Any other status, an invalid decision body, a timeout, or a failed connectionErrTreats the guardrail as failed; what happens to the call depends on the integration

Map every failure to Err, never to Ok(None), so the plugin never reports a check that could not finish as an allow. What Relay then does with the call depends on the integration that runs the agent:

  • Relay’s Claude Code and Codex integrations block the call on Err from Relay 0.10.1. Through the Relay CLI’s gateway, the agent receives the plugin’s error inside Relay’s message. Through the managed Relay daemon, the agent receives only Relay’s own message. Refer to Check NeMo Relay Tool Calls with the NVIDIA NeMo Guardrails Plugin: Find the Reason for a Failed Check.
  • Relay’s standalone pi extension treats Err as a fault and lets the call run by default, with NEMO_RELAY_PI_FAIL=open. Set NEMO_RELAY_PI_FAIL=closed to block the call.
  • Relay’s managed pi extension blocks the call on Err and does not use NEMO_RELAY_PI_FAIL.

Tool Names

Relay forwards the names of whatever tools it wraps, and the hooks server matches them exactly. Behind Relay’s Claude Code or Codex integration, the names are that agent’s, so base the configuration on the Claude Code or Codex tool names.

Check Each Call Once

Account for the following sources of duplicate checks:

  • Use Relay or a direct agent hook, not both. With a Relay plugin and a direct Claude Code or Codex hook both pointed at hooks servers, every call is checked twice.
  • Relay 0.10 checks some calls twice. Through the 0.10 releases, Relay also runs the guardrail on Claude Code’s and Codex’s PermissionRequest event. A call that reaches a permission prompt then costs two requests to the hooks server, and two runs of any rail that calls a model. When the second check allows the call, Relay also approves Claude Code’s permission prompt, so Claude Code does not ask the user.