Skip to main content
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, Grok CLI session, Codex session, Qwen Code session, Cline CLI session, Devin CLI session, Muse Code session, OpenCode 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, 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
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, Grok CLI, Codex, Qwen Code, Cline CLI, Devin CLI, Muse Code, OpenCode, 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
  • 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 and Claude Cowork monitoring; Cowork exports directly from Anthropic’s infrastructure) and Glean session events as OTLP traces (where enabled for your tenant). 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, Grok CLI, Codex, Qwen Code, Cline CLI, Devin CLI, Muse Code, OpenCode, 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.
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.
For managed deployments, set Sessions in Deploy AI Watch. 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 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 for setup.For organization-wide Claude prompt inspection, configure Anthropic Inference hooks. 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.
4

Configure scanners

Under Settings → Security Scanners, tune catalog and per-call tool scanners, then configure AgentGuard 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. For other custom agents, the Hooks SDK (TypeScript or Python) sends the same lifecycle and tool events through the hook pipeline.
Enforce is the guide for supported hook clients and manual hook flags. Deploy AI Watch 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 above as the checklist for Full session scanning, Hook clients, and event hook installation. Use Deploy AI Watch 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.
Permission-prompt capture requires Full session scanning and the client’s hooks installed in event mode (see Set up Sessions). It relies on the client actually emitting a permission event: web chat brought in through 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 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 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 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.
  1. In claude.ai, 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.
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.
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.
Anthropic Inference hooks work differently: a live prompt is only accepted when its email matches an active Runlayer user. See Anthropic Inference hooks.

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. To decide per person who reads other people’s content, with policies, break-glass access and protected sessions, see Session content access.

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:
  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 for per-group targeting.
  2. Claude Cowork 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 for how the two controls differ.
  4. Check compliance imports 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).
Exclusion is device/group-scoped through MDM targeting by default. Where policy rules are enabled, you can instead create a user-scoped policy with Sessions off under Settings → Endpoint configuration. That setting is applied by the device, so it is not a server-side guarantee. 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.
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.
Attach this write policy to the customer IAM role. Replace the bucket name and sessions prefix with your values.
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/:
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) 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. 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: 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

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

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_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.
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.
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).
  3. Use Alert mode before Block mode for new tool scanners and AgentGuard. Alert mode logs detections without blocking, so you can tune sensitivity on real traffic before enforcing.
  4. Roll out policies gradually — start with deny-all and grant exceptions as legitimate usage patterns emerge.
  5. Verify agents 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 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 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.

Troubleshooting

No sessions appear

Start with 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:
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. For managed deployments, confirm Sessions is enabled in the assigned Runlayer MDM configuration (see Deploy AI Watch), 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:
For managed deployments, use Deploy AI Watch.

AgentGuard options are missing

See AgentGuard → Requirements.

Browser extension

Capture supported AI web chats and apply prompt protection where available

Enforce

Install hooks for Cursor, VS Code, Claude Code, GitHub Copilot CLI, Gemini CLI, Grok CLI, Codex, Qwen Code, Cline CLI, Devin CLI, Muse Code, OpenCode, Hermes, Goose, and Windsurf

ToolGuard Models

Configure per-call tool scanners and model sensitivity

AgentGuard

Session-level behavior monitoring across the agent trajectory

Policies

Restrict tools using access policies

Claude Cowork monitoring

Send Cowork session events via OTLP

Claude Code OTLP monitoring

Send Claude Code session events via OTLP