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

# Sessions

> Monitor, detect, and enforce security across the full agentic lifecycle

Sessions monitor and secure the entire agentic lifecycle — every prompt, reasoning step, tool call, and response across AI IDEs, agents, and web chat tools. Security and platform teams use Sessions to see what agents are doing in real time, detect risky behavior across multiple steps, and enforce controls before a compromised or misaligned agent can continue.

A session represents one AI conversation or run, such as a Cursor chat, VS Code session, Claude Code session, GitHub Copilot CLI session, Gemini CLI session, Cline CLI session, Codex session, Qwen Code session, Hermes session, Goose session, Windsurf session, Vercel Eve session, Runlayer Agent run, or imported web chat.

Use Sessions to:

* Review prompts, reasoning, all tool calls (MCP and local), and model responses in one timeline
* See tool scanner outcomes for each tool call, including pass, alert, hint, mask, and block decisions
* Detect unsafe agent trajectory with [AgentGuard](https://docs.runlayer.com/agentguard.md), including prompt injection, reasoning drift, and multi-step manipulation
* Enforce tool scanner and AgentGuard decisions across the rest of the session
* Apply session policies for data isolation and protection against session-based attacks like privilege drift and cross-context access

> [!NOTE]
>
> Sessions are short-term operational monitoring data. Audit Logs remain the long-term system of record for policy decisions, security events, and administrative activity.

## How Sessions work

Sessions are built from several event sources:

* **Client hooks** send AI IDE and CLI activity from Cursor, VS Code, Claude Code, GitHub Copilot CLI, Gemini CLI, Cline CLI, Codex, Qwen Code, Hermes, Goose, Windsurf, and the Runlayer browser extension
* **Anthropic Inference hooks** send governed Claude.ai and Claude Code transcripts from Anthropic's infrastructure before inference; see [Anthropic Inference hooks](https://docs.runlayer.com/anthropic-inference-hooks.md)
* **Native runtime hooks** send hosted Vercel Eve lifecycle events without an external relay
* **OTLP telemetry** sends Claude Code and Claude Cowork session events as OTLP logs (see [Claude Code OTLP monitoring](https://docs.runlayer.com/claude-code-otlp-monitoring.md) and [Claude Cowork monitoring](https://docs.runlayer.com/claude-cowork-monitoring.md); Cowork exports directly from Anthropic's infrastructure) and Glean session events as OTLP traces. Runlayer accepts the OTLP metrics signal but doesn't store it
* **Runlayer Agents** stream run activity into the same session model
* **Tool scanners** add scan results for every MCP and local tool call — shell, file, web, and other client-local operations
* **Compliance imports** bring supported web chat activity in for monitor-only review

Runlayer normalizes everything into a single session record. Each session shows:

* **Identity** — user, client, status, timestamps, and source
* **Prompt context** — initial prompt and topic when available
* **Timeline** — prompts, thoughts, responses, tool inputs, tool outputs, tool permission prompts (allow/deny decisions), errors, and subagent activity
* **Tool usage** — tools called, connected servers, and failures
* **Security results** — tool scanner passes, warnings, alerts, masked content, and blocks
* **AgentGuard turns** — agent trajectory analysis across prompt, reasoning, tool output, and follow-up reasoning
* **External links** — provider links for imported web chat sessions when available

The Sessions page supports filtering by action, status, actor, client, topic, and date range.

## Set up Sessions

**1. Enable Full session scanning**

Go to **Settings → Agent session monitoring**.

Turn on **Full session scanning APIs**. This allows Runlayer to accept detailed session events from hooks and first-party agents.

**2. Choose the clients to monitor**

Under **Hook clients**, confirm each client or source you want to record in Sessions is enabled, such as Cursor, VS Code, Claude Code, GitHub Copilot CLI, Gemini CLI, Cline CLI, Codex, Qwen Code, Hermes, Goose, Windsurf, the Runlayer browser extension, Vercel Eve, Claude Cowork, Runlayer Agents, or the Hooks TypeScript SDK. Newly supported clients such as Vercel Eve are enabled by default.

Disable a client if you do not want its prompts, reasoning, tool inputs, and tool outputs collected.

Runlayer agent runs are recorded only while both **Full session scanning APIs** and **Runlayer Agents** are on. These switches also decide what reaches a [session SIEM export](#siem-export).

**3. Install client hooks or configure OTLP**

For IDE or CLI clients, install or reinstall hooks. For Sessions, pass `--event-hooks` (or the `--all-events` alias) so hooks send full session telemetry, not just shadow MCP enforcement.

Shadow MCP source blocking can run without full session telemetry. Local tool lifecycle scanning requires **Full session scanning APIs** and the target **Hook client** to be enabled.

```bash theme={null}
runlayer setup hooks --client cursor --install --event-hooks --yes
```

For managed deployments, set **Sessions** in [Deploy AI Watch](https://docs.runlayer.com/shadow-ai/deploy.md). Installer startup is fail-closed with no hooks; after settings sync, `Sessions=true` installs the full session hook set. Protect or Enforce with Sessions off installs decision hooks without full session telemetry.

For Claude Cowork, configure OTLP monitoring to send session events. See [Claude Cowork monitoring](https://docs.runlayer.com/claude-cowork-monitoring.md) for setup.

Claude Code can also send session events over OTLP. Prefer hooks where they can run, because OTLP is observe-only. See [Claude Code OTLP monitoring](https://docs.runlayer.com/claude-code-otlp-monitoring.md) for setup.

For organization-wide Claude prompt inspection, configure [Anthropic
Inference hooks](https://docs.runlayer.com/anthropic-inference-hooks.md). This server-side integration
can enforce input scanner verdicts and publish supported transcripts into
Sessions without a device-installed hook.

For Vercel Eve, install the native Runlayer runtime hook and add the active
Eve session ID to Runlayer MCP headers. See [Vercel Eve setup](https://docs.runlayer.com/runlayer-hooks-sdk.md#vercel-eve).

**4. Configure scanners**

Under **Settings → Security Scanners**, tune catalog and per-call [tool scanners](https://docs.runlayer.com/runlayer-toolguard.md), then configure [AgentGuard](https://docs.runlayer.com/agentguard.md) and **Block later tool calls when any scanner blocks**.

**5. Review activity**

Open **Sessions** in the sidebar. Start with the **Flagged** and **Blocked** filters to triage risky activity, then open a session to inspect the timeline and scanner results.

## Hook integrations

Hooks are the real-time source for IDE and supported hosted-runtime sessions. They capture both MCP tool calls and local tool activity, so Sessions show shell commands, file reads and writes, web fetches, and other client-local operations alongside MCP activity. Vercel Eve uses a [native runtime hook](https://docs.runlayer.com/runlayer-hooks-sdk.md#vercel-eve). For other custom agents, the Hooks SDK ([TypeScript](https://docs.runlayer.com/runlayer-hooks-typescript-sdk.md) or [Python](https://docs.runlayer.com/runlayer-hooks-python-sdk.md)) sends the same lifecycle and tool events through the hook pipeline.

> [!NOTE]
>
> [Enforce](https://docs.runlayer.com/shadow-ai/enforce.md) is the guide for supported hook clients and manual hook flags. [Deploy AI Watch](https://docs.runlayer.com/shadow-ai/deploy.md) is the canonical guide for MDM package configuration, including the `Sessions` flag. Enforce and Sessions are separate controls: Enforce hooks can block unmanaged Shadow MCPs as soon as they are installed, while full session scanning records detailed prompts, reasoning, tool calls, and scanner results in Sessions.

Hook enforcement depth varies by client. Windsurf enforces on pre-tool events only. Runlayer can deny a Windsurf tool call before it runs, but cannot block or rewrite Windsurf tool output. Windsurf tool output is still recorded in the session timeline, and scanner results on that output are observational.

Use [Set up Sessions](#set-up-sessions) above as the checklist for Full session scanning, Hook clients, and event hook installation. Use [Deploy AI Watch](https://docs.runlayer.com/shadow-ai/deploy.md) for managed deployments.

After hook installation or MDM redeployment, restart the AI client so the new hooks load.

### Tool permission prompts

When a coding agent asks the user to approve a tool call — for example Claude Code's allow/deny permission prompt, a Codex `PermissionRequest`, or a Cursor permission decision — Runlayer captures that prompt through the hook pipeline (the `PreToolUse`, `PermissionRequest`, and `PostToolUse` events). Each captured permission event records the **tool name**, the **tool input**, and the resulting **decision** (allow or deny) and **decision source** (the user, an agent auto-approval, or a client setting).

These appear on the session timeline alongside Runlayer's own scanner outcomes (pass, alert, hint, mask, block). This lets reviewers distinguish the agent's *native* allow/deny prompts from Runlayer's *policy and scanner* enforcement on the same tool call — for example, seeing that a developer approved a shell command that a Runlayer tool scanner then flagged.

> [!NOTE]
>
> Permission-prompt capture requires **Full session scanning** and the client's hooks installed in event mode (see [Set up Sessions](#set-up-sessions)). It relies on the client actually emitting a permission event: web chat brought in through [compliance imports](#web-chat-and-compliance-imports) (Claude web/desktop, ChatGPT web) is monitor-only and does not include native permission prompts.

## Reviewing Sessions

The Sessions page groups activity into security-focused tabs:

* **All** shows every session visible to you.
* **Flagged** shows sessions where scanners or policies recorded warning-level activity (Alert or Hint).
* **Blocked** shows sessions where Runlayer blocked an action.

Open a session to inspect the timeline. Depending on the source and workspace privacy settings, the timeline can include prompts, reasoning, local tool calls, MCP tool calls, tool permission prompts, scanner decisions, and links back to audit logs.

## AgentGuard

[AgentGuard](https://docs.runlayer.com/agentguard.md) is Runlayer's session-level behavior monitoring. It looks across the agent's trajectory — prompt, reasoning, tool output, follow-up reasoning — to detect output-steering injection, sudden reasoning pivots, and slow-chain drift that single-call scanners miss.

In the Sessions timeline, AgentGuard results appear as session turns. Configure Agent monitoring and **Block later tool calls when any scanner blocks** on the [AgentGuard](https://docs.runlayer.com/agentguard.md) page.

## Session policies

Session policies enforce data isolation and defend against session-based attacks — privilege drift, cross-context access, and tool calls that switch resources mid-session. They build on [session payload tracking](https://docs.runlayer.com/platform-policies.md#session-payload-tracking) and are configured as connector or agent **Policies**.

## Web chat and compliance imports

Some providers expose compliance APIs for reviewing web chat activity. When configured, Runlayer polls the provider's compliance API on a schedule and imports supported chat sessions into the Sessions view. Runlayer currently supports the **Anthropic Compliance API** (Claude web and desktop chat) and the **OpenAI Compliance Logs Platform** (ChatGPT web chat).

Imported web sessions are **monitor only**:

* They appear in Sessions for review and investigation
* They can include provider links when available
* They do not support real-time blocking because the chat already happened

Use web chat imports for visibility. Use client hooks for real-time monitoring and enforcement.

### Set up compliance imports

Compliance API access is an **enterprise plan capability on the provider side**, and the compliance API key is issued by an **admin of your Anthropic or OpenAI organization** — not by Runlayer. If your org does not yet have compliance API access, request it from the provider first (OpenAI's Compliance Logs Platform is granted on request and can take a few days to enable).

Configure providers in **Settings → Agent session monitoring**. Runlayer stores the API key encrypted at rest, and imports are scoped to your organization.

> [tab] Anthropic (Claude)
>
> 1. In [claude.ai](https://claude.ai/admin-settings/api-access), the primary owner of your Claude Enterprise organization opens **Organization settings → API** and creates a **Compliance Access Key** (`sk-ant-api01-…`) with the `read:compliance_user_data` scope. An organization owner can create a key limited to their own organization. Admin API keys from the Claude Console only reach Anthropic's Activity Feed and cannot import chats.
> 2. In Runlayer, open **Settings → Agent session monitoring**, expand **Claude.ai Web** under **Web clients**, and paste the key into **Compliance Access Key**.
> 3. Turn on the **Claude.ai Web** toggle and save.
>
> Runlayer imports Claude chats from every organization the key can read. Organization IDs are optional: add Anthropic organization IDs (UUID or `org_…` form) to limit the import to those organizations.
>
> > [!NOTE]
> >
> > **Claude Science, Claude for Microsoft 365, and Claude in Chrome (beta):** with the same key, Runlayer can also import prompts and replies from these apps, which Runlayer hooks don't capture. Claude Code and Cowork sessions aren't imported this way, because Runlayer hooks already capture them. To limit these imports by organization, use the UUID form of each organization ID. This import is in **beta**. Contact your Runlayer account team to enable it.

> [tab] OpenAI (ChatGPT)
>
> 1. Request access to the **Compliance Logs Platform** from OpenAI for your enterprise workspace or organization, then have an admin issue a compliance API key (sent as a `Bearer` token to `https://api.chatgpt.com/v1/compliance`).
>
> 2. In Runlayer, open **Settings → Agent session monitoring** and paste the key into **OpenAI Compliance API key**.
>
> 3. Add at least one **workspace or organization ID**. A value that starts with `org-` is treated as an organization scope; any other value is treated as a workspace scope.
>
> 4. Turn on the **OpenAI** toggle and save.
>
> > [!NOTE]
> >
> > OpenAI requires at least one workspace or organization ID **and** an API key before the provider can be enabled — the toggle stays disabled until both are set.

After a provider is enabled, imported web chats appear in **Sessions** on the next sync cycle, tagged with their source and a provider link when one is available. Changing the API key or external IDs resets the sync cursor, so the next run re-imports from the provider's current window.

### Who a compliance import covers

A compliance import covers **every user** in the connected Anthropic organization or OpenAI workspace. It doesn't depend on Runlayer sign-in, SSO or directory sync groups, or AI Watch:

* Chats from people who have a Runlayer account (same email) are filed under that account.
* Chats from people who have never signed in to Runlayer are still imported and stored, under the provider's user ID.
* The only scope control is the list of organization or workspace IDs. There is no per-user or per-group filter.

To keep a group out, for example during a POC or for executives, leave the import off, or keep those users in a provider organization or workspace that the import doesn't cover. See [Excluding users or groups from session capture](#excluding-users-or-groups-from-session-capture).

> [!NOTE]
>
> Anthropic Inference hooks work differently: a live prompt is only accepted when its email matches an active Runlayer user. See [Anthropic Inference hooks](https://docs.runlayer.com/anthropic-inference-hooks.md).

## Privacy and access

Sessions can contain prompts, reasoning, tool inputs, and tool outputs. Treat them as sensitive operational data.

With **Session privacy** on (**Settings → Agent session monitoring**), other users' sessions are redacted by default: the list shows a topic or session ID instead of raw prompts, and the first prompt, generated title and page URL are withheld, in the API and the Runlayer MCP `list_sessions` tool too. The timeline keeps each event's time, type, tool name, model and token counts, with `***REDACTED***` in place of every prompt, response, tool input and output, and page URL. People with the **View unredacted content** capability see it blurred until they unredact it; everyone else sees a notice instead. The API and the Runlayer MCP `get_session` tool return the same placeholder timeline. Safety charts and alerts stay visible. For who can see an agent's runs, see [Who can see an agent's runs](https://docs.runlayer.com/platform-agents.md#who-can-see-runs).

To decide per person who reads other people's content, with policies, break-glass access and protected sessions, see [Session content access](https://docs.runlayer.com/platform-session-content-access.md).

## Excluding users or groups from session capture

Some teams cannot send certain users' activity to Runlayer at all — executives, legal, or anyone working on material that is not yet public inside the company (M\&A, restructuring, unannounced plans). This is a common requirement when moving a POC toward production, and it is handled at the **source**: session capture is opt-in per device, so a device that is not configured to send session telemetry never transmits prompts or reasoning to Runlayer in the first place. There is nothing to filter server-side because the excluded user's content never leaves the endpoint.

One nuance to decide up front: **enforcement is not free of transmission**. Blocking a shadow MCP requires sending each tool call to Runlayer for policy evaluation, so a device running enforcement hooks still transmits tool inputs and outputs (and those events are stored when the client is enabled for the workspace) even with `Sessions` disabled. If a group requires that *nothing* be transmitted, do not deploy the AI Watch package to that group at all.

Scope capture by targeting the AI Watch / hook configuration to MDM device groups rather than enabling it org-wide:

| Group | AI Watch / client config | Result |
| - | - | - |
| Recorded (e.g. engineering) | Synced `Sessions` setting enabled (event-mode hooks installed) | Full session telemetry flows to Sessions |
| Excluded, enforcement kept (e.g. legal) | Synced `Sessions` setting disabled; Mode Protect or Enforce | No prompts or reasoning are sent or stored; enforcement hooks still transmit tool calls for policy evaluation |
| Excluded, zero transmission (e.g. executives) | No AI Watch package deployed | Nothing is sent from the device (see step 4 for server-side imports) |

1. **Split your deployment into device groups** and assign a distinct Runlayer MDM configuration per group. Enable Sessions only for groups you intend to monitor. See [Deploy AI Watch](https://docs.runlayer.com/shadow-ai/deploy.md) for per-group targeting.
2. **[Claude Cowork](https://docs.runlayer.com/claude-cowork-monitoring.md) cannot be scoped by device.** Cowork monitoring is configured org-wide in Claude admin settings and exports from Anthropic's VM, not from managed devices, so MDM targeting does not apply. To exclude users from Cowork capture, keep them in a separate Claude organization that has no Runlayer OTLP endpoint configured.
3. **Enforcement and Sessions stay independent** — an excluded group can keep enforcement hooks that block unmanaged shadow MCPs without sending prompts or reasoning, accepting the tool-call transmission described above. See [Set up Sessions](#set-up-sessions) for how the two controls differ.
4. **Check [compliance imports](#who-a-compliance-import-covers) too.** These are server-side: Runlayer imports web chat for **every user** in the connected Anthropic organization or OpenAI workspace, regardless of any device configuration or Runlayer sign-in. If excluded users must not appear in Sessions at all, they must sit in a provider organization/workspace that is not covered by a configured compliance import (or the import must be disabled).

> [!NOTE]
>
> Exclusion today is **device/group-scoped through MDM targeting**, not a per-user toggle inside the Runlayer app — centralized per-user exclusion levers are on the roadmap. As a coarser alternative, some teams keep excluded users on a separate model-provider account entirely so their activity is never in scope for the managed configuration.

## SIEM export

Session SIEM export sends prompts, reasoning, tool calls, and scanner verdicts
to S3 in near real time. Runlayer writes directly to a bucket that your
organization controls.

Customer-owned buckets keep retention, encryption, notifications, and SIEM
access in your AWS account. Runlayer assumes your IAM role with an external ID
for cross-account access.

This opt-in export is available for supported AWS deployments. Contact your
Runlayer account team to make sure that the export is available. New exports
start from new events. The export does not include earlier sessions.

> [!NOTE]
>
> The export carries the events Sessions records, so the switches under
> **Settings → Agent session monitoring** also control what reaches your
> bucket. Turning off **Full session scanning APIs** or a client under **Hook
> clients** stops that client's prompts, responses, and tool calls; tool scan
> results (`scan_recorded`) can still arrive. Runlayer agent runs need both
> **Full session scanning APIs** and **Runlayer Agents** turned on. Events from
> while a switch was off are not exported later. If your bucket only receives
> `scan_recorded` records, check these switches first.

### Configure the customer-owned bucket

Runlayer provides these values:

* A unique external ID
* The Runlayer AWS principal ARN
* The proposed object prefix, which is `sessions/` by default

Provide these values to Runlayer:

* The S3 bucket name
* The AWS Region
* The IAM role ARN
* The object prefix (`sessions/` by default)
* Whether the bucket uses SSE-KMS

Use this trust policy for the customer IAM role. Replace the placeholders with
the values from Runlayer.

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "RunlayerSessionSiemExportTrust",
      "Effect": "Allow",
      "Principal": {
        "AWS": "<runlayer-principal-arn>"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<external-id-from-runlayer>"
        }
      }
    }
  ]
}
```

Attach this write policy to the customer IAM role. Replace the bucket name and
`sessions` prefix with your values.

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "RunlayerSessionSiemExportWrite",
      "Effect": "Allow",
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::<bucket-name>/sessions/*"
    }
  ]
}
```

Grant the write on the whole prefix (`<prefix>/*`), never a narrower path such
as `sessions/year=*`. Runlayer writes both the NDJSON objects and the
`payloads/` full-body objects under the prefix. If a `payloads/` write is
denied, export pauses and retries until the policy is fixed; it does not skip
the event.

The same rule applies if your bucket policy grants Runlayer write access
directly, with no customer IAM role: the statement that allows Runlayer's
principal `s3:PutObject` must use `"Resource": "arn:aws:s3:::<bucket-name>/<prefix>/*"`.

The customer IAM role needs only `s3:PutObject` for S3 writes. If the bucket
uses SSE-KMS, grant `kms:GenerateDataKey` to this role. The KMS key policy must
also allow the role.

### S3 object layout

Objects are written with a Hive-style date partition prefix. Each event object
is gzip-compressed NDJSON with content type `application/x-ndjson` and content
encoding `gzip`. Full-body objects under `payloads/` are plain JSON with content
type `application/json`. The default prefix is `sessions/`:

```text theme={null}
sessions/year=YYYY/month=MM/day=DD/<object>.jsonl.gz
sessions/payloads/year=YYYY/month=MM/day=DD/<event_id>-sha256-<body digest>.json
sessions/payloads/year=YYYY/month=MM/day=DD/<chunk_id>-part-<part_index>-sha256-<body digest>.json
```

Read full bodies through `data_payload_uri` rather than building the key
yourself. The name ends in the SHA-256 of the body, so two events that share
an `event_id` but carry different bodies (see
[Duplicates and retries](#duplicates-and-retries)) never overwrite each other,
and a retried write of the same event lands on the same object.

Ingest the `.jsonl.gz` objects into your SIEM. Objects under `payloads/` hold
the full content of large events; see [Truncated content](#truncated-content).

If S3 event notifications drive your ingestion (for example a Splunk SQS-based
S3 input, the Microsoft Sentinel S3 connector, the Datadog Forwarder, or an
EventBridge rule), filter them on the `.jsonl.gz` suffix or on the
`<prefix>/year=` prefix. A filter on `<prefix>/` alone also matches the
`payloads/` objects, which are plain JSON of up to about 1 MB each, not event
lines. Fetch those through `data_payload_uri` when you need the full body.

Treat object names as opaque unique identifiers. The date partition is each
event's UTC **arrival date**, which can differ from the event's own
`timestamp` — scan by partition for completeness, filter by `timestamp` for
analysis.

### Payload schema v1

Each NDJSON line is one schema-v1 event. The stable top-level field names are:

| Field group | Fields |
| - | - |
| Schema and time | `schema_version`, `arrival_at`, `timestamp` |
| Event, actor, session, and chunk identity | `organization_id`, `event_id`, `actor_id`, `actor_type`, `session_id`, `external_session_id`, `chunk_id`, `part_index`, `total_parts` |
| Actor details | `actor_email`, `actor_display_name`, `actor_workos_id`, `actor_workos_directory_user_id` |
| Event metadata | `client`, `event_category`, `event_type`, `raw_event_name`, `blocked`, `block_reason`, `duration_ms` |
| Producer metadata | `tool_name`, `server_slug`, `internal_type`, `agent_id`, `source`, `model`, `monitor_only` |
| Content and truncation | `data`, `data_truncated`, `data_original_bytes`, `data_payload_uri` |

Top-level field names and meanings remain stable within schema v1. `data`
normally contains the raw producer body and can evolve additively as producers
add fields. Truncation can replace `data` with a preview or an empty object. In
extreme cases, enforcing the event-size cap can also null or omit lower-priority
top-level fields. For the values of `event_category` and `event_type`, see
[Event types](#event-types).

### Event types

Each event has three type fields:

* `event_category` is the broad group, for example `tool`.
* `event_type` is the normalized event, for example `pre_tool_use`.
* `raw_event_name` is the name the producer sent. It is producer-specific and
  is not normalized. For example, Claude Code sends `PreToolUse` and Cursor
  sends `preToolUse`; both become `tool` / `pre_tool_use`.

Use `event_category` and `event_type` for SIEM rules. Use `client` and
`raw_event_name` only for client-specific logic.

The list below can grow. New clients and producers can add values in schema v1
without notice. SIEM consumers **must accept unknown values** of
`event_category`, `event_type`, and `raw_event_name`. Runlayer does not store or
export a raw client event that it cannot map. It does not send such an event
with a placeholder category.

Not every client sends every event type. The **Sources** column gives examples,
not a complete list. "Claude Code-format clients" means Claude Code and the
clients that use its hook format, such as GitHub Copilot CLI, Gemini CLI,
Cline, Devin CLI, Grok CLI, Windsurf, Claude Cowork, and Glean.

| `event_category` | `event_type` | Meaning | Sources |
| - | - | - | - |
| `session` | `session_start` | A session started or resumed. | All clients |
| `session` | `session_end` | A session ended. Runlayer also closes a session after it is idle for too long. | All clients |
| `prompt` | `prompt_submit` | The user sent a prompt to the agent. | Most clients, LLM gateway |
| `reasoning` | `agent_thought` | The agent produced intermediate reasoning text. | Cursor, Claude Code, Codex, Runlayer agents, Vercel Eve |
| `reasoning` | `agent_response` | The agent produced a response. | Cursor, Claude Code, Codex, Gemini CLI, Glean, LLM gateway, Runlayer agents, Vercel Eve, compliance imports |
| `response` | `agent_response` | The agent produced a response, captured from an Anthropic inference request. | Anthropic inference hooks |
| `tool` | `pre_tool_use` | The agent is about to use a tool: an MCP tool, a shell command, or a file read or write. | Most clients, LLM gateway, Runlayer agents |
| `tool` | `post_tool_use` | A tool call completed. | Most clients, LLM gateway, Runlayer agents |
| `tool` | `post_tool_use_failure` | A tool call failed. | Claude Code-format clients, Cursor, Codex, Runlayer agents |
| `subagent` | `subagent_start` | The agent started a subagent. | Claude Code-format clients, Cursor, Vercel Eve |
| `subagent` | `subagent_stop` | A subagent stopped. | Claude Code-format clients, Cursor, Hermes, Vercel Eve |
| `control` | `stop` | The agent stopped its turn, or the turn was cancelled or failed. | Most clients |
| `control` | `turn_completed` | The agent completed a turn. | Vercel Eve |
| `control` | `pre_compact` | The client is about to compact the conversation context. | Claude Code-format clients, Cursor |
| `control` | `post_compact` | The client compacted the conversation context. | Devin CLI, Grok CLI |
| `control` | `permission_request` | The client asked the user to approve an action. | Claude Code-format clients, Codex |
| `control` | `permission_denied` | The client denied an action. | Grok CLI |
| `control` | `notification` | The client showed a notification to the user. | Claude Code-format clients |
| `control` | `teammate_idle` | A teammate agent became idle. | Claude Code-format clients |
| `control` | `task_completed` | A task completed. | Claude Code-format clients |
| `control` | `error_occurred` | The client reported an error. | GitHub Copilot CLI, Cline, Grok CLI |
| `config` | `instructions_loaded` | The client loaded an instructions file. | Claude Code-format clients |
| `config` | `config_change` | The client configuration changed. | Claude Code-format clients |
| `config` | `worktree_create` | The client created a Git worktree. | Claude Code-format clients |
| `config` | `worktree_remove` | The client removed a Git worktree. | Claude Code-format clients |
| `model` | `api_request` | A model API request completed. `data` can include the model and token usage. | Claude Code, Codex, Claude Cowork, Glean, LLM gateway, Runlayer agents, Vercel Eve |
| `model` | `api_error` | A model API request failed. | Claude Cowork, Glean, Vercel Eve |
| `artifact` | `turn_completed` | Runlayer recorded the [AgentGuard](https://docs.runlayer.com/agentguard.md) result for a completed turn. | Runlayer |
| `artifact` | `scan_recorded` | Runlayer recorded a tool scan result. | Runlayer |
| `artifact` | `session_blocked` | Runlayer blocked the whole session. | Runlayer |

The same `event_type` can occur in more than one category. For example,
`turn_completed` occurs in `control` and in `artifact`. Always match on the pair.

This example shows a Claude Code MCP tool call. The values are synthetic.

```json theme={null}
{
  "schema_version": 1,
  "arrival_at": "2026-11-04T10:16:43+00:00",
  "organization_id": "0b6f2c1e-4a57-4d3e-9b8a-1f2e3d4c5b6a",
  "event_id": "3f6c2d9e-8b1a-4c7d-9e2f-5a6b7c8d9e0f",
  "actor_id": "7d1e9a40-2c3b-4f5e-8a6d-9b0c1d2e3f4a",
  "actor_type": "user",
  "client": "claude_code",
  "session_id": "da37535a-7497-5a72-adb1-7407e4b4426d",
  "external_session_id": "cc-81d4",
  "event_category": "tool",
  "event_type": "pre_tool_use",
  "raw_event_name": "PreToolUse",
  "timestamp": "2026-11-04T10:16:42Z",
  "blocked": null,
  "block_reason": null,
  "duration_ms": null,
  "chunk_id": null,
  "part_index": 0,
  "total_parts": 1,
  "actor_email": "user@example.com",
  "actor_display_name": "Example User",
  "actor_workos_id": "user_01EXAMPLE",
  "actor_workos_directory_user_id": null,
  "tool_name": "mcp__github__list_pull_requests",
  "server_slug": null,
  "internal_type": null,
  "agent_id": null,
  "source": null,
  "model": null,
  "monitor_only": null,
  "data_truncated": null,
  "data_original_bytes": null,
  "data": {
    "tool_type": "mcp",
    "tool_name": "mcp__github__list_pull_requests",
    "tool_input": { "state": "open" },
    "tool_use_id": "toolu_01",
    "transport": "local_hook",
    "provider_session_id": "cc-81d4"
  }
}
```

This example shows the prompt from the same session. Most fields are left out
to keep it short. The real line contains all the fields of the first example.

```json theme={null}
{
  "schema_version": 1,
  "arrival_at": "2026-11-04T10:16:41+00:00",
  "event_id": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
  "client": "claude_code",
  "session_id": "da37535a-7497-5a72-adb1-7407e4b4426d",
  "external_session_id": "cc-81d4",
  "event_category": "prompt",
  "event_type": "prompt_submit",
  "raw_event_name": "UserPromptSubmit",
  "timestamp": "2026-11-04T10:16:40Z",
  "data": {
    "prompt": "Summarize the open pull requests",
    "transport": "local_hook",
    "provider_session_id": "cc-81d4"
  }
}
```

### Duplicates and retries

Delivery is at-least-once: a retry can write the same event again, as a
duplicate line or in a second object. SIEM consumers **must dedupe on
`session_id`, `event_id` and `part_index`**. All parts of a chunked event share
one `event_id`; other events always have `part_index` 0. A retry always repeats
all three values. `event_id` alone is not unique across sessions: for clients
that send their own event ids, `event_id` is derived from that id, so two
sessions can carry the same `event_id` for different events. Keying on
`session_id` as well keeps both lines, the same way Runlayer keeps both in each
session's timeline.

### Truncated content

The default per-event cap is 256 KiB, with a 4 KiB UTF-8 preview. A preview is
stored in `data._preview`; `data._preview_truncated` indicates whether the
preview itself was cut.

Content over the cap is not lost. Runlayer writes the full `data` body to its
own JSON object in the same bucket and prefix, under `payloads/`, before it
writes the line that points to it. The line's `data_payload_uri` field holds
the object's `s3://` URI. Lines under the cap have no `data_payload_uri` field.

| `data_truncated` | Meaning |
| - | - |
| `oversize` | The event exceeded the size cap. `data` contains a bounded preview. The full `data` body is in the object at `data_payload_uri`. |
| `chunked` | A very large event was split during ingestion. Every part is exported as its own line with a preview of that part, and each part's full body is in its own object at `data_payload_uri`. |
| `invalid` | The producer sent a non-object `data` value. It was dropped, not truncated, and `data` never contains a preview. `data_original_bytes` can be null. |

`data_original_bytes` is not comparable across truncation reasons. For
`oversize`, it is the serialized size of the whole logical event before content
is shed. For `chunked`, it is the size of that part only — a fraction of
the logical event. Only a small share of events exceeds the cap at the default
sizes; the rest export with full content.

To rebuild a chunked event, collect the lines with the same `chunk_id` (parts
can arrive in different objects and on different days), read the object at each
part's `data_payload_uri`, join their `_chunk` strings in `part_index` order
from `0` to `total_parts - 1`, and parse the result as JSON. The result is the
event's original `data`.

> [!WARNING]
>
> Session SIEM export contains unredacted content. The workspace's **Session
> privacy** setting and a connector's **Sensitive audit log** setting do not
> apply to exported session content. Access to the destination bucket is the
> access-control boundary.

## Recommended rollout

Sessions work best when enabled gradually — observe first, then enforce, then expand. The same phased approach applies when moving from a pilot to org-wide deployment:

1. **Start with admins and security reviewers.** Enable Full session scanning and hooks for a small pilot group before adding broader teams.
2. **Enable session privacy** if your workspace expects user-level confidentiality (see [Privacy and access](#privacy-and-access)).
3. **Use Alert mode before Block mode** for new [tool scanners](https://docs.runlayer.com/runlayer-toolguard.md) and [AgentGuard](https://docs.runlayer.com/agentguard.md). Alert mode logs detections without blocking, so you can tune sensitivity on real traffic before enforcing.
4. **Roll out [policies](https://docs.runlayer.com/platform-policies.md) gradually** — start with deny-all and grant exceptions as legitimate usage patterns emerge.
5. **Verify [agents](https://docs.runlayer.com/platform-agents.md) in the Playground** and tighten prompt/tool scope before broad rollout.
6. **Review blocked and flagged sessions daily during rollout.** Use the **Flagged** and **Blocked** tabs to triage, and rely on [Audit Logs](https://docs.runlayer.com/platform-audit-logs.md) as the long-term record of policy decisions and security events.
7. **Expand client coverage** — once the pilot group's alerts are quiet and scanner settings are tuned, enable additional Hook clients and move to managed [MDM deployment](https://docs.runlayer.com/shadow-ai/deploy.md) for the rest of the org.

For the infrastructure side of moving from POC to production (self-hosted deployment, networking, upgrades), see the [deployment overview](https://docs.runlayer.com/deployment/overview.md).

## Troubleshooting

### No sessions appear

Start with [Set up Sessions](#set-up-sessions). Empty Sessions usually mean Full session scanning is off, the source is not enabled, hooks were not installed in event mode, or the AI client was not restarted after hook installation or MDM redeployment.

Also check that the user is logged in with `runlayer login`.

### One client's sessions are missing (e.g. Codex)

If most clients show up but one does not, that client is likely not enabled as a **Hook client**. Go to **Settings → Agent session monitoring → Hook clients** and confirm the specific client (Codex, GitHub Copilot CLI, Gemini CLI, Hermes, Goose, and so on) is toggled on. Then reinstall that client's hooks in event mode and restart it:

```bash theme={null}
runlayer setup hooks --client codex --install --event-hooks --yes
```

Each client only reads its hook config at process start, so the client must be fully restarted after the toggle is enabled or hooks are reinstalled.

### Enforce blocks shadow MCPs, but Sessions are empty

Enforce and Sessions are separate. Shadow MCP blocking can work without full session telemetry.

Complete [Set up Sessions](#set-up-sessions). For managed deployments, confirm Sessions is enabled in the assigned Runlayer MDM configuration (see [Deploy AI Watch](https://docs.runlayer.com/shadow-ai/deploy.md)), wait for settings sync and the next bootstrap tick, then restart the AI client.

### Hook commands cannot find `runlayer`

Install the CLI permanently and restart the AI client:

```bash theme={null}
uv tool install runlayer
runlayer --help
```

For managed deployments, use [Deploy AI Watch](https://docs.runlayer.com/shadow-ai/deploy.md).

### AgentGuard options are missing

See [AgentGuard → Requirements](https://docs.runlayer.com/agentguard.md#requirements).

## Related docs

> [card] [Browser extension](https://docs.runlayer.com/shadow-ai/browser-extension.md)
>
> Capture supported AI web chats and apply prompt protection where available

> [card] [Enforce](https://docs.runlayer.com/shadow-ai/enforce.md)
>
> Install hooks for Cursor, VS Code, Claude Code, GitHub Copilot CLI, Gemini CLI, Cline CLI, Codex, Qwen Code, Hermes, Goose, and Windsurf

> [card] [ToolGuard Models](https://docs.runlayer.com/runlayer-toolguard.md)
>
> Configure per-call tool scanners and model sensitivity

> [card] [AgentGuard](https://docs.runlayer.com/agentguard.md)
>
> Session-level behavior monitoring across the agent trajectory

> [card] [Policies](https://docs.runlayer.com/platform-policies.md)
>
> Restrict tools using access policies

> [card] [Claude Cowork monitoring](https://docs.runlayer.com/claude-cowork-monitoring.md)
>
> Send Cowork session events via OTLP

> [card] [Claude Code OTLP monitoring](https://docs.runlayer.com/claude-code-otlp-monitoring.md)
>
> Send Claude Code session events via OTLP


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