> This page is for version Latest (default).
> For other versions, use one of these documentation indexes:
> - Latest (default): https://docs.nvidia.com/nemo/guardrails/latest/llms.txt
> - v0.25.0: https://docs.nvidia.com/nemo/guardrails/v0.25.0/llms.txt
> - v0.24.1: https://docs.nvidia.com/nemo/guardrails/v0.24.1/llms.txt
> - v0.24.0: https://docs.nvidia.com/nemo/guardrails/v0.24.0/llms.txt
> - v0.23.0: https://docs.nvidia.com/nemo/guardrails/v0.23.0/llms.txt
> - v0.22.0: https://docs.nvidia.com/nemo/guardrails/v0.22.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/guardrails/llms.txt.

# Check NeMo Relay Tool Calls with the Hooks Server

> The /v1/hooks/nemo-relay endpoint of the Guardrails hooks server, for a NeMo Relay plugin's tool conditional-execution guardrail.

[NeMo Relay](https://github.com/NVIDIA/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](/nemo/guardrails/run-guardrailed-inference/using-hooks-server/nemo-relay-plugin).

For how Relay runs these guardrails, refer to [conditional execution](https://github.com/NVIDIA/NeMo-Relay/blob/494018ac4d6abb0085853a02f4b6d75a75ff7049/docs/about-nemo-relay/concepts/middleware.mdx?plain=1#L235) 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](https://github.com/NVIDIA-NeMo/Guardrails/tree/develop/examples/configs/agent_hooks/nemo_relay), run the following command from a clone of the repository:

  ```bash
  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:

| Field             | Type           | Description                                                                                               |
| ----------------- | -------------- | --------------------------------------------------------------------------------------------------------- |
| `hook_event_name` | string         | Always `NemoRelayToolConditionalExecutionGuardrail`.                                                      |
| `tool_name`       | string         | The tool's name, as Relay passes it to the guardrail. Not empty.                                          |
| `tool_input`      | Any JSON value | The 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`.

```bash
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:

```json
{"decision": "allow"}
```

A denied call returns the reason, without a prefix:

```json
{"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](/nemo/guardrails/run-guardrailed-inference/using-hooks-server/results-and-errors).
For the endpoint's full reference, refer to [Hooks Server API: Check a NeMo Relay Tool Call](/nemo/guardrails/reference/hooks-server-api/nemo-relay).

## Map the Response to the Guardrail Result

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

| Hooks Server Response                                                         | Guardrail Callback Result | Relay 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 connection | `Err`                     | Treats 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](/nemo/guardrails/run-guardrailed-inference/using-hooks-server/nemo-relay-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](/nemo/guardrails/run-guardrailed-inference/using-hooks-server/claude-code#claude-code-tool-names) or [Codex](/nemo/guardrails/run-guardrailed-inference/using-hooks-server/codex#codex-tool-names) 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.

## Related Topics

* [Run the Hooks Server](/nemo/guardrails/run-guardrailed-inference/using-hooks-server/run-hooks-server)
* [Hooks Server Results and Errors](/nemo/guardrails/run-guardrailed-inference/using-hooks-server/results-and-errors)