Events Reference

Events are the session protocol between your application and a managed Herm agent. Use POST /v1/sessions/{sessionId}/events to send user.* events. Use GET /v1/sessions/{sessionId}/events and GET /v1/sessions/{sessionId}/events/stream to receive agent.* and session.* events.

Event envelope

Every listed or streamed event is wrapped in an envelope:

{
  "id": "evt_123",
  "type": "agent.message",
  "sessionId": "session_123",
  "sequence": 6,
  "status": "complete",
  "payload": {
    "type": "agent.message",
    "delta": false,
    "content": [{ "type": "text", "text": "Hello!" }]
  },
  "processedAt": "2026-06-20T23:28:02.772Z",
  "createdAt": "2026-06-20T23:28:02.773Z"
}

Field	Type	Description
`id`	string	Gateway event ID.
`type`	string	Event type, duplicated from `payload.type`.
`sessionId`	string	Session ID.
`sequence`	integer	Monotonic sequence number within the session.
`status`	string	Event processing status.
`payload`	object	Event-specific payload.
`processedAt`	string	ISO timestamp when processing completed, when available.
`createdAt`	string	ISO timestamp when the event was created.

Shared types

Text content block

{ "type": "text", "text": "Hello" }

Text content arrays contain 1 to 100 text blocks. Each text value can be up to 20,000 characters.

Stop reason

session.status_idle.stop_reason is one of:

{ "type": "end_turn" }

{ "type": "error", "message": "The runtime failed." }

{ "type": "requires_action", "event_ids": ["custom_toolu_123"] }

When type is requires_action, send the matching user.* response event.

User events

User events are accepted by POST /v1/sessions/{sessionId}/events.

`user.message`

Starts a new agent turn.

{
  "type": "user.message",
  "content": [{ "type": "text", "text": "Say hello in one sentence." }]
}

Field	Type	Required	Description
`type`	string	Yes	Must be `user.message`.
`content`	text block[]	Yes	User message content.

Only one user.message is allowed per request. A new user.message is rejected while another turn is already running.

`user.steer`

Adds steering text to the current session without starting a normal prompt.

{
  "type": "user.steer",
  "message": "Keep the answer short and cite files you change."
}

Field	Type	Required	Description
`type`	string	Yes	Must be `user.steer`.
`message`	string	Yes	Steering instruction.

`user.interrupt`

Interrupts the active turn.

{
  "type": "user.interrupt",
  "message": "Stop this run."
}

Field	Type	Required	Description
`type`	string	Yes	Must be `user.interrupt`.
`message`	string	No	Optional reason or UI note.

`user.tool_confirmation`

Allows or denies a built-in or MCP tool call that requires approval.

{
  "type": "user.tool_confirmation",
  "tool_use_id": "toolu_123",
  "result": "allow",
  "scope": "once"
}

Field	Type	Required	Description
`type`	string	Yes	Must be `user.tool_confirmation`.
`tool_use_id`	string	Yes	`id` from `agent.tool_use` or `agent.mcp_tool_use`.
`result`	string	Yes	`allow` or `deny`.
`scope`	string	No	`once`, `session`, or `always`. Defaults to `once` when omitted.

`user.custom_tool_result`

Returns the result of an application-owned custom tool.

{
  "type": "user.custom_tool_result",
  "tool_use_id": "custom_toolu_123",
  "content": [{ "type": "text", "text": "Order #123 ships tomorrow." }],
  "is_error": false
}

Field	Type	Required	Description
`type`	string	Yes	Must be `user.custom_tool_result`.
`tool_use_id`	string	Yes	`id` from `agent.custom_tool_use`.
`content`	text block[]	Yes	Tool result content shown to the model.
`is_error`	boolean	No	Defaults to `false`. Set to `true` when your tool failed.

`user.clarify_result`

Answers an agent clarification request.

{
  "type": "user.clarify_result",
  "request_id": "clarify_123",
  "answer": "Use the production environment."
}

Field	Type	Required	Description
`type`	string	Yes	Must be `user.clarify_result`.
`request_id`	string	Yes	`request_id` from `agent.clarify_request`.
`answer`	string	Yes	User answer. Empty string means skip.

`user.sudo_result`

Supplies a sudo password for a blocked runtime request.

{
  "type": "user.sudo_result",
  "request_id": "sudo_123",
  "password": "correct-horse-battery-staple"
}

Field	Type	Required	Description
`type`	string	Yes	Must be `user.sudo_result`.
`request_id`	string	Yes	Runtime request ID.
`password`	string	Yes	Password value forwarded to Hermes.

`user.secret_result`

Supplies a requested secret value.

{
  "type": "user.secret_result",
  "request_id": "secret_123",
  "value": "secret-value"
}

Field	Type	Required	Description
`type`	string	Yes	Must be `user.secret_result`.
`request_id`	string	Yes	Runtime request ID.
`value`	string	Yes	Secret value forwarded to Hermes.

Session events

Session events describe turn status and session metadata changes.

`session.status_running`

The agent turn is running.

{ "type": "session.status_running" }

`session.status_idle`

The agent turn ended, errored, or paused for required action.

{
  "type": "session.status_idle",
  "stop_reason": { "type": "end_turn" }
}

{
  "type": "session.status_idle",
  "stop_reason": {
    "type": "requires_action",
    "event_ids": ["custom_toolu_123"]
  }
}

