Check Claude Code Tool Calls with the Hooks Server
Claude Code runs a PreToolUse hook before each tool call.
An HTTP hook sends the call to the Guardrails hooks server (nemoguardrails hooks-server) at /v1/hooks/claude-code, and Claude Code acts on the answer.
When the hooks server denies a call, Claude Code cancels it and shows the reason to Claude.
Prerequisites
Before you configure the hook, meet the following prerequisites:
-
Claude Code 2.1.295 or later, the first release with
onFailure: "block", which makes a failed check block the call. -
A running hooks server. To start one with the Claude Code example configuration, run the following command from a clone of the repository:
To write your own configuration, refer to Run the Hooks Server: Write a Hooks Configuration. If you list tools in
allowed_tools, setallow_unlisted_tools: falseto deny every tool you leave out: the hooks server refuses to start an allowlist that leaves it unset.
Add the Hook
Add an http hook on PreToolUse to a Claude Code settings file:
The hook settings have the following effects:
- The hook has no
matcher, so Claude Code runs it for every tool. onFailure: "block"blocks the call when the hook fails: an error status from the hooks server, a refused connection, or no answer withintimeout. Without it, Claude Code treats a failure as a non-blocking error and runs the tool.timeoutis in seconds. Without it, Claude Code waits up to 600 seconds. Set it to how long your slowest rail can take: a rail that calls a model, such as a tool safety check, takes longer than a regular expression.
If the hooks server runs on another port, for example because you run one server for each agent, change the port in url.
Choose the settings file by who the hook should cover:
Claude Code watches its settings files and applies hook changes to a running session.
Type /hooks in Claude Code to list the hooks it has loaded.
Allow the Hook URL
When any settings file, including managed settings, defines allowedHttpHookUrls, Claude Code runs an HTTP hook only if its URL matches one of the patterns.
If your organization sets it, add the hooks server’s URL:
Otherwise Claude Code does not run the hook, and no tool call reaches the hooks server.
Deploy the Hook with Managed Settings
Anyone who can edit a user’s or a project’s settings can remove the hook, point it at another server, or drop onFailure: "block".
To enforce the hook for every user, add it to Claude Code’s managed settings, such as managed-settings.json:
- Settings in other files cannot remove a managed hook, and a user’s
disableAllHookscannot turn it off. "allowManagedHooksOnly": truein managed settings stops every hook that does not come from managed settings.
For file locations and deployment through mobile device management (MDM) or server-managed settings, refer to managed settings in the Claude Code documentation.
Verify the Hook
- In Claude Code, type
/hooksand check that thePreToolUseHTTP hook is listed. - Ask Claude to run
echo 'rm -rf /tmp/guardrails-hook-check'. The example configuration blocks the command because its text matches therm -rfpattern. If the hook is missing or misconfigured, the command only prints text. Claude Code cancels the call, and Claude reports the reason,NeMo Guardrails: regex check tool call. - Stop the hooks server and ask Claude to run any command.
With
onFailure: "block", Claude Code blocks the call because the hook fails. - Start the hooks server again.
The hooks server logs one line for each tool call it checks, so you can follow the checks in its output.
What Claude Code Does with Each Outcome
Claude Code handles each hooks server response as follows:
The hooks server never returns permissionDecision: "allow", which would skip Claude Code’s permission prompt.
Your permission rules keep applying to every call the hooks server allows.
Claude Code Tool Names
The hooks server matches tool names exactly as Claude Code sends them:
An MCP tool from a plugin is named mcp__plugin_<plugin>_<server>__<tool>.
Claude Code also sends an mcp_server field with MCP calls, which says where the server’s definition came from.
The hooks server does not read it, so it identifies an MCP server only by the tool name’s prefix.
Some tool uses never reach the hook:
- Files you reference with
@in a prompt are added without a tool call, so noPreToolUsehook runs for them, including a check onRead. In Claude Code 2.1.299 or later, setCLAUDE_CODE_DISABLE_FILE_MENTIONS=1in user or managed settings to disable this automatic insertion. Claude then receives the paths with a note to read them using file tools, which run the hook. EndConversationcalls skip hooks.
Request and Response
The hooks server reads four fields from the Claude Code PreToolUse input: hook_event_name, tool_name, tool_input, and tool_use_id.
Claude Code also sends fields such as session_id, cwd, and permission_mode, which the hooks server accepts and ignores.
A request without one of the four fields gets HTTP 422.
The following example is the input Claude Code sends for a Bash command:
An allowed call gets an empty object, which carries no decision:
A denied call gets a deny decision, with the reason prefixed with NeMo Guardrails: :
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 Claude Code Tool Call.
Related Topics
- Run the Hooks Server
- Check Codex Tool Calls with the Hooks Server
- Hooks reference in the Claude Code documentation