> This page is for NeMo Relay, version dev.
> For other versions, use one of these documentation indexes:
> - Latest (v0.11.2) (default): https://docs.nvidia.com/nemo/relay/latest/llms.txt
> - dev: https://docs.nvidia.com/nemo/relay/dev/llms.txt
> - v0.11.2: https://docs.nvidia.com/nemo/relay/v0.11.2/llms.txt
> - v0.10.4: https://docs.nvidia.com/nemo/relay/v0.10.4/llms.txt
> - v0.9.4: https://docs.nvidia.com/nemo/relay/v0.9.4/llms.txt
> - v0.8.4: https://docs.nvidia.com/nemo/relay/v0.8.4/llms.txt
> - v0.7.3: https://docs.nvidia.com/nemo/relay/v0.7.3/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/relay/llms.txt.

# Gateway and Hook Reference

> Look up gateway routes, hook delivery, lifecycle mapping, and trace propagation.

Use this reference to understand the hook payloads and provider routes accepted
by the Relay gateway, how requests map to lifecycle events, and how hook
delivery behaves.

For launch instructions, use the [coding agent guides](/nemo/relay/dev/nemo-relay-cli/about).
For endpoint selection and credentials, use
[Provider Connections](/nemo/relay/dev/nemo-relay-cli/provider-upstreams) and
[Provider Authentication](/nemo/relay/dev/nemo-relay-cli/authentication).

## Hook Endpoints

Each hook endpoint accepts the agent's native hook JSON directly. Do not wrap
the payload in a shared gateway envelope.

* `POST /hooks/codex` accepts Codex hook JSON and returns the Codex-compatible
  hook response object.
* `POST /hooks/claude-code` accepts Claude Code hook JSON and returns
  the Claude-compatible `continue` response after recording the hook.
* `POST /hooks/pi` accepts the hook JSON posted by the NeMo Relay pi extension.
  It returns an empty object for an allowed call, or
  `{"tool_call": {"tool_call_id": "…", "input": {…}}}` when a request intercept
  rewrote the arguments and the extension must execute those instead. It returns
  HTTP 403 with `error.type = "nemo_relay_guardrail_rejected"` when a guardrail
  blocks one.

When a hook closes a turn, subagent, or session scope, Relay returns the hook
response after subscribers finish processing that scope-end event. This makes
synchronous outputs such as the final ATIF trajectory visible at the hook
boundary without draining subscriber work queued later by another session.
Remote ATIF storage is the exception: Relay starts the upload and returns the hook
response without waiting for the receiver. A process-wide flush and plugin teardown
wait for it, so a one-shot `nemo-relay run` still waits at exit.
Full gateway shutdown uses a process-wide flush after closing all remaining
sessions and before clearing plugins.

The adapters preserve vendor fields such as session IDs, working directories,
transcript paths, model names, tool payloads, shell payloads, MCP payloads, file
payloads, user identity, and subagent metadata in NeMo Relay event metadata.

Compaction, notification, generic hook, and `skill.load.inferred` marks include
`session_id` and `session_instance_id` in their metadata, along with configured
and session metadata. The `prompt_submitted` mark emitted when a gateway request
opens the turn before the prompt hook includes the same metadata. Custom
subscribers can filter these marks by session without parsing the agent-specific
payload.

For fields copied from the hook payload into event metadata, non-null values
override configured and session metadata. Relay supplies the session identity
and harness type. Its non-null gateway and plugin settings take precedence.
Relay takes `agent_version` from the harness executable it launched. It omits
the field if no harness was launched or the session uses a different harness.

## Gateway Routes

The gateway supports these provider routes. Some routes record LLM lifecycle
events. The passthrough routes described below forward requests without those
events. Relay preserves provider JSON and forwards streaming responses as streams.
For managed LLM routes, it records LLM start and end events under the active
session scope. It removes headers used for the current network connection and
private Relay authentication and routing headers before forwarding requests.

