Allowlist

Which detectors support it

• crashes — allowlist key is the exception_type (e.g. ValueError, RateLimitedRetry). Use this for known-harmless exception types your agent raises deliberately as a control signal.
• tool_failures — allowlist key is the tool_name. Use this for flaky third-party tools you would rather monitor manually, or known-best-effort tools whose failures don't indicate a real problem.
• validator_failures — allowlist key is the validator_name. Use this for validators that legitimately fail in expected ways (for example, an is_disposable_email check that intentionally fails for known throwaway addresses).

When to use the allowlist (vs the alternatives)

The allowlist is the right answer for known and accepted failures — failure shapes you have already triaged and decided don't require a page. It is NOT the right answer when:

• You want to tune sensitivity of a detector (e.g. raise the loop revisit count or lower the context-overflow cutoff). Use Detector thresholds instead.
• The flaky tool / validator should be deleted. Allowlisting a dead tool just papers over the code-cleanup work.
• You want to route failures to a softer alarm channel rather than silence them. Use Severity routing on the Settings page to downgrade a failure class from critical to warning or info.

How to manage entries (dashboard)

Go to Settings and scroll to the three Allowlist sections (one per consuming detector). Each section shows existing entries with their match count, dormant badge for entries that have never matched, and Add / Edit / Delete actions. The lifetime suppression count across all three detectors also surfaces on the main dashboard as the Allowlist suppressions tile (visible once you have at least one entry).

How to manage entries (API)

The REST surface is project-scoped (gated by the same API key as event ingest). Replace $DETECTOR with one of crashes, tool_failures, validator_failures.

# List entries for a detector
GET  /me/allowlist/$DETECTOR

# Create an entry
POST /me/allowlist/$DETECTOR
{ "allowlist_key": "ValueError",
  "reason": "We catch + retry these manually" }

# Update an entry
PATCH /me/allowlist/$DETECTOR/$ALLOWLIST_ID
{ "allowlist_key": "RateLimitedRetry",
  "reason": "..." }

# Delete an entry
DELETE /me/allowlist/$DETECTOR/$ALLOWLIST_ID

# Lifetime per-detector suppression stats
GET  /me/allowlist-stats

Server caps each project at 200 entries per detector; create requests above that limit return 429 Too Many Requests with a hint to delete an existing entry first. allowlist_key is capped at 200 characters and must not contain control characters; reason is capped at 500 characters and is optional.

Telemetry: dormant entries

Each entry shows a lifetime match_count — the number of failures the entry has suppressed since you created it. Entries with match_count = 0 render a dormant badge in the editor. Dormant entries either describe a failure shape you never actually see (safe to delete) or describe one that has stopped happening (also safe to delete). Pruning dormant entries keeps the allowlist readable and prevents accidental over- suppression when a similar-looking failure shape does come along later.

Failure modes

• Allowlist lookup fails at the database layer: detection fires normally. Silent suppression on a broken read would be the worst possible failure mode — you would lose detection coverage without seeing the cause. The server logs a warning instead.
• match_count increment fails after a successful match check: suppression decision is still honored; the telemetry counter just doesn't advance for that match. Server logs a warning.
• You allowlist a key that has historical failure_groups: existing groups remain untouched. The allowlist only affects future failures.

Related docs

• Detector thresholds — tune detection sensitivity instead of suppressing matches.
• Custom security patterns — the analogous primitive for the three security detectors (prompt_injection, data_leakage, sandbox_escape).