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

# How it works

> Learn how Aegis intercepts MCP tool calls, evaluates them against your policies, and enforces Allow, Deny, Rewrite, or Require Approval decisions.

Aegis sits between your AI coding agents and GitHub, intercepting every tool call over the Model Context Protocol (MCP) before it reaches your repositories. This page explains how requests flow through the system, how the policy engine decides what to do, and how rooms and roles control which agents can take which actions.

## Request lifecycle

Every governed agent action follows the same path:

<Steps>
  <Step title="Agent calls a tool">
    Your coding agent, Claude Code, Cursor, VS Code Copilot, or any MCP-compatible tool, issues a tool call targeting a GitHub action. Common examples include creating a branch, pushing a commit, opening a pull request, or merging one.
  </Step>

  <Step title="Aegis intercepts over MCP SSE">
    The tool call arrives at Aegis via the MCP SSE endpoint at `https://app.runaegis.co/sse`. Aegis receives the full tool name, arguments, and the `user_id` header that identifies which account's policies to apply. No tool call reaches GitHub before Aegis evaluates it.
  </Step>

  <Step title="Policy engine evaluates the request">
    Aegis evaluates the tool call against your enabled policies in order. Policies check things like the target repository, the target branch, the tool being used, and the requesting agent's role within the room. The engine returns one of four decisions.
  </Step>

  <Step title="Decision is enforced">
    Aegis enforces the decision, executing the action, blocking it, rewriting it, or pausing it for human review, and records the outcome in the audit trail with a timestamp, the tool arguments, and the final result.
  </Step>
</Steps>

## The four decision types

Every tool call receives exactly one decision. The decision is determined by the first matching policy rule, evaluated in priority order.

<AccordionGroup>
  <Accordion title="ALLOW, action executes immediately" defaultOpen icon="circle-check">
    The tool call passes all policy checks and executes against GitHub without any interruption. The agent receives the result and continues normally. ALLOW decisions are logged in the audit trail with a `pass` policy verdict.

    Use ALLOW for repositories and operations where your team trusts the agent to act autonomously, for example, a feature branch on a low-risk repository.
  </Accordion>

  <Accordion title="DENY, action is blocked" icon="circle-xmark">
    The tool call matches a deny rule and is rejected before it reaches GitHub. The agent receives an error response. The action is logged with a `DENY` decision so you can review what was attempted and why it was blocked.

    Common deny scenarios include writes to a protected branch, actions on a repository you have set to **Deny** in permissions, or tool calls that match a specific policy you have enabled.
  </Accordion>

  <Accordion title="REWRITE, action is transformed to a safer path" icon="pen-to-square">
    Aegis modifies the tool call before forwarding it to GitHub. The most common rewrite converts a direct push to a protected branch into a pull request workflow: instead of force-pushing, Aegis opens a PR that a human can review and merge.

    The agent receives a response reflecting the rewritten outcome, for example, a PR URL rather than a push confirmation. Rewrites are logged with a `REWRITE` decision and the transformed arguments are visible in the audit trail.
  </Accordion>

  <Accordion title="REQUIRE_APPROVAL, action pauses for human review" icon="clock">
    The tool call is held by Aegis and not forwarded to GitHub until a team member approves or denies it from the dashboard. The agent enters a waiting state. Approvals appear in the **Approvals** section of the dashboard with the full tool name, arguments, a plain-language action summary, and (for PR-related tools) a link to the pull request.

    A human can approve the action in one click, after which Aegis executes it and returns the result to the agent. If denied, the agent receives an error. All approval events, including who acted and when, are recorded in the audit trail.
  </Accordion>
</AccordionGroup>

## Policy evaluation

Policies are rules that Aegis evaluates against each incoming tool call. When a tool call arrives, Aegis checks it against every enabled policy in order of priority. The first matching rule determines the decision. If no policy matches, the system falls back to the default permission you set for that repository during onboarding (Allow, Require Approval, or Deny).

Policies can match on:

* The **tool name**, for example, `push_files`, `create_pull_request`, `merge_pull_request`
* The **target repository**, matched against the per-repo permissions you configured
* The **target branch**, for example, blocking all writes to `main` or `production`
* The **agent role** within a room, OWNER, ADMIN, or DEVELOPER each have their own tool-level access controls

Changes to policies take effect immediately for all future tool calls. In-flight approval requests are not retroactively affected.

## Rooms: the access layer

A room corresponds to a single GitHub repository and is the unit of access control in Aegis. Before an agent can take governed actions on a repository, a room must exist for that repository.

Each room has:

* **Members** with one of three roles: `OWNER`, `ADMIN`, or `DEVELOPER`
* **Per-tool access controls** configured per role, you can allow or deny specific MCP tools for each role independently
* A **room ID** and **access token** used in the MCP configuration to scope the agent's access to that room

When a tool call arrives, Aegis looks up the room associated with the request, identifies the requesting user's role in that room, and applies the tool-level access controls for that role before evaluating any higher-level policies.

<Note>
  You must create a room before connecting an agent to a repository in production. The onboarding flow verifies basic MCP connectivity, but full per-repo governance requires a room. See the [Rooms documentation](/concepts/rooms) for setup details.
</Note>

## Dashboard and real-time updates

The Aegis dashboard displays live agent activity, pending approvals, and a summary of recent decisions. The dashboard auto-refreshes every 30 seconds so you always see current data without reloading.

Key dashboard views:

| View            | What you see                                                                    |
| --------------- | ------------------------------------------------------------------------------- |
| **Activity**    | All recent tool calls with decision, tool name, target repo, and timestamp      |
| **Approvals**   | Pending `REQUIRE_APPROVAL` actions waiting for your response                    |
| **Audit trail** | Full paginated history of every decision, filterable by tool, repo, and date    |
| **Sessions**    | Tool calls grouped by agent session, with per-session allow/deny/rewrite counts |
| **Rooms**       | Repositories under governance, member roles, and per-role tool permissions      |

## Architecture summary

```text theme={null}
Your agent (Claude Code / Cursor / VS Code Copilot)
        │
        │  MCP tool call (SSE)
        ▼
┌─────────────────────────────────────┐
│           Aegis policy engine       │
│                                     │
│  1. Identify user + room + role     │
│  2. Apply per-role tool controls    │
│  3. Evaluate enabled policies       │
│  4. Return decision                 │
└─────────────┬───────────────────────┘
              │
    ┌─────────┴──────────┐
    │                    │
 ALLOW / REWRITE      DENY / REQUIRE_APPROVAL
    │                    │
    ▼                    ▼
 GitHub API         Block or pause
                    (log + notify)
```

Every path through the engine produces an entry in the audit trail, regardless of outcome.