Sessions - Enagrams

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.

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

{
  "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)

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

preToolUse Response (allow)

{
  "permission": "allow"
}

List Active Sessions

GET /workspaces/:id/sessions
Authorization: Bearer ek_...

Response

[
  {
    "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.

POST /workspaces/sessions/heartbeat
Authorization: Bearer ek_...

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

End Session

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.

​Overview

​Hook Endpoint

​Event Types

​sessionStart Response

​preToolUse Response (deny)

​preToolUse Response (allow)

​List Active Sessions

​Heartbeat

​End Session

​Session Expiry