* `POST /v1/responses`
* `POST /v1/chat/completions`
* `POST /v1/messages`
* `POST /v1/messages/count_tokens`
* `GET /v1/models`
* `POST /v1/live` (also available as `/live`)
* `POST /v1/live/sessions` (also available as `/live/sessions`)
* `POST /v1/images/edits` (also available as `/images/edits`)
* `POST /v1/memories/trace_summarize` (also available as `/memories/trace_summarize`)
* `POST /v1/alpha/search` (also available as `/alpha/search`)
* `POST /v1/realtime/calls` (also available as `/realtime/calls`)
* `POST /v1/responses/compact` (also available as `/responses/compact`)
* `GET /v1/live` and `GET /v1/realtime` with a WebSocket upgrade (also available
  as `/live` and `/realtime`)

### OpenShell Request Receipts

On managed model routes, the gateway records an `openshell.request.receipt`
mark when an upstream response contains exactly one valid UUID in
`x-openshell-request-id`. The mark belongs to the active model call and contains
only `request_id` and `http_status`. Capture happens before reading the body,
including for HTTP errors, so later body failures do not erase the receipt.
Retries can produce multiple receipts for one model call.

Use the request ID to find OpenShell records with the same
`metadata.correlation_uid`. A receipt is an unverified correlation hint, not
proof of identity, authorization, policy denial, or downstream execution.
OpenShell owns its enforcement trace; it does not adopt the workload's trace as
a trusted parent. The request ID join works independently of W3C context
propagation. Receipt capture does not change existing forwarding policy,
including the removal of `traceparent` and `tracestate` from credential-free
remote-HTTP model requests.

ATOF and the `full` and `openinference` trace projections retain these marks.
The `gen_ai` trace projection omits marks. Missing, malformed or duplicate
receipt headers produce no mark and do not change response handling.

This applies to model requests forwarded by the standalone gateway and daemon
workers. It does not instrument HTTP clients inside native agent processes,
tool subprocesses, passthrough routes or WebSocket frames. Those requests need
their own context propagation and receipt capture.

### Passthrough Requests

Voice call setup, Responses compaction, image editing, memory summarization, and
experimental standalone search use passthrough mode. Relay forwards these
requests without recording LLM lifecycle events or changing their contents.
It preserves request bodies, including multipart data and Session Description
Protocol (SDP) offers. For voice calls, it also preserves the upstream SDP answer
and `Location` header.

Live and Realtime WebSockets use passthrough mode in the standalone gateway and
daemon. Relay checks the caller's credentials and connects to the upstream before
accepting the client's connection. It removes private Relay headers and forwards
WebSocket frames in both directions. The daemon keeps the selected worker assigned
until the connection closes. It closes active connections when the worker's drain
deadline expires.

### WebRTC Sidebands

A sideband is a WebSocket connection used to send session events and commands.
WebRTC carries the primary audio. Your application runs tools and sends session
updates.

Use the following routes to create a call or session and attach its sideband.
These examples use a local gateway at `127.0.0.1:8000`.

* **Realtime:** Create a call with `POST /v1/realtime/calls`. Read the call ID from
  the upstream `Location` header. Connect to
  `ws://127.0.0.1:8000/v1/realtime?call_id=CALL_ID`.
* **Codex Live:** Create a call with `POST /v1/live` or
  `POST /v1/realtime/calls`, using the format required by the upstream provider.
  Read the call ID from the upstream `Location` header. Connect to
  `ws://127.0.0.1:8000/v1/live/CALL_ID`. Relay preserves query parameters,
  including `intent` and `architecture`.
* **Live:** Create a session with `POST /v1/live/sessions`. Read `session.id` from
  the response. Connect to
  `ws://127.0.0.1:8000/v1/live/sessions/SESSION_ID/attach`.

Keep the returned ID unchanged. Use the credentials required by the upstream
and the same Relay route credential for creation and attachment. Codex can use
separate destinations for ChatGPT call creation and the OpenAI sideband.
Live and Realtime connections use Relay's configured OpenAI upstream and keep
the caller's provider credential.

Live attach also supports `/live/sessions/SESSION_ID/attach`. Codex Live also
supports `/live/CALL_ID`. In the standalone gateway, each HTTP passthrough route
listed above and each sideband route supports the capability prefix
`/v1/nemo-relay/CAPABILITY`. For example, use
`/v1/nemo-relay/CAPABILITY/live/CALL_ID` to attach a Codex Live sideband.

