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

# Sessions

> Agent session management and hook endpoint

## Overview

Sessions track active coding agent conversations in a workspace. They're created and managed automatically by IDE hooks — you don't typically call these endpoints directly.

## Hook Endpoint

The primary endpoint. Handles all IDE hook events.

```bash theme={null}
POST /workspaces/sessions/hook
Authorization: Bearer ek_...

{
  "event": "sessionStart",
  "agent_type": "cursor",
  "workspace_slug": "my-startup",
  "conversation_id": "conv_abc123",
  "task": "Build user authentication"
}
```

### Event Types

| Event                                     | IDE                         | Effect                                    |
| ----------------------------------------- | --------------------------- | ----------------------------------------- |
| `sessionStart` / `SessionStart`           | Cursor / Claude Code, Codex | Creates session, returns context briefing |
| `preToolUse` / `PreToolUse`               | Cursor / Claude Code        | Checks file reservation, may deny write   |
| `postToolUse` / `PostToolUse`             | Cursor / Claude Code        | Reserves file for this conversation       |
| `beforeSubmitPrompt` / `UserPromptSubmit` | Cursor / Claude Code, Codex | Captures task text                        |
| `sessionEnd` / `SessionEnd` / `Stop`      | Cursor / Claude Code, Codex | Releases reservations, ends session       |
| `file_check`                              | Any                         | Updates heartbeat                         |

### sessionStart Response

```json theme={null}
{
  "session_id": "sess_xyz",
  "additional_context": "Team briefing:\n\nActive agents:\n  - Developer B (Cursor): Build JWT auth flow\n\nLocked files:\n  - src/auth/login.ts (Developer B)\n\nRecent decisions:\n  - Use JWT for auth (Developer B, 5 min ago)"
}
```

The `additional_context` field is injected as system context by the IDE.

### preToolUse Response (deny)

```json theme={null}
{
  "permission": "deny",
  "message": "File src/auth/login.ts is reserved by Developer B — 'Build JWT auth flow' (6 min remaining)"
}
```

### preToolUse Response (allow)

```json theme={null}
{
  "permission": "allow"
}
```

***

## List Active Sessions

```bash theme={null}
GET /workspaces/:id/sessions
Authorization: Bearer ek_...
```

**Response**

```json theme={null}
[
  {
    "id": "sess_abc",
    "user_name": "Developer A",
    "agent_type": "cursor",
    "current_task": "Build JWT auth flow",
    "current_file": "src/auth/login.ts",
    "branch": "feat/auth",
    "conversation_id": "conv_xyz",
    "last_heartbeat": "2026-04-13T10:30:00Z",
    "reserved_files": ["src/auth/login.ts", "src/auth/middleware.ts"]
  }
]
```

***

## Heartbeat

Keep a session alive.

```bash theme={null}
POST /workspaces/sessions/heartbeat
Authorization: Bearer ek_...

{
  "workspace_slug": "my-startup",
  "session_id": "sess_abc"
}
```

***

## End Session

```bash theme={null}
POST /workspaces/sessions/end
Authorization: Bearer ek_...

{
  "workspace_slug": "my-startup",
  "session_id": "sess_abc"
}
```

Releases all file reservations for the session.

***

## Session Expiry

Sessions auto-expire after **5 minutes** of inactivity (no hook events). File reservations auto-expire after **10 minutes** of inactivity.