Skip to navigation

The hooks server: checks the tool call in each agent hook with one config’s tool-call rails, on IORails.

Module Contents

Classes

NameDescription
HooksConfigErrorA config the hooks server can’t serve, found before it answers any request.

Functions

NameDescription
_answer_hookCheck the tool call the hook carries, and answer with the agent’s allow or deny, or an error status.
_build_engineThe server’s IORails engine for config, never LLMRails, which can’t run tool checks.
_check_allowlist_sets_unlisted_tools_choiceRaise when hooks_server.allowed_tools lists tools but leaves allow_unlisted_tools to its default.
_check_main_modelRaise unless a tool-call rail uses any main model, and tool lists replace the tools it declares.
_check_no_global_tool_call_railsRaise when rails.tool_call.flows lists a rail, which can’t deny a call the tool policy allows.
_check_per_tool_rails_can_runRaise when the tool policy denies every call to a tool that per-tool rails are configured for.
_check_something_can_denyRaise unless the tool policy or a per-tool rail can deny a call, since otherwise every call is allowed.
_check_tool_callDecide the hook’s call with the tool policy, then run its tool’s per-tool rails on it, and log the verdict.
_has_per_tool_railsWhether config lists a per-tool rail for any tool’s calls.
_lifespanStart the metrics exporter and the engine before the server accepts requests, and stop them on shutdown.
_log_checkLog one line for a check, without the tool’s input; an error, which no rail decided, as a warning.
_main_modelconfig’s main model, or None without one.
_parse_hookThe tool call body asks to check on adapter’s path, raising a failure for the shared 422 handler.
_read_jsonThe request body as JSON, whatever its Content-Type says.
_tool_call_rails_use_modelWhether a global or per-tool tool-call rail names model_type with $model=.
_unsupported_hook_event_handlerAnswer a hook_event_name the path doesn’t handle with 422 unsupported_hook_event.
_warn_about_ignored_main_model_toolsWarn that the hooks server ignores the tools a main model declares, since the tool policy replaces them.
_warn_if_the_config_records_no_metricsWarn that the scrape endpoint will show no guardrails metrics, when the config doesn’t turn them on.
check_hooks_configRaise HooksConfigError unless IORails can serve config, it can deny a call, its rails and main run, and
create_hooks_appBuild the hooks server for config, with its own engine; raises HooksConfigError if it can’t serve hooks.
handle_claude_code_hookAnswer a Claude Code hook in Claude Code’s hook output format.
handle_codex_hookAnswer a Codex hook in Codex’s hook output format.
handle_nemo_relay_hookAnswer a NeMo Relay tool conditional-execution guardrail with its decision.
healthReturn HTTP 200 while the server process is running and able to serve requests.
metrics_exporter_settingsThe NEMO_GUARDRAILS_SERVER_METRICS_* exporter settings, with the hooks server’s defaults for those unset.

Data

_EXCEPTION_HANDLERS

_METRICS_DEFAULTS

_MODEL_CALL_ERRORS

_TOOL_POLICY

_router

log

API

class nemoguardrails.server.hooks.app.HooksConfigError()

Bases: ConfigurationError

A config the hooks server can’t serve, found before it answers any request.

nemoguardrails.server.hooks.app._answer_hook(
request: fastapi.Request
) -> starlette.responses.Response
async

Check the tool call the hook carries, and answer with the agent’s allow or deny, or an error status.

