Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.
Version: 11.3.0

Governing What a Session Has Already Read

A classification tells you what one call carries. It cannot tell you that an agent read your finance channel two minutes ago, and is now writing an email. The email itself may carry nothing sensitive, because the agent reworded what it read.

Session tracking closes that gap. When a call reads classified data, HYPR AgentPass™ remembers the most sensitive data that session has touched. Every later call in the same session can then be judged on it, as in "this session has already read Restricted data, and this destination may only receive Internal."

This page builds on Classifying the Data Your Tools Handle. Session tracking has something to remember only once your tools carry labels. A flow rule acts only on a destination that has a data ceiling.

Turning It On​

Session tracking is off by default.

  1. Open Advanced → Data Classification, and click the Policies tab.
  2. Turn on the switch beside Session tracking is off. The label then reads Session tracking is on.
  3. Optional: In Forget a session after, enter how many minutes of inactivity end a session. The default is 30 minutes, and the maximum is 1,440 (one day). Every call that counts restarts the clock.
  4. If you changed the window, click Save window.
The session tracking control on the Policies tab, switched on, with how sessions are told apart and the Forget a session after window

Turning it on changes no traffic by itself. It gives policies something new to read. Nothing is held or refused until a policy uses it.

The History tab records who turned session tracking on or off, and when.

What a Session Remembers​

A session remembers:

  • The most sensitive tier of data it has read
  • Every tag that data carried
  • Every connector it has called, classified or not

Only calls that actually returned data to the agent count. A call is remembered when all of these hold:

  • It is a tool call, a resource read or a prompt fetch.
  • AgentPass forwarded it, and the system behind the connector answered successfully.
  • No policy withheld the response.

A call that was refused, held for approval, or failed upstream returned nothing, so it leaves the session as it was. This applies to MCP proxy connectors and REST API connectors alike, so a session can read through one kind and send through the other.

How a Session Is Identified​

What counts as one session depends on what the calling client tells AgentPass. AgentPass uses the most precise identity available.

The caller isOne session isShown as
An AgentCore agentOne conversation, confirmed against the session the gateway startedagentcore_session
An Anthropic cloud agentOne cloud-agent sessioncma_session
Another managed or service agentEvery session of that agent credential — kept separate per user when many people share one AgentCore agentagent_identity
A person in a desktop clientEverything that person does through AgentPass within the windowuser

Desktop clients such as Claude Code and Codex do not send a session identifier with their tool calls. AgentPass therefore groups them by person. Two conversations one person runs side by side, in the same client or different ones, share one record.

That grouping is deliberately broad. A narrower grouping would let an agent read through one connector and send through another, without the two ever being linked. It is also why the recommended rule holds a call for approval, instead of refusing it.

Two more details apply:

  • An Anthropic cloud-agent session identifier counts only when the call uses that cloud agent's own credential. Any other caller that sends one is grouped as usual. A caller therefore cannot start a fresh, clean session by changing the identifier it sends.
  • Calls are linked only when they arrive under the same identity. If a person reads data through their own AgentPass sign-in, and an agent then sends through a separate agent credential, the two are separate sessions.

Writing a Session Policy​

A policy reads a session through the session attributes.

AttributeWhat it holds
session.tier_rankRank of the most sensitive tier the session has read. 0 when it has read nothing classified
session.tierThe key of that tier, such as restricted. Absent when session.tier_rank is 0
session.tagsEvery tag the session has read
session.connectorsEvery connector the session has called
session.contributionsHow many calls have counted toward the session so far
session.key_kindHow the session was identified: agentcore_session, cma_session, agent_identity or user

The session reflects what happened before the current call. As always, data, tool and connector describe the call being judged.

The session attributes are absent when session tracking is off, when nothing identifies the caller, or when AgentPass cannot read the session record in time. A missing attribute never matches, so a session rule steps aside instead of blocking traffic. In each of these cases, calls carry on normally.

For example, if Restricted is rank 4 in your vocabulary, this rule holds anything sent through a mail connector once the session has read Restricted data. Scope the policy to your mail connector, on the Pre-Request phase:

session.tier_rank >= 4

As with data, compare the rank, not the tier's name, so the rule survives a rename. The starter policies express the same idea against each connector's own ceiling, so one rule covers every destination.

The Session Starter Policies​

The Policies tab always lists three session starters. While session tracking is off, each is tagged needs session tracking, and matches nothing until you turn it on. All three compare what the session has read with the destination's data ceiling, so they never act on a connector that has none.

PolicyConditionAction
hold-session-data-leaving (recommended)The session has already read data above the destination's ceilingRequire approval
refuse-session-data-leavingThe sameDeny
refuse-session-data-leaving-preciseThe same, but only for sessions identified precisely, not a desktop client's per-person sessionDeny
The three session starter policies on the Policies tab, each in Observe mode and tagged session tracking on, with its condition and an Add this policy button

Start with the hold. On desktop clients, a person's parallel conversations share one record, so a refusal could stop a conversation that never read the data. A hold asks a supervisor instead, so a false alarm costs one approval, not a failed task.

To refuse managed and cloud agents outright, use refuse-session-data-leaving-precise alongside the hold. It refuses where AgentPass knows exactly which conversation read the data, and leaves desktop sessions to the hold rule.

Like every starter, these are created in Observe mode. Until you switch them to Enforce, they record what they would have held or refused, without changing traffic.

When a session rule holds a call, the approval tells the supervisor why, below the policy's own message.

It names every connector the session has called, not only the one the data came from. It names up to three, then gives a count.

Seeing a Session in the Request Log​

Open a call in the Request Log. When session tracking identified the call's session, a Session before this call card shows how the session was identified, and what it had already read when the call arrived. That is the evidence a session rule acted on, or in Observe mode would have acted on.

A request's Data classification card, and below it the Session before this call card, with what the session had read and how it was identified

The Data Flow Report​

The Data flow tab on the Data Classification page counts boundary crossings. A boundary crossing is a call that sent data more sensitive than the destination's ceiling, whether the call itself carried it or its session had read it earlier.

Crossings are recorded only for a destination that has a ceiling, so the report starts filling the day you set one.

Each row covers one day, and has these columns.

ColumnMeaning
DayThe day the crossings happened
DestinationThe connector the data went to
CeilingThat connector's ceiling
Carried byWhether the call itself carried the data, the session had read it, or both
Session keyHow the session was identified
OutcomeWhat happened: allowed, denied or held
CallsHow many calls matched
The Data flow tab with the window choices, Export CSV, a notice counting allowed crossings, and one row per day and destination

The report opens on the last 30 days. Choose a 7, 30 or 90-day window. Click Export CSV to download the rows for the chosen window as a CSV file. The report refreshes every 30 minutes, and keeps 90 days.

Allowed rows matter most: data crossed a boundary, and nothing stopped it. A crossing that only an Observe-mode policy matched counts as allowed, because the call went through. When a window has allowed crossings, the tab states how many. Each crossing is also recorded as an event, so the same signal reaches your event stream and SIEM.