Gateway and Hook Reference
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. For endpoint selection and credentials, use Provider Connections and Provider 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/codexaccepts Codex hook JSON and returns the Codex-compatible hook response object.POST /hooks/claude-codeaccepts Claude Code hook JSON and returns the Claude-compatiblecontinueresponse after recording the hook.POST /hooks/piaccepts 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 witherror.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/responsesPOST /v1/chat/completionsPOST /v1/messagesPOST /v1/messages/count_tokensGET /v1/modelsPOST /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/liveandGET /v1/realtimewith a WebSocket upgrade (also available as/liveand/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 upstreamLocationheader. Connect tows://127.0.0.1:8000/v1/realtime?call_id=CALL_ID. - Codex Live: Create a call with
POST /v1/liveorPOST /v1/realtime/calls, using the format required by the upstream provider. Read the call ID from the upstreamLocationheader. Connect tows://127.0.0.1:8000/v1/live/CALL_ID. Relay preserves query parameters, includingintentandarchitecture. - Live: Create a session with
POST /v1/live/sessions. Readsession.idfrom the response. Connect tows://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 for the setting
and configuration locations.
Refer to OpenAI server-side 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.
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-onlyallows 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-metadatasetsx-nemo-relay-session-metadata.--profilesetsx-nemo-relay-config-profile.--gateway-modesetsx-nemo-relay-gateway-mode.--fail-openallows the agent to continue after a delivery failure, even whenNEMO_RELAY_FAIL_CLOSED=1is set. Structured guardrail rejections still return a failure.--fail-closedreturns 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.
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-profilex-nemo-relay-session-metadatax-nemo-relay-plugin-configx-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-levelScopeType::Agentscope. Claude Code uses bounded turn scopes. Codex opens a boundedcodex-taskagent scope for active work, with separate parent and child turns. Itssession.startmark waits for that exported task ancestor; other harnesses emit the mark at agent start. - Subagent start opens a child
ScopeType::Agentscope. 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
UserPromptSubmitandStophooks 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 throughStopFailure, and Codex reports interrupted turns throughInterrupt. 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-idx-nemo-relay-subagent-idx-nemo-relay-conversation-idx-nemo-relay-generation-idx-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:
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.