Concepts

Sessions

A sessionis FORG's unit for grouping a related sequence of AI tool calls by a single developer. Sessions provide the context for per-session cost attribution, policy scoping, and analytics aggregation.

Session lifecycle

Start — A session begins when an adapter emits a SessionStart hook, or when the first signal arrives after a timeout.
Active — While signals arrive within the session_timeout window (default: 1800 seconds), they are grouped into the current session.
End — A session ends when an adapter emits a SessionEnd hook, when the timeout expires, or when the user logs out of the tool.

Session attributes

Attribute	Description
`session_id`	Unique identifier, format: `sess_<12hex>`
`user_id`	Developer identity associated with this session
`project_id`	Project context (if provided by the adapter)
`adapter`	The tool adapter that generated the session
`started_at`	Timestamp of the first signal
`ended_at`	Timestamp of the last signal (or explicit end)
`total_cost_usd`	Sum of all signal costs in the session
`total_tokens_in`	Sum of input tokens across all signals
`total_tokens_out`	Sum of output tokens across all signals
`signal_count`	Number of AI calls made in the session

How savings are measured

FORG reports session savings in two distinct tiers so that a number is never inflated or fabricated. A healthy session that needed no intervention shows a dash (—) rather than $0.00.

Tier	What it counts	Units
Measured	Hard, observed savings from cache reuse and context compaction. Backed by real token deltas the engine recorded.	Tokens and dollars
Protection	Context kept healthy, drift held off, and rework avoided. These are estimates of waste that never happened.	Tokens only (with a ±35% range) — never expressed as dollars

Only the Measured tier is ever shown as a dollar figure. Protection is reported in tokens with an explicit estimate range, because attaching a precise price to avoided-waste would overstate certainty. When a tier has no value for a session, its row is hidden rather than shown as zero.

CSV export columns

Session and usage CSV exports carry both tiers as additive columns alongside the existing totals:

Column	Meaning
`tokens_saved`	Legacy total tokens saved (unchanged, kept for compatibility).
`savings_measured_usd`	Measured-tier dollar savings (cache reuse + compaction). Empty when no measured savings exist.
`protected_tokens_est`	Protection-tier estimated tokens (context, overflow, rework). Tokens only — never priced.

Session timeout

The session timeout controls how long of an inactivity gap is allowed before a new session is started. The default is 30 minutes (1800 seconds). Adjust in Dashboard → Settings → Sessions or via the config file:

{
  "session_timeout": 3600   // 1 hour
}

Session-scoped policies

Policies with scope: "session" evaluate the cumulative signal data within the current session. This is useful for per-task cost limits:

// Block if a single session exceeds $5
{
  "scope": "session",
  "condition": { "cost_usd": { "gt": 5 } },
  "action": "block"
}