Skip to navigation

Gateway and Hook Reference

View as MarkdownOpen in Claude

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/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 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-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. 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:

AgentLLM Lifecycle and Correlation HooksScope, Tool, and Mark Hooks
Claude CodeUserPromptSubmit, Stop, StopFailureSessionStart, SessionEnd, UserPromptExpansion, SubagentStart, SubagentStop, PreToolUse, PostToolUse, PostToolUseFailure, Notification, PreCompact, PostCompact
CodexUserPromptSubmit, Stop, InterruptSessionStart, SessionEnd, SubagentStart, SubagentStop, PreToolUse, PostToolUse, PreCompact, PostCompact
pinone — pi’s LLM spans come from real gateway traffic, not from hookssession_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.