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

# Sessions

> Learn how Aegis sessions group agent tool calls, what session fields mean, how to inspect individual actions, and how approvals interact with sessions.

A **session** in Aegis represents a single, continuous agent run, everything an agent does from the moment it starts a task to the moment it stops making tool calls. All actions within a run share a common `session_id`, which lets you view the complete history of what an agent did, in order, in one place. Sessions are created automatically; you do not configure or start them manually.

## How sessions are created

When an agent makes its first MCP tool call through Aegis, Aegis records the `session_id` embedded in the call. Every subsequent call from the same agent run with the same `session_id` is grouped into that session. If an agent starts a new task and generates a new `session_id`, Aegis opens a new session automatically.

You never need to declare or initialize a session. The aggregation happens on the backend as actions arrive.

## Session fields

Each session surfaces the following information in the Aegis dashboard:

| Field            | Description                                                                                   |
| ---------------- | --------------------------------------------------------------------------------------------- |
| `session_id`     | The unique identifier for this agent run, generated by the agent                              |
| `agent_name`     | The name the agent reported when making tool calls                                            |
| `action_count`   | Total number of MCP tool calls made in this session                                           |
| `started_at`     | Timestamp of the first action in the session                                                  |
| `last_action_at` | Timestamp of the most recent action, useful for identifying whether a session is still active |
| `repos`          | List of GitHub repositories that were touched during this session                             |
| `allows`         | Count of actions that received an ALLOW decision                                              |
| `denies`         | Count of actions that were blocked with a DENY decision                                       |
| `rewrites`       | Count of actions that were redirected via a REWRITE decision                                  |
| `approvals`      | Count of actions that required or triggered a REQUIRE\_APPROVAL decision                      |

The sum of `allows`, `denies`, `rewrites`, and `approvals` equals `action_count`.

## Individual actions within a session

Drilling into a session shows each individual tool call as a row. Every action includes:

| Field            | Description                                                                                  |
| ---------------- | -------------------------------------------------------------------------------------------- |
| `tool_name`      | The GitHub MCP tool the agent called (e.g., `push_files`, `create_pull_request`)             |
| `action_summary` | A plain-English description of what the action would do                                      |
| `decision`       | The outcome Aegis assigned: ALLOW, DENY, REWRITE, or REQUIRE\_APPROVAL                       |
| `execution_time` | How long the action took to evaluate and (if allowed) execute, in milliseconds               |
| `blast_radius`   | Severity rating: Low, Medium, High, or Critical                                              |
| `policy`         | The policy verdict, `pass` if all checks passed, or the enforced policy name if a rule fired |
| `arguments`      | The raw arguments the agent passed to the tool call                                          |
| `target_repo`    | The repository the action targeted                                                           |
| `target_branch`  | The branch the action targeted, if applicable                                                |

Actions within a session are ordered by `sequence_order`, so you can follow the agent's chain of reasoning step by step.

## Viewing sessions in the dashboard

<Steps>
  <Step title="Open the Sessions page">
    Navigate to **Dashboard → Sessions** in the sidebar. The page lists all sessions, sorted by most recent activity. Each row shows the agent name, action count, start time, last activity time, and a summary of allow/deny/rewrite/approval counts.
  </Step>

  <Step title="Select a session">
    Click any session row to expand or navigate to its detail view. You will see the full list of individual actions in order, with their tool names, summaries, decisions, and blast radius ratings.
  </Step>

  <Step title="Inspect an action">
    Click an individual action row to see the full arguments, policy verdict, execution time, and any action pointers (human-readable bullet points that the backend generates for complex tool calls like PR creation).
  </Step>
</Steps>

## How sessions relate to approvals

When an action in a session receives a `REQUIRE_APPROVAL` decision, the agent's tool call does not return immediately. The session is effectively paused at that step, the agent waits for a human to act before it can continue.

You review pending approvals from two places:

* **Dashboard home**, the **Pending approvals** panel on the right side of the overview shows up to five queued actions. Each item displays the agent name, tool name, a plain-English summary, and Approve / Deny buttons.
* **Approvals page**, navigate to **Dashboard → Approvals** to see the full list of all pending and historical approval requests.

When you click **Approve**, Aegis executes the held action immediately and returns the result to the waiting agent. The session then continues from where it paused. When you click **Deny**, Aegis sends an error back to the agent and discards the action. The agent receives a structured response indicating the action was denied and can decide how to proceed.

<Note>
  Multiple actions in the same session can be waiting for approval simultaneously if the agent made several qualifying tool calls in quick succession before any were reviewed.
</Note>

<Tip>
  The dashboard header badge shows the count of pending approvals across all sessions. Use it as a quick signal that an agent is waiting for you.
</Tip>