Field	Type	Description
`type`	string	`session.status_idle`.
`stop_reason`	object	Why the turn is idle.

`session.title_updated`

Live-only event emitted when the gateway generates a session title.

{
  "type": "session.title_updated",
  "title": "Holiday campaign planning"
}

This event is not stored in the persisted event history.

Agent events

Agent events are emitted by the Hermes runtime through the gateway.

`agent.message`

Assistant response content.

{
  "type": "agent.message",
  "content": [{ "type": "text", "text": "Hello!" }],
  "delta": false
}

Field	Type	Description
`content`	text block[]	Assistant text.
`delta`	boolean	`true` for streaming chunks, `false` for complete durable messages.

`agent.thinking`

Reasoning content emitted by the model or runtime.

{
  "type": "agent.thinking",
  "content": [{ "type": "text", "text": "I need to inspect the repo." }],
  "delta": true
}

Field	Type	Description
`content`	text block[]	Reasoning text.
`delta`	boolean	`true` for streaming chunks, `false` for finalized durable reasoning.

`agent.tool_use`

Built-in Hermes tool call.

{
  "type": "agent.tool_use",
  "id": "toolu_123",
  "tool": "terminal",
  "input": { "command": "pwd" },
  "status": "running",
  "preview": "pwd",
  "requires_action": true
}

Field	Type	Description
`id`	string	Tool use ID.
`tool`	string	Tool name.
`input`	object	Tool input.
`status`	string	Currently `running`.
`preview`	string	Optional human-readable preview.
`requires_action`	boolean	Present when the tool requires `user.tool_confirmation`.

`agent.tool_result`

Built-in Hermes tool result.

{
  "type": "agent.tool_result",
  "tool_use_id": "toolu_123",
  "tool": "terminal",
  "status": "completed",
  "content": [{ "type": "text", "text": "/workspace" }],
  "is_error": false
}

Field	Type	Description
`tool_use_id`	string	ID of the matching `agent.tool_use`.
`tool`	string	Tool name.
`status`	string	`completed` or `failed`.
`content`	text block[]	Tool result text.
`is_error`	boolean	Whether the tool result is an error.

`agent.mcp_tool_use`

MCP tool call. Shape matches agent.tool_use.

{
  "type": "agent.mcp_tool_use",
  "id": "mcptoolu_123",
  "tool": "mcp_github_create_issue",
  "input": { "title": "Bug" },
  "status": "running",
  "requires_action": true
}

`agent.mcp_tool_result`

MCP tool result. Shape matches agent.tool_result.

{
  "type": "agent.mcp_tool_result",
  "tool_use_id": "mcptoolu_123",
  "tool": "mcp_github_create_issue",
  "status": "completed",
  "content": [{ "type": "text", "text": "Created issue #42." }],
  "is_error": false
}

`agent.custom_tool_use`

Application-owned custom tool request. Your application must execute the tool and return user.custom_tool_result.

{
  "type": "agent.custom_tool_use",
  "id": "custom_toolu_123",
  "tool": "check_order_status",
  "input": { "order_id": "123" }
}

Field	Type	Description
`id`	string	Tool use ID to return as `user.custom_tool_result.tool_use_id`.
`tool`	string	Custom tool name from the agent configuration.
`input`	object	Model-supplied tool input.

`agent.clarify_request`

Blocking clarification question from the agent.

{
  "type": "agent.clarify_request",
  "request_id": "clarify_123",
  "question": "Which environment should I deploy to?",
  "choices": ["Staging", "Production"]
}

Field	Type	Description
`request_id`	string	ID to return as `user.clarify_result.request_id`.
`question`	string	Question to display to the user.
`choices`	string[] or null	Multiple-choice options, or `null` for open-ended answers.

`agent.thread_message_sent`

Parent agent delegated work to a subagent or thread.

{
  "type": "agent.thread_message_sent",
  "thread_id": "thread_123",
  "content": [{ "type": "text", "text": "Research deployment options." }]
}

`agent.thread_message_received`

Parent agent received a subagent or thread result.

{
  "type": "agent.thread_message_received",
  "thread_id": "thread_123",
  "content": [{ "type": "text", "text": "Use the existing deployment." }]
}

Custom tool handling

Custom tools are host-executed. Herm only brokers the request and response.

Declare a custom_tool in the agent’s tools array.
The model calls the tool during a turn.
The stream emits agent.custom_tool_use with the tool id, tool name, and input.
The stream emits session.status_idle with stop_reason.type: "requires_action" and the custom tool ID.
Your application executes the tool.
Your application posts user.custom_tool_result with tool_use_id equal to the agent.custom_tool_use.id.
The gateway forwards the result to Hermes and the paused turn continues streaming.

Custom tools are not governed by Herm permission policies because they do not run inside the Hermes sandbox. Your application is responsible for authorization, validation, idempotency, retries, and side-effect safety.

​Event envelope

​Shared types

​Text content block

​Stop reason

​User events

​user.message

​user.steer

​user.interrupt

​user.tool_confirmation

​user.custom_tool_result

​user.clarify_result

​user.sudo_result

​user.secret_result

​Session events

​session.status_running

​session.status_idle

​session.title_updated

​Agent events

​agent.message

​agent.thinking

​agent.tool_use

​agent.tool_result

​agent.mcp_tool_use

​agent.mcp_tool_result

​agent.custom_tool_use

​agent.clarify_request

​agent.thread_message_sent

​agent.thread_message_received

​Custom tool handling