nemoguardrails.server.hooks.app._build_engine(

The server’s IORails engine for config, never LLMRails, which can’t run tool checks.

nemoguardrails.server.hooks.app._check_allowlist_sets_unlisted_tools_choice(
) -> None

Raise when hooks_server.allowed_tools lists tools but leaves allow_unlisted_tools to its default.

nemoguardrails.server.hooks.app._check_main_model(
) -> None

Raise unless a tool-call rail uses any main model, and tool lists replace the tools it declares.

nemoguardrails.server.hooks.app._check_no_global_tool_call_rails(
) -> None

Raise when rails.tool_call.flows lists a rail, which can’t deny a call the tool policy allows.

nemoguardrails.server.hooks.app._check_per_tool_rails_can_run(
) -> None

Raise when the tool policy denies every call to a tool that per-tool rails are configured for.

nemoguardrails.server.hooks.app._check_something_can_deny(
) -> None

Raise unless the tool policy or a per-tool rail can deny a call, since otherwise every call is allowed.

async

Decide the hook’s call with the tool policy, then run its tool’s per-tool rails on it, and log the verdict.

nemoguardrails.server.hooks.app._has_per_tool_rails(
) -> bool

Whether config lists a per-tool rail for any tool’s calls.

nemoguardrails.server.hooks.app._lifespan(
app: fastapi.FastAPI
) -> typing.AsyncIterator[None]
async

Start the metrics exporter and the engine before the server accepts requests, and stop them on shutdown.

nemoguardrails.server.hooks.app._log_check(
rail: typing.Optional[str]
) -> None

Log one line for a check, without the tool’s input; an error, which no rail decided, as a warning.

nemoguardrails.server.hooks.app._main_model(

config’s main model, or None without one.

nemoguardrails.server.hooks.app._parse_hook(
body: object

The tool call body asks to check on adapter’s path, raising a failure for the shared 422 handler.

nemoguardrails.server.hooks.app._read_json(
request: fastapi.Request
) -> object
async

The request body as JSON, whatever its Content-Type says.

nemoguardrails.server.hooks.app._tool_call_rails_use_model(
model_type: str
) -> bool

Whether a global or per-tool tool-call rail names model_type with $model=.

nemoguardrails.server.hooks.app._unsupported_hook_event_handler(
request: fastapi.Request,
) -> starlette.responses.Response
async

Answer a hook_event_name the path doesn’t handle with 422 unsupported_hook_event.

nemoguardrails.server.hooks.app._warn_about_ignored_main_model_tools(
) -> None

Warn that the hooks server ignores the tools a main model declares, since the tool policy replaces them.

nemoguardrails.server.hooks.app._warn_if_the_config_records_no_metrics(
) -> None

Warn that the scrape endpoint will show no guardrails metrics, when the config doesn’t turn them on.

nemoguardrails.server.hooks.app.check_hooks_config(
) -> None

Raise HooksConfigError unless IORails can serve config, it can deny a call, its rails and main run, and an allowlist says whether unlisted tools are allowed.

nemoguardrails.server.hooks.app.create_hooks_app(
) -> fastapi.FastAPI

Build the hooks server for config, with its own engine; raises HooksConfigError if it can’t serve hooks.

nemoguardrails.server.hooks.app.handle_claude_code_hook(
request: fastapi.Request
) -> starlette.responses.Response
async

Answer a Claude Code hook in Claude Code’s hook output format.

nemoguardrails.server.hooks.app.handle_codex_hook(
request: fastapi.Request
) -> starlette.responses.Response
async

Answer a Codex hook in Codex’s hook output format.

nemoguardrails.server.hooks.app.handle_nemo_relay_hook(
request: fastapi.Request
) -> starlette.responses.Response
async

Answer a NeMo Relay tool conditional-execution guardrail with its decision.

nemoguardrails.server.hooks.app.health() -> starlette.responses.Response
async

Return HTTP 200 while the server process is running and able to serve requests.

nemoguardrails.server.hooks.app.metrics_exporter_settings(
environ: typing.Optional[typing.Mapping[str, str]] = None

The NEMO_GUARDRAILS_SERVER_METRICS_* exporter settings, with the hooks server’s defaults for those unset.

nemoguardrails.server.hooks.app._EXCEPTION_HANDLERS = ((UnsupportedHookEventError, _unsupported_hook_event_handler), (NonStreamingWork...
nemoguardrails.server.hooks.app._METRICS_DEFAULTS = MetricsExporterSettings(host='127.0.0.1', port=9465, service_name='nemoguardrail...
nemoguardrails.server.hooks.app._MODEL_CALL_ERRORS = (LLMCallException, ModelEngineError, HTTPClientError)
nemoguardrails.server.hooks.app._TOOL_POLICY = 'tool policy'
nemoguardrails.server.hooks.app._router = APIRouter()
nemoguardrails.server.hooks.app.log = logging.getLogger(__name__)