Skip to main content

​
Overview

Emergency bypass lets an authorized operator temporarily suspend enforcement of one retrieval rule when a critical situation requires immediate access to context that rule is suppressing. Every bypass is bounded (15 minutes to 2 hours), requires a written reason, and is fully audited — activation, every decision made through the bypassed rule, and deactivation all land in the audit log with the reason code EMERGENCY_BYPASS. Emergency bypass is a safety valve, not a workflow. It exists for scenarios where a rule would prevent an agent from accessing information needed to resolve an urgent incident.

​
When to Use Emergency Bypass

  • A production incident requires an agent to access documents a rule is suppressing, right now
  • A security investigation needs an agent to review suppressed context for threat analysis
  • A misconfigured rule is denying context that should be allowed, and you need relief while you fix it
Emergency bypass should never be used as a routine workflow. If you find yourself bypassing frequently, the rule itself needs adjustment — frequent bypass usage is a signal that your policy configuration does not match your operational reality.

​
How It Works

1

Operator activates bypass on one rule

An operator with the recall_rules:bypass permission calls the bypass endpoint for a specific rule, with a mandatory reason (at least 10 characters) and a duration of exactly 15, 30, 60, or 120 minutes. Activating a rule that already has an active bypass returns 409 Conflict.
2

That rule stops enforcing

While the bypass is active, any request that reaches the bypassed rule in the priority cascade returns allow with the reason code EMERGENCY_BYPASS and your reason string. Only that one rule is suspended — higher-priority rules evaluate first and keep enforcing normally throughout the window.
3

Everything is audited, fail-closed

Activation and deactivation are first-class audit operations, and the bypass fails if its audit entry cannot be written — you cannot bypass without leaving a record. Each decision allowed through the bypassed rule is logged with reason_code: "EMERGENCY_BYPASS" and the rule’s ID.
4

Bypass expires or is deactivated

Expiry is checked at decision time — no background job is involved, so there is no window where a stuck process leaves a bypass open past its deadline. The operator can also deactivate early with a DELETE; deactivating a rule with no active bypass returns 409 Conflict. Either way, the transition back to normal enforcement is immediate.

​
Activating and Deactivating

Bypass is controlled per rule via the REST API. Both calls require an operator whose role grants the dedicated recall_rules:bypass permission — separate from rule editing, so you can restrict who may pull the emergency lever. Harness (agent) keys cannot call these endpoints.
Both calls return the updated rule, including its bypass state: bypass_active, bypass_reason, bypass_activated_by, bypass_activated_at, and bypass_expires_at. While a bypass is active, the rule shows a Bypass active badge in the dashboard’s retrieval rules view.

​
Audit Trail

Three kinds of entries record a bypass, all in the retrieval audit log: Activation — operation: "emergency_bypass_activate", with metadata: Decisions during the window — normal decision entries whose decision is allow, whose reason_code is EMERGENCY_BYPASS, whose reason is the operator’s reason string, and whose rule_id is the bypassed rule. Requests decided by other (non-bypassed) rules during the window carry their normal reason codes. Deactivation — operation: "emergency_bypass_deactivate", with metadata recording deactivated_by plus the original bypass details (original_reason, original_activated_by, original_activated_at, original_expires_at, rule_name). Example activation entry:
Bypass decisions flow through the same audit pipeline as every other decision — record envelopes with asynchronous Ed25519-signed receipts when artifact signing is enabled for your organization. See Receipts.

​
Querying Bypass Events

Use the audit log API for post-incident review:
This supports:
  • Post-incident reviews to understand exactly what data was accessed during the window
  • Compliance reporting to demonstrate that every bypass is documented, justified, and time-bounded
  • Trend analysis — repeated bypasses of the same rule mean the rule needs fixing

​
Best Practices

Write a real reason

The API enforces a minimum length, but make the reason genuinely useful: reference an incident number, ticket, or specific operational justification. It becomes the reason on every decision allowed through the bypassed rule.

Bypass only the blocking rule

Bypass is deliberately scoped to a single rule — identify which rule is actually denying the context and bypass that one. If the rule is simply wrong, fix the rule instead of repeatedly bypassing it.

Pick the shortest window

Choose the smallest duration that covers the need — 15 minutes is often enough. Deactivate manually the moment the incident no longer needs the access; don’t wait for auto-expiry.

Review after incidents

After every bypass, query both the activation events and the EMERGENCY_BYPASS decisions to see what was accessed. Use the review to decide whether the rule needs adjustment to prevent the next bypass.