To send a Codex WebRTC sideband through Relay, set
`experimental_realtime_ws_base_url` to the Relay base URL in your user-level
Codex settings. Codex can choose its sideband URL separately from its model
provider URL. Relay does not set this option for you.

Relay forwards voice requests in the format it receives. Codex chooses ChatGPT's
JSON call format when its call-creation base URL contains `/backend-api`.
A local Relay URL without that path selects the public API format instead.
For personal persistent installs with ChatGPT sign-in, Relay sets a separate
call-creation URL ending in `/backend-api/codex`. It preserves an explicit
call-creation URL that you already set.

For a managed daemon deployment, set
`experimental_realtime_webrtc_call_base_url` manually to the Relay URL ending
in `/backend-api/codex`. Keep the model provider's `/v1` URL. Refer to
[Managed Codex Configuration](/nemo/relay/dev/daemon/configuration#codex) for the setting
and configuration locations.

Refer to [OpenAI server-side controls](https://developers.openai.com/api/docs/guides/voice-server-controls)
for details about the provider's sideband lifecycle.

### Unmatched Routes

When a request does not match a supported Relay path or method, Relay logs a
`route_unmatched` record at error level. The record identifies the gateway,
daemon, or worker that handled the request. It includes the HTTP method and
response status.
The path is `/<redacted>`, or `/v1/nemo-relay/<redacted>` for requests in the
capability namespace. Relay does not log caller-supplied path segments, query
strings, headers, or bodies. An upstream 404 response does not produce this
record.

## Hook Forwarding

Transparent Claude Code and Codex hooks invoke
`nemo-relay hook-forward <agent>` with the canonical payload on standard input.
The wrapper writes a private hook configuration file at
`<system-temp>/nemo-relay-claude-plugin-<uuid>/.nemo-relay-hook-config.json` for
Claude Code or
`<system-temp>/nemo-relay-codex-hooks-<uuid>/.nemo-relay-hook-config.json` for Codex.
`<system-temp>` is the operating system's temporary directory, and `<uuid>` is
generated for each run. The file contains the gateway URL and hook delivery
settings. The generated
command passes its path through `--hook-config`; `hook-forward` reads it when
the coding agent invokes the hook. The command is marked as transparent so it
cannot recover the fixed gateway.

Persistent Claude Code and Codex hooks also use
`nemo-relay hook-forward <agent>`. Each generated command identifies the fixed
gateway and its private install-generation fence, waits for the MCP-owned Relay
gateway, verifies it, and forwards the unchanged payload once.

`hook-forward` reads the canonical hook payload from standard input, sends it
to the matching endpoint, and prints the endpoint response. Generated
`PreToolUse` hooks use `--fail-closed`; generated observability hooks use
`--fail-open`. This blocks tools when
Relay cannot evaluate them without making observability-only hooks a runtime
dependency.
Rerun `nemo-relay install <agent> --force` after upgrading to replace legacy
generated hooks.

Hook forwarding uses a 30-second request timeout in gateway and daemon modes,
including delivery to daemon workers. Generated Claude Code and Codex hook
configs use the same 30-second limit. This allows LLM judge guardrails to take
longer than two seconds; configure their evaluation timeouts to leave room for
hook transport within that limit. Delivery timeouts follow the hook's failure
policy, and timed-out requests are not retried.

The failure-policy and exit-code rules below do not apply to
`hook-forward pi --pi-extension-client`. That mode exits successfully when it
receives an HTTP response with a readable body, including a `403` guardrail
rejection. Inspect the returned `status` and `body` envelope to determine the
verdict. See the [pi forwarding example](/nemo/relay/dev/nemo-relay-cli/pi#smoke-test).

Without a policy flag, gateway and daemon hooks fail closed for events that
run tools, including `PreToolUse`. Hooks also fail closed if Relay cannot read
the payload,
parse its JSON, or find an event name. Payloads that exceed the size limit
also fail closed. Other named events fail open.

Set `NEMO_RELAY_FAIL_CLOSED=1` to make all events fail closed. An explicit
`--fail-open` or `--fail-closed` flag overrides the environment and event defaults.

For local hook requests, Relay checks the server's identity before sending
credentials or payloads. It uses an encrypted TLS connection and a saved
certificate for your user account. Gateway health checks also verify the
server's address and running instance. Restart Relay gateways and daemons
after upgrading to use this transport.

Fail-closed delivery failures return exit code `2`, including connection errors,
timeouts, and HTTP errors such as a daemon's `503` response when a required
worker is unavailable. This applies to gateway hooks and managed daemon hooks,
including hooks routed through a daemon worker. Fail-open delivery failures
return exit code `0`; structured guardrail rejections return exit code `2` under
either policy.

These flags control delivery and metadata:

* `--gateway-url <url>` selects the Relay gateway that receives the payload.
* `--forward-only` allows source plugins and custom automation to use an
  existing compatible gateway without an installer-owned generation fence. It
  verifies the gateway but never launches or recovers Relay. Generated
  installed hooks use a private generation fence instead.
* `--session-metadata` sets `x-nemo-relay-session-metadata`.
* `--profile` sets `x-nemo-relay-config-profile`.
* `--gateway-mode` sets `x-nemo-relay-gateway-mode`.
* `--fail-open` allows the agent to continue after a delivery failure, even
  when `NEMO_RELAY_FAIL_CLOSED=1` is set. Structured guardrail rejections still
  return a failure.
* `--fail-closed` returns a failure when delivery fails or Relay rejects the
  hook.

### Continue the Launcher Trace

A host process can launch Claude Code or Codex with the standard
OpenTelemetry `TRACEPARENT` and optional `TRACESTATE` environment variables.
The agent runs its hook commands with that environment. `hook-forward` and
`nemo-relay daemon hook` send the values as W3C `traceparent` and `tracestate`
request headers.

The hook that creates a session sets the session's remote parent. Top-level
session scopes, such as the Codex `codex-task` scope or a Claude Code turn,
export as children of the launcher's span. Their child spans stay in the
launcher's trace. Later hooks for an open session do not change its parent.
When the session ends, the next hook starts a new session with the context
it carries.

Relay validates the pair as described in
[Cross-Process Propagation](/nemo/relay/dev/about-nemo-relay/concepts/scopes#cross-process-propagation).
It ignores an invalid `traceparent` and keeps the session in a new trace
without failing the hook. Relay ignores trace headers on provider requests for
this purpose, because they describe a single request, not the launcher.

### Forwarded Session Settings

`hook-forward` can also pass per-session configuration through headers:

* `x-nemo-relay-config-profile`
* `x-nemo-relay-session-metadata`
* `x-nemo-relay-plugin-config`
* `x-nemo-relay-gateway-mode`

The accepted gateway mode values are `hook-only`, `passthrough`, and
`required`. The gateway records this value as session metadata so downstream
exporters and review tooling can distinguish hook-only traces from sessions
where provider traffic was expected to pass through the gateway.

## Runtime Mapping

The gateway normalizes vendor hook payloads into private internal events before
calling NeMo Relay APIs.

* Agent start records session metadata on a dedicated `ScopeStackHandle`.
  Harnesses with a reliable session boundary also open a top-level
  `ScopeType::Agent` scope. Claude Code uses bounded turn scopes. Codex opens a
  bounded `codex-task` agent scope for active work, with separate parent and child
  turns. Its `session.start` mark waits for that exported task ancestor; other
  harnesses emit the mark at agent start.
* Subagent start opens a child `ScopeType::Agent` scope. Subagent stop closes
  that scope when it is still active.
* Tool pre-use evaluates conditional-execution guardrails before starting a
  NeMo Relay tool span. A rejection blocks the tool. Tool post-use, denial, or
  failure closes the span.
* Generated `UserPromptSubmit` and `Stop` hooks are retained as private
  correlation hints. The adapters
  do the same when a custom or older integration delivers a response or
  agent-thought hook. These hints are not emitted as NeMo Relay events.
* Compaction, notification, and unknown hook events become mark events under
  the active session scope.
* Harnesses that report the *start* of a turn as well as its end open the turn
  scope at that signal instead of lazily. pi does; Claude Code and Codex report
  turn completion through `Stop`, so their turns stay lazily opened by the
  first event of the turn. Claude Code also reports failed turns through
  `StopFailure`, and Codex reports interrupted turns through `Interrupt`. Both
  close the turn with an error while retaining the session.
  For a harness with an explicit turn start, a mark that arrives between turns
  is recorded on the session scope rather than opening a turn to hold it.
* Gateway requests emit NeMo Relay LLM start and end events under the active
  session scope. Before each LLM start, the gateway uses explicit subagent
  headers, pending hints, shared conversation/generation/request identifiers,
  and the previous correlated owner to choose the parent scope.
* LLM responses that contain future tool-use suggestions are retained as
  private tool-call hints. The next matching tool hook can then inherit the
  subagent scope that owned the LLM response, even when the hook payload does
  not include a subagent id.

Gateway requests can provide explicit correlation identifiers with these
headers:

* `x-nemo-relay-session-id`
* `x-nemo-relay-subagent-id`
* `x-nemo-relay-conversation-id`
* `x-nemo-relay-generation-id`
* `x-nemo-relay-request-id`

When those headers are absent, the gateway also looks for
`conversation_id`/`conversationId`/`conversation.id`,
`generation_id`/`generationId`/`generation.id`, and
`request_id`/`requestId`/`request.id` fields in the provider request body.
Correlation hints expire after five minutes. If the gateway cannot select one
unambiguous hint, it falls back to the previous LLM owner, then to the only
active subagent, then to the top-level agent scope.

Every gateway LLM event includes `llm_correlation_status` metadata. Managed
requests can use `explicit`, `single_hint`, `matched_hint`,
`request_affinity`, `sticky_last_owner`, `recent_tool_owner`,
`subagent_start`, `active_subagent`, `agent_fallback`, or
`ambiguous_fallback`. Known Claude Code internal requests without an explicit
child use `harness_internal`; their reported class is recorded separately as
`claude_code_request_class`. Matched hints can also add
`llm_correlation_source`, `llm_correlation_subagent_id`,
`llm_correlation_conversation_id`, `llm_correlation_generation_id`,
`llm_correlation_request_id`, and `llm_correlation_agent_type`.

Generated hook bundles subscribe to the events needed for that mapping. pi has
no generated bundle — its extension posts these names directly:

| Agent       | LLM Lifecycle and Correlation Hooks                                  | Scope, Tool, and Mark Hooks                                                                                                                                                                                                                                              |
| ----------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Claude Code | `UserPromptSubmit`, `Stop`, `StopFailure`                            | `SessionStart`, `SessionEnd`, `UserPromptExpansion`, `SubagentStart`, `SubagentStop`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `Notification`, `PreCompact`, `PostCompact`                                                                                     |
| Codex       | `UserPromptSubmit`, `Stop`, `Interrupt`                              | `SessionStart`, `SessionEnd`, `SubagentStart`, `SubagentStop`, `PreToolUse`, `PostToolUse`, `PreCompact`, `PostCompact`                                                                                                                                                  |
| pi          | none — pi's LLM spans come from real gateway traffic, not from hooks | `session_start`, `session_shutdown`, `agent_start`, `agent_end`, `agent_settled`, `turn_start`, `turn_end`, `session_before_compact`, `session_compact`, `model_redirect`, `tool_call`, `tool_arguments_transformed`, `tool_execution_end`, `user_bash`, `user_bash_end` |

Three of pi's names are not pi hooks. The extension posts `model_redirect` after
deciding whether to point the active model's provider at the gateway, from
`session_start` and from every `model_select`; `tool_arguments_transformed` after
applying a request intercept's rewrite; and `user_bash_end` to close the
inline-shell span, because pi reports no completion for it. pi's own
`tool_execution_start` is deliberately never forwarded — it fires before argument
validation and for calls that never execute, so the extension uses it only to
remember a tool name for the matching end.