---
description: >-
  The Watcher vocabulary: sessions, trajectories, graders, blocking vs. trailing review, and organization settings.
---

> Part of the Watcher docs. Index of all pages, with summaries: https://watcher-docs.apolloresearch.ai/llms.txt
> Before upgrading Watcher, read the release pages and full changelogs for every version crossed: https://watcher-docs.apolloresearch.ai/releases/index.md
> Found an issue with this page? Report it: https://github.com/ApolloResearch/watcher-bin/issues/new?title=Docs%20feedback%3A%20Concepts&body=Page%3A%20Concepts%0AURL%3A%20https%3A%2F%2Fwatcher-docs.apolloresearch.ai%2Fconcepts%2F%0A%0A

# Concepts

This page is the glossary for the Watcher vocabulary used across these docs,
linking to the full concept page where one exists.

| Term | Definition |
| --- | --- |
| Session | One recorded interaction with a coding agent, such as a single [Claude Code or Codex](../supported-agents.md) conversation on a developer's machine. A session contains one or more trajectories. See [Sessions and trajectories](sessions-and-trajectories.md). |
| Trajectory | One linear path through a session's conversation: an unbroken chain of messages ending at one of the session's latest messages. Graders review trajectories. See [Sessions and trajectories](sessions-and-trajectories.md). |
| Grader | A versioned grading rubric: a prompt plus score dimensions that an LLM applies to a trajectory, producing a grade: one value per dimension, plus optional explanation and summary text. Watcher ships built-in graders, and you can create your own. See [Graders](graders.md). |
| Managed monitor | A grader Watcher manages end to end, prompt and model included, addressed by role rather than by ID and updated with Watcher releases. An organization shapes managed monitors with custom instructions instead of editing them; the Analyzer calls an organization's own graders custom monitors to distinguish them. See [Graders](graders.md#monitors). |
| Severity | A score band: low (1-3), medium (4-6), high (7-8), or critical (9-10). Sessions use the latest deep-review verdict; tool calls use the gateway score, or triage when applicable; missing scores are not a low-severity verdict (see [Analyzer severity](analyzer.md#severity)). |
| Blocking review | Review of a tool call before it runs. The outcome allows the call, denies it, or escalates it to a human for approval. See [Blocking and trailing review](blocking-and-trailing-review.md). |
| Tool threshold | A per-tool pair of scores, flag and deny, that blocking review compares a grader's score against. A pair set to a terminal value decides the call without grading; a tool with no entry of its own uses the `unknown` fallback pair. See [Blocking and trailing review](blocking-and-trailing-review.md#blocking-review). |
| Command rule | A regular expression, scoped to one tool name or a glob, matched against a tool call's command text, file path or other arguments before any grader runs. A match allows the call, denies it, escalates it to a human, or sends it to grading. See [Blocking and trailing review](blocking-and-trailing-review.md#blocking-review). |
| Triage | Blocking review's fast, cheap grading stage. It can only auto-approve a low-scoring call; anything else goes on to gateway review. Its managed monitor role is `triage`. See [Blocking review](blocking-and-trailing-review.md#blocking-review). |
| Gateway review | Blocking review's deciding grading stage. The gateway grader scores the call from 1 to 10 and the tool's thresholds turn that score into allow, deny, or escalate. Its managed monitor role is `gateway`. See [Blocking review](blocking-and-trailing-review.md#blocking-review). |
| Trailing review | Server-side grading that follows ingested sessions: summaries while a session runs and after it settles, plus a deeper security review of highly scored sessions. See [Blocking and trailing review](blocking-and-trailing-review.md). |
| Deep Review | Trailing review's second, more thorough security grade of a session the blocking pipeline scored highly. It runs on the server after the session settles and drives session severity. Its monitor role is `deep_review`. See [Trailing review](blocking-and-trailing-review.md#trailing-review). |
| Subagent coverage | Review of subagent tool calls through the coding agent's hooks. Coverage depends on which calls the agent sends for review and does not imply a complete record of the subagent's conversation. See [Subagent coverage](subagent-coverage.md). |
| Organization settings | Org-wide configuration managed by admins in the Analyzer, such as Slack notifications for flagged sessions. See [Organization settings](organization-settings.md). |
| Admin audit log | An append-only file on a self-hosted deployment recording admin access to other users' session data, organization-level writes, and system-attributed retention scrubs, one JSON line per event. See [Operations](../self-hosting/operations.md#admin-audit-log). |
| Analyzer | Watcher's web dashboard: where your team reviews sessions and tool calls with their grades, works on graders, and where admins manage organization settings. See [Analyzer](analyzer.md). |
| Login agent | The per-user background service that starts the Watcher client on login and keeps it running: a LaunchAgent on macOS, a systemd user unit on Linux. Installed by the first plain `watcher` run, or by `watcher autostart install`. See [Client](../client/index.md#command-reference). |
| Gateway hook | An API integration that sends a conversation and tool call to Watcher for evaluation and recording without a client on the developer's machine. Enforcement-capable callers apply returned decisions according to the configured enforcement mode; Aperture only observes. See [Gateway hooks](../api/hooks.md). |
| Session source | How a session's messages reached Watcher, shown as badges and as the Source filter in the [Analyzer](analyzer.md): Watcher Live for the Watcher client, Aperture for Tailscale Aperture, or one of three labels for other gateway hooks. **Gateway** marks a session whose conversation ID starts with a gateway example's prefix, such as `litellm:`. **Watcher SDK** marks a registered SDK coding agent's prefix, such as `github-copilot-cli:`. **Hooks API** covers any other ID or none, including your own agent sending gateway hooks through the Watcher SDK with its own conversation ID. The labels affect display and filtering only. See [ingestion sources](../api/python-sdk.md#filter-by-ingestion-source). |
| Watcher API | The HTTP interface your deployment serves for programmatic access to sessions, trajectories, grades, and graders. See [API](../api/index.md). |
| Watcher client | The program installed on each developer machine. It hooks into coding agents ([Claude Code, Codex](../supported-agents.md)) to record sessions, upload them to your Watcher deployment, and enforce blocking review. See [Client](../client/index.md) for installing and using it. |
| Supported agents | The coding-agent environments Watcher integrates with. [Supported agents](../supported-agents.md) lists local integrations and the Aperture agent/provider support table. |
| Enforcement mode | The administrator's setting that selects enforce, observe, or paused behavior for the Watcher client and gateway hooks. Paused clients retain deterministic checks; paused gateway hooks ingest transcripts without evaluating calls. See [Blocking and trailing review](blocking-and-trailing-review.md#enforcement-modes) and [Gateway hooks](../api/hooks.md#enforcement-modes). |
| Snooze | Temporarily skips LLM grading without changing the enforcement mode. Command rules still run. See [Snoozing](blocking-and-trailing-review.md#snoozing). |
| Managed client settings | An admin-authored overlay of Watcher client settings, edited in the Analyzer and delivered to developer machines by client pull (when distribution via Watcher is on) or by your MDM, with per-value locking. See [Organization settings](organization-settings.md#managed-client-settings). |
| Settings profile | A named bundle of the Watcher client's review settings that is switched as a unit, such as the built-in Default and Human in the Loop profiles. See [Client](../client/index.md#per-machine-settings). |
| `.watcher-ignore` | A file a developer puts in a directory to keep the coding-agent sessions started there from being uploaded to the deployment or LLM-graded. Honored only where an administrator has enabled it, and it does not stop deterministic blocking review. See [Excluding a directory with .watcher-ignore](../client/watcher-ignore.md). |
| Red-team drill | A prompt an admin downloads from the Analyzer and sends to a developer, whose AI assistant uses it to turn enforcement on for that one machine, probe an agreed threat model, and restore the machine. See [Organization settings](organization-settings.md#red-team-drill). |