> ## Documentation Index
> Fetch the complete documentation index at: https://silmaril.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Events and conversations

> Label execution boundaries and preserve ordered context across an agent sequence.

Send one complete event at each boundary you protect. Apply its verdict before the application consumes that event or performs the proposed action.

## Choose a hook

| Boundary | API hook | Check before |
| - | - | - |
| User input | `user_input` | The model consumes the input |
| Tool call | `tool_call` | The tool executes |
| Tool response | `tool_response` | The model consumes the tool output |
| Model output | `llm_output` | The application returns or consumes generated content |

Supply the tool name for tool calls and tool responses. SDKs expose typed hook labels for these values.

## Preserve conversation order

Use a caller-owned `metadata.conversationId` for one agent sequence. Send ordered individual `classify()` calls with that ID, waiting for and handling each verdict or error before sending the next event.

Each SDK event also receives a `metadata.silmaril.request_id`. Use the request ID to correlate a classification and the conversation ID to group the sequence. Let the SDK manage request identity.

Location: protected TypeScript service with an initialized `fw` client

```typescript theme={"theme":"github-light-default"}
import { HookLabel } from "@silmaril-security/sdk"

const metadata = { conversationId: "build-repair-123" }

const inputVerdict = await fw.classify(userInput, {
  hook: HookLabel.USER_INPUT,
  metadata,
})
```

Import `HookLabel` from `@silmaril-security/sdk`. Handle `inputVerdict` according to the [effective mode](https://silmaril.dev/docs/guides/enforcement.md) before continuing the sequence.

## Batch independent events

Use batch classification for independent inputs. Responses preserve input order. Batch calls preserve per-item metadata while leaving conversation history unchanged. The same conversation ID on batch items leaves those items independent.

Use concurrency for independent events or different conversations. Keep events within one conversation sequential.

## Field names

| API field | TypeScript option | Python option | Go option |
| - | - | - | - |
| `hook` | `hook` | `hook` | `WithHook` |
| `tool_name` | `toolName` | `tool_name` | `WithToolName` |
| `metadata` | `metadata` | `metadata` | `WithMetadata` |

See the [single-event API](https://silmaril.dev/docs/api-reference/classify.md) and [SDK reference](https://silmaril.dev/docs/sdk/typescript.md) for complete request options.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.