Blocking and trailing review

Watcher reviews a running session in two lanes. Blocking review evaluates tool calls before they run and can stop them. Trailing review grades the session's trajectory as it grows and surfaces findings after the fact. The dividing line: if a single action could cause irreversible harm, it belongs to blocking review; patterns that emerge across turns belong to trailing review.

Blocking review runs from the Watcher client on the developer's machine and is configured through the client's settings: which graders run, the thresholds, and the enforcement mode. These resolve on each machine, but they do not have to be set machine by machine: admins can distribute and lock them across the organization with managed settings. Trailing review runs on the Watcher server, over the sessions the client has ingested, and needs no client configuration.

Blocking review

Blocking review evaluates tool calls the coding agent proposes before they run. Coverage depends on the agent: with Claude Code, every tool call is evaluated; with Codex, review runs through the agent's approval flow, so a call Codex does not ask about executes without a pre-execution decision (it is still recorded, and graded after the fact). Codex asks about the commands it considers dangerous, and about anything that needs to reach outside its sandbox — which is why Watcher keeps that sandbox on when it is enforcing. Because the agent is paused while a call is evaluated, the pipeline is staged from fastest to slowest, and most calls never reach the slow stages:

1. Terminal thresholds. A tool whose thresholds are set to a terminal value is decided instantly: always-allow (both thresholds disabled), always-deny, or always-flag. These outrank everything that follows, including command rules: setting a tool to always-allow also switches off that tool's command rules, deny rules included.
2. Command rules. Instant allow/deny list matching.
3. Triage. A fast, cheap grader scores the call. Triage can only auto-approve: a low-scoring call proceeds immediately, and anything else falls through to deep review. It never denies or escalates.
4. Deep review. The gateway grader scores the call from 1 to 10. The score is compared against the tool's configured thresholds: at or above the deny threshold the call is denied, at or above the flag threshold it is escalated, otherwise it is allowed.
5. Human escalation. An escalated call waits for a person: the developer approves or denies it in the Watcher client's UI, or answers the coding agent's own permission prompt, whichever comes first.

Every outcome is recorded as a decision on the session, so escalations and denials are visible in the Analyzer transcript afterwards. If grading fails or exceeds its time budget, Watcher applies the configured failure decision: escalate (the default: a human decides, via the Watcher client's UI or the coding agent's own permission prompt), deny, or allow. Transient failures (the grading service being unavailable, an empty grading result) are retried first, once by default; other failures, such as authentication errors or a transcript too long for the grading model, apply the decision immediately. A grade that runs out of time is not retried: one attempt may use the whole time budget, so there is nothing left to retry with, and a grader slow enough to exhaust it would only be slow again. The one exception is when an SSO-mode machine with no stored sign-in credentials gets a 401 from grading: that call is blocked with a sign-in prompt instead. Any other failure kind on such a machine still follows the configured decision above.

Enforcement modes

The client's enforcement mode controls what blocking review does with its judgments:

• Enforce. Decisions take effect: denials block the call, escalations wait for a human.
• Observe. The pipeline still grades calls and records what it would have decided, but never intervenes (with Codex, observe-mode grading happens after each call has run). Useful for tuning thresholds before turning enforcement on.
• Paused. LLM grading stops, but deterministic checks still apply: a command rule or an always-deny tool threshold still denies. Calls that would have needed grading or escalation fall through to the coding agent's own permission flow.

Trailing review

Trailing review runs asynchronously on the Watcher server, on a periodic schedule over recently active sessions — nothing on the developer's machine triggers or configures it. Two built-in jobs run today:

• Summaries. The built-in Summarize grader produces a title and short summary for each session: an early first summary while the session is still active, an updated one once it goes quiet, and periodic refreshes for sessions that never go quiet.
• Deep review. Sessions the blocking pipeline scored highly get a second, more thorough security review once they settle.

Trailing review never blocks the agent and never feeds anything back into the agent's context. Its grades appear in the Analyzer, alongside grades from any other grader. Sessions whose scores reach your organization's flag threshold are flagged for review and can trigger a Slack notification (see organization settings).

What drives the schedule when you self-host

A xylon-grading-scheduler container triggers trailing review every five minutes by default. It asks the API to grade each organization's recent sessions. The API performs the grading; the scheduler reads no session content, holds no provider keys, and contacts no provider. It runs the xylon-api image with a different entrypoint, so it is not a separate image to deploy or review.

The scheduler is the only component that triggers trailing review. The async-grading Compose profile starts it, and .env.example enables the profile for new installs. Without the scheduler, a deployment records sessions but never grades them. See Update Watcher for update instructions.

Choosing what goes where

	Blocking review	Trailing review
Evaluates	one tool call, before it runs	the trajectory so far
Can interrupt the agent	yes	no
Latency budget	seconds; the agent is paused	generous; runs behind the session
Suited to	irreversible single actions: destructive commands, secret exposure, dangerous infrastructure changes	cross-turn patterns: wrong diagnoses, premature completion claims, ignored instructions, scope creep
Results appear in	the Watcher client (live) and the Analyzer (as decisions)	the Analyzer (as grades)