Sessions
The durable runtime unit AGH creates, resumes, audits, and governs.
- Audience
- Operators running durable agent work
- Focus
- Sessions guidance shaped for scanability, day-two clarity, and operator context.
A session is the unit AGH actually manages. It binds one agent subprocess to a workspace, permission policy, event store, and resume record under one stable AGH session ID.
Session-scoped Vault refs use vault:sessions/<session_id>/<name>. They are ordinary encrypted
Vault records filtered by the session prefix, and the session inspector shows only redacted metadata
for those refs.
Use this section when a live run needs supervision or forensic detail: why it started, what state it entered, which events were persisted, whether it can resume, and which permission checks apply while the agent works. If the problem is choosing an agent definition, use Agents first. If the problem is the daemon or database itself, use Operations after you identify the affected session.
The reading order follows the lifecycle. Start with lifecycle for state names and stop classification, move to events when you need the durable record, then use resume and permissions for the two most common operator questions: "can this continue?" and "why did AGH ask before acting?"
In this section
Lifecycle
Create, activate, stop, and classify sessions
Use this page for the state machine, stop behavior, timeout boundaries, and what AGH persists across the session lifetime.
Health
Session presence, attachability, and wake eligibility
Use this page for metadata-only health, the authority boundary against task-run leases and HEARTBEAT.md, and the session health/status/inspect CLI/API surfaces.
Resume
Resume stopped sessions and replay stored work
Use this page to understand ACP `session/load`, fresh-start fallback, transcript reconstruction, and when resume will fail.
Events
Query, stream, and persist session events
Use this page for the event catalog, SSE behavior, SQLite storage, and the difference between persisted streams and prompt streams.
Permissions
Static modes, workspace boundaries, and approval flow
Use this page to understand what `deny-all`, `approve-reads`, and `approve-all` actually permit and how interactive approvals work.
Vault
Session-scoped secret metadata
Use this page when a session needs write-only encrypted refs such as `vault:sessions/<session_id>/<